Package: tsvarana
Tsvarana|||AboutTsvaranaperforms (t)ime(s)eries (var)iance (ana)lysis for fMRI data, written in Python 3. It is a diagnostic tool intended to detect abnormal fluctuations in MRI signals, that you may wish to remove from further analysis.The logic behind Tsvarana is based on a simple observation: abnormal signal intensities in fMRI data caused by non-physiological sources of noise stand out by being very different from the median signal intensity across a timeseries. A well-designed fMRI experiment will elicit BOLD signal fluctuations in the order of 1-4% signal change, with changes outside this range likely attributable to non-physiological sources of noise. Thus, by computing the voxelwise variance between signal intensity at every timepoint against the median signal intensity, we can detect abnormal voxels, slices or volumes for further inspection or removal.Tsvarana is a spiritual successor totsdiffana, written byMatthew Brett. The two tools differ in some important aspects. First, signal assessment is carried out by comparing the signal variance in the time domain against the median signal amplitude. This approach is preferable to a sliding window approach, as it is more robust to cases of sustained abnormal intensities spanning consecutive timepoints. Second, timepoint removal or 'scrubbing' is performed iteratively. The iteration algorithm is defined as follows; (a) check all timepoint-to-median variances against a user-defined maximum variance threhold, (b) remove all timepoints failing the test, (c) replace removed timepoints with the mean of the first preceeding and first following retained timepoints, where available. Steps (a)-(c) are repeated until no further timepoints are marked for removal.Tsvarana is experimental software and is provided with no warranty of any kind.InstallationInstall withpippip install tsvaranaTsvarana has the following dependencies:NumPy,SciPy,Bokeh,NibabelUsageThere are two ways to use Tsvarana. To perform a basic timeseries variance analysis and scrubbing, you can invoke tsvarana from the shell withpython-mtsvarana--data<4d_nifti>Alternatively, you can use the tsvarana library from within a Python environmentimporttsvaranaSee below for a step-by-step tutorial.Tutorial# Load libraryimporttsvarana# Start by loading a 4D BOLD timeseries to the workspace. We will use the nibabel library for this# This example dataset contains (x,y,z,t) dimensionsimportnibabelasnibheader=nib.load('my_4D_data.nii.gz')data=header.get_fdata()# Define a variance analysis objectvarana=tsvarana.classes.varana()# First, we will define the spatial unit. Variance will be calculated at the specified spatial level,# which can be 'voxel', 'slice' or 'volume'. If slice is selected, you must specify the dimension# axis along which slices are taken# For our example dataset with (x,y,z,t) dimensions, we'll pick slices along the z dimensionvarana.spatial_unit='slice'varana.slice_axis=2# We can also modify the axis along which time is stored# In our example of (x,y,z,t) data, that will be the 3rd axisvarana.time_axis=3# Next, define the variance threshold, expressed in normalised variance units# A value in the range of 5-10 is a reasonable starting point for fMRI data# Note this threshold must be selected while considering the nature of your data acquisition# protocol, and the type of signal abnormalities you wish to detectvarana.var_threshold=5# Perform diagnostics# Calculate the timepoint-to-median variance using the settings specified above, and compare the# empirical normalised variance against the previously-specified variance thresholdvarana.detect(data)# Plot the resulting variance diagnosticstsvarana.plot_diagnostic(varana,show=True)# Perform iterative scrubbing# This step iterates the timepoint removal algorithm, until no timepoints display normalised# variance-to-median above the specified threshold. Note that timepoints removed are replaced# with the mean of the first valid preceeding and first valid following timepoint. If ony one# is valid, a copy of that timepoint is used for replacementvarana.scrub_iterative(data)# Plot every step of the diagnostic variance calculation# This will create a HTML page, containing one figure for each iteration passtsvarana.plot_diagnostic(varana,outfile='variance.html')# Plot every step of the binary thresholding# As above, This will make one figure for each iteration passtsvarana.plot_regressor(varana,outfile='regressors.html')# We can also obtain a regressor matrix, with all timepoints excluded flagged as 1s and timepoints# that were never excluded as 0sregressor=varana.get_final_regressor()# Finally, we pull out the scrubbed timeseries data, and save it to a NIFTI filedata_scrub=varana.get_data_scrub()img=nib.Nifti1Image(data_scrub,header.affine)nib.save(img,'my_scrubbed_data.nii.gz')DevelopmentTsvarana was created and maintained byIvan Alvarez. To see the code or report a bug, please visit theGitHub repository.