rapidtide
Description:
The central program in this package is rapidtide. This is the program that calculates a similarity function between a “probe” signal and every voxel of a BOLD fMRI dataset. It then determines the peak value, time delay, and wi dth of the similarity function to determine when and how strongly that probe signal appears in each voxel.
At its core, rapidtide is simply performing a full crosscorrelation between a “probe” timecourse and every voxel in an fMRI dataset (by “full” I mean over a range of time lags that account for any delays between the signals, rather than only at zero lag, as in a Pearson correlation). As with many things, however, the devil is in the details, and so rapidtide provides a number of features which make it pretty good at this particular task. A few highlights:
There are lots of ways to do something even as simple as a cross-correlation in a nonoptimal way (not windowing, improper normalization, doing it in the time rather than frequency domain, etc.). I’m pretty sure what rapidtide does by default is, if not the best way, at least a very good and very fast way.
rapidtide has been optimized and profiled to speed it up quite a bit; it has an optional dependency on numba – if it’s installed, some of the most heavily used routines will speed up significantly due to judicious use of @jit.
The sample rate of your probe regressor and the fMRI data do not have to match - rapidtide resamples the probe regressor to an integral multiple of the fMRI data rate automatically.
The probe and data can be temporally prefiltered to the LFO, respiratory, or cardiac frequency band with a command line switch, or you can specify any low, high, or bandpass range you want.
The data can be spatially smoothed at runtime (so you don’t have to keep smoothed versions of big datasets around). This is quite fast, so no reason not to do it this way.
rapidtide can generate a probe regressor from the global mean of the data itself - no externally recorded timecourse is required. Optionally you can input both a mask of regions that you want to be included in the mean, and the voxels that you want excluded from the mean (there are situations when you might want to do one or the other or both).
Determining the significance threshold for filtered correlations where the optimal delay has been selected is nontrivial; using the conventional formulae for the significance of a correlation leads to wildly inflated p values. rapidtide estimates the spurious correlation threshold by calculating the distribution of null correlation values obtained with a shuffling procedure at the beginning of each run (the default is to use 10000 shuffled correlations), and uses this value to mask the correlation maps it calculates. As of version 0.1.2 it will also handle two-tailed significance, which you need when using bipolar mode.
rapidtide can do an iterative refinement of the probe regressor by aligning the voxel timecourses in time and regenerating the test regressor.
rapidtide fits the peak of the correlation function, so you can make fine grained distinctions between close lag times. The resolution of the time lag discrimination is set by the length of the timecourse, not the timestep – this is a feature of correlations, not rapidtide.
Once the time delay in each voxel has been found, rapidtide outputs a 4D file of delayed probe regressors for using as voxel specific confound regressors or to estimate the strength of the probe regressor in each voxel. This regression is performed by default, but these outputs let you do it yourself if you are so inclined.
I’ve put a lot of effort into making the outputs as informative as possible - lots of useful maps, histograms, timecourses, etc.
There are a lot of tuning parameters you can mess with if you feel the need. I’ve tried to make intelligent defaults so things will work well out of the box, but you have the ability to set most of the interesting parameters yourself.
Inputs:
At a minimum, rapidtide needs a data file to work on (space by time), which is generally thought to be a BOLD fMRI data file. This can be Nifti1 or Nifti2 (for fMRI data, in which case it is time by up to 3 spatial dimensions) or a whitespace separated text file (for NIRS data, each column is a time course, each row a separate channel); I can currently read (probably) but not write Cifti files, so if you want to use grayordinate files you need to convert them to nifti2 in workbench, run rapidtide, then convert back. As soon as nibabel finishes their Cifti support (EDIT: and I get around to figuring it out), I’ll add that.
The file needs one time dimension and at least one spatial dimension. Internally, the array is flattened to a time by voxel array for simplicity.
The file you input here should be the result of any preprocessing you intend to do. The expectation is that
rapidtide will be run as the last preprocessing step before resting state or task based analysis. So any slice
time correction, motion correction, spike removal, etc. should already have been done. If you use FSL, this
means that if you’ve run preprocessing, you would use the filtered_func_data.nii.gz file as input. Temporal
and spatial filtering are the two (partial) exceptions here. Generally rapidtide is most useful for looking
at low frequency oscillations, so when you run it, you usually use the --filterband lfo
option or some
other to limit the analysis to the detection and removal of low frequency systemic physiological oscillations.
So rapidtide will generally apply it’s own temporal filtering on top of whatever you do in preprocessing.
Also, you have the option of doing spatial smoothing in rapidtide to boost the SNR of the analysis; the
hemodynamic signals rapidtide looks for are often very smooth, so you rather than smooth your functional
data excessively, you can do it within rapidtide so that only the hemodynamic data is smoothed at that level.
Outputs:
Outputs are space or space by time NIFTI or text files, depending on what the input data file was, and some text files containing textual information, histograms, or numbers. File formats and naming follow BIDS conventions for derivative data for fMRI input data. Output spatial dimensions and file type match the input dimensions and file type (Nifti1 in, Nifti1 out). Depending on the file type of map, there can be no time dimension, a time dimension that matches the input file, or something else, such as a time lag dimension for a correlation map.
BIDS Outputs:
Name |
Extension(s) |
Content |
When present |
---|---|---|---|
XXX_maxtime_map |
.nii.gz, .json |
Time of offset of the maximum of the similarity function |
Always |
XXX_desc-maxtime_hist |
.tsv, .json |
Histogram of the maxtime map |
Always |
XXX_maxcorr_map |
.nii.gz, .json |
Maximum similarity function value (usually the correlation coefficient, R) |
Always |
XXX_desc-maxcorr_hist |
.tsv, .json |
Histogram of the maxcorr map |
Always |
XXX_maxcorrsq_map |
.nii.gz, .json |
Maximum similarity function value, squared |
Always |
XXX_desc-maxcorrsq_hist |
.tsv, .json |
Histogram of the maxcorrsq map |
Always |
XXX_maxwidth_map |
.nii.gz, .json |
Width of the maximum of the similarity function |
Always |
XXX_desc-maxwidth_hist |
.tsv, .json |
Histogram of the maxwidth map |
Always |
XXX_MTT_map |
.nii.gz, .json |
Mean transit time (estimated) |
Always |
XXX_corrfit_mask |
.nii.gz |
Mask showing where the similarity function fit succeeded |
Always |
XXX_corrfitfailreason_map |
.nii.gz, .json |
A numerical code giving the reason a peak could not be found (0 if fit succeeded) |
Always |
XXX_desc-corrfitwindow_info |
.nii.gz |
Values used for correlation peak fitting |
Always |
XXX_desc-runoptions_info |
.json |
A detailed dump of all internal variables in the program. Useful for debugging and data provenance |
Always |
XXX_desc-lfofilterCleaned_bold |
.nii.gz, .json |
Filtered BOLD dataset after removing moving regressor |
If GLM filtering is enabled (default) |
XXX_desc-lfofilterRemoved_bold |
.nii.gz, .json |
Scaled, voxelwise delayed moving regressor that has been removed from the dataset |
If GLM filtering is enabled (default) and |
XXX_desc-lfofilterEVs_bold |
.nii.gz, .json |
Voxel specific delayed sLFO regressors used as EVs for the GLM |
If GLM filtering is enabled (default) and |
XXX_desc-lfofilterCoeff_map |
.nii.gz, .json |
Magnitude of the delayed sLFO regressor from GLM filter |
If GLM filtering is enabled (default) |
XXX_desc-lfofilterMean_map |
.nii.gz, .json |
Mean value over time, from GLM fit |
If GLM filtering is enabled (default) |
XXX_desc-lfofilterNorm_map |
.nii.gz, .json |
GLM filter coefficient, divided by the voxel mean over time |
If GLM filtering is enabled (default) |
XXX_desc-lfofilterR_map |
.nii.gz, .json |
R value for the GLM fit in the voxel |
If GLM filtering is enabled (default) |
XXX_desc-lfofilterR2_map |
.nii.gz, .json |
R value for the GLM fit in the voxel, squared. Multiply by 100 to get percentage variance explained |
If GLM filtering is enabled (default) |
XXX_desc-CVR_map |
.nii.gz, .json |
Cerebrovascular response, in units of % BOLD per unit of the supplied regressor (probably mmHg) |
If CVR mapping is enabled |
XXX_desc-CVRR_map |
.nii.gz, .json |
R value for the CVR map fit in the voxel |
If CVR mapping is enabled |
XXX_desc-CVRR2_map |
.nii.gz, .json |
R value for the CVR map fit in the voxel, squared. Multiply by 100 to get percentage variance explained |
If CVR mapping is enabled |
XXX_desc-processed_mask |
.nii.gz |
Mask of all voxels in which the similarity function is calculated |
Always |
XXX_desc-globalmean_mask |
.nii.gz |
Mask of voxels used to calculate the global mean signal |
This file will exist if no external regressor is specified |
XXX_desc-refine_mask |
.nii.gz |
Mask of voxels used in the last estimate a refined version of the probe regressor |
Present if passes > 1 |
XXX_desc-shiftedtcs_bold |
.nii.gz |
The filtered input fMRI data, in voxels used for refinement, time shifted by the negated delay in every voxel so that the moving blood component should be aligned. |
Present if passes > 1 and |
XXX_desc-despeckle_mask |
.nii.gz |
Mask of the last set of voxels that had their time delays adjusted due to autocorrelations in the probe regressor |
Present if despecklepasses > 0 |
XXX_desc-corrout_info |
.nii.gz |
Full similarity function over the search range |
Always |
XXX_desc-gaussout_info |
.nii.gz |
Gaussian fit to similarity function peak over the search range |
Always |
XXX_desc-autocorr_timeseries |
.tsv, .json |
Autocorrelation of the probe regressor for each pass |
Always |
XXX_desc-corrdistdata_info |
.tsv, .json |
Null correlations from the significance estimation for each pass |
Present if |
XXX_desc-nullsimfunc_hist |
.tsv, .json |
Histogram of the distribution of null correlation values for each pass |
Present if |
XXX_desc-plt0p050_mask |
.nii.gz |
Voxels where the maxcorr value exceeds the p < 0.05 significance level |
Present if |
XXX_desc-plt0p010_mask |
.nii.gz |
Voxels where the maxcorr value exceeds the p < 0.01 significance level |
Present if |
XXX_desc-plt0p005_mask |
.nii.gz |
Voxels where the maxcorr value exceeds the p < 0.005 significance level |
Present if |
XXX_desc-plt0p001_mask |
.nii.gz |
Voxels where the maxcorr value exceeds the p < 0.001 significance level |
Present if |
XXX_desc-globallag_hist |
.tsv, .json |
Histogram of peak correlation times between probe and all voxels, over all time lags, for each pass |
Always |
XXX_desc-initialmovingregressor_timeseries |
.tsv, .json |
The raw and filtered initial probe regressor, at the original sampling resolution |
Always |
XXX_desc-movingregressor_timeseries |
.tsv, .json |
The probe regressor used in each pass, at the time resolution of the data |
Always |
XXX_desc-oversampledmovingregressor_timeseries |
.tsv, .json |
The probe regressor used in each pass, at the time resolution used for calculating the similarity function |
Always |
XXX_desc-refinedmovingregressor_timeseries |
.tsv, .json |
The raw and filtered probe regressor produced by the refinement procedure, at the time resolution of the data |
Present if passes > 1 |
Usage:
Perform a RIPTiDe time delay analysis on a dataset.
usage: rapidtide [-h]
[--denoising | --delaymapping | --CVR | --globalpreselect]
[--venousrefine | --nirs]
[--datatstep TSTEP | --datafreq FREQ] [--noantialias]
[--invert] [--interptype {univariate,cubic,quadratic}]
[--offsettime OFFSETTIME] [--autosync]
[--filterband {None,vlf,lfo,resp,cardiac,hrv_ulf,hrv_vlf,hrv_lf,hrv_hf,hrv_vhf,lfo_legacy}]
[--filterfreqs LOWERPASS UPPERPASS]
[--filterstopfreqs LOWERSTOP UPPERSTOP]
[--filtertype {trapezoidal,brickwall,butterworth}]
[--butterorder ORDER] [--padseconds SECONDS]
[--permutationmethod {shuffle,phaserandom}] [--numnull NREPS]
[--skipsighistfit]
[--windowfunc {hamming,hann,blackmanharris,None}]
[--zeropadding PADVAL] [--detrendorder ORDER]
[--spatialfilt GAUSSSIGMA] [--globalmean]
[--globalmaskmethod {mean,variance}]
[--globalmeaninclude MASK[:VALSPEC]]
[--globalmeanexclude MASK[:VALSPEC]] [--motionfile MOTFILE]
[--motderiv] [--confoundfile CONFFILE] [--confoundpowers N]
[--confoundderiv] [--noconfoundorthogonalize]
[--globalsignalmethod {sum,meanscale,pca}]
[--globalpcacomponents VALUE] [--slicetimes FILE]
[--numskip SKIP] [--numtozero NUMPOINTS]
[--timerange START END] [--nothresh]
[--oversampfac OVERSAMPFAC] [--regressor FILE]
[--regressorfreq FREQ | --regressortstep TSTEP]
[--regressorstart START]
[--corrweighting {None,phat,liang,eckart,regressor}]
[--corrtype {linear,circular}]
[--corrmaskthresh PCT | --corrmask MASK[:VALSPEC]]
[--similaritymetric {correlation,mutualinfo,hybrid}]
[--mutualinfosmoothingtime TAU] [--simcalcrange START END]
[--fixdelay DELAYTIME | --searchrange LAGMIN LAGMAX]
[--sigmalimit SIGMALIMIT] [--bipolar] [--nofitfilt]
[--peakfittype {gauss,fastgauss,quad,fastquad,COM,None}]
[--despecklepasses PASSES] [--despecklethresh VAL]
[--refineprenorm {None,mean,var,std,invlag}]
[--refineweighting {None,NIRS,R,R2}] [--passes PASSES]
[--refineinclude MASK[:VALSPEC]]
[--refineexclude MASK[:VALSPEC]] [--norefinedespeckled]
[--lagminthresh MIN] [--lagmaxthresh MAX] [--ampthresh AMP]
[--sigmathresh SIGMA] [--offsetinclude MASK[:VALSPEC]]
[--offsetexclude MASK[:VALSPEC]] [--norefineoffset]
[--pickleft] [--pickleftthresh THRESH]
[--refineupperlag | --refinelowerlag]
[--refinetype {pca,ica,weighted_average,unweighted_average}]
[--pcacomponents VALUE] [--convergencethresh THRESH]
[--maxpasses MAXPASSES] [--noglm] [--glmsourcefile FILE]
[--preservefiltering] [--glmderivs NDERIVS] [--nolimitoutput]
[--savelags] [--histlen HISTLEN] [--saveintermediatemaps]
[--calccoherence] [--version] [--detailedversion]
[--noprogressbar] [--checkpoint] [--spcalculation]
[--dpoutput] [--cifti] [--simulate] [--displayplots]
[--nonumba] [--nosharedmem] [--memprofile]
[--mklthreads MKLTHREADS] [--nprocs NPROCS] [--reservecpu]
[--infotag tagkey tagvalue] [--psdfilter] [--wiener]
[--corrbaselinespatialsigma SIGMA]
[--corrbaselinetemphpfcutoff FREQ]
[--spatialtolerance EPSILON] [--echocancel]
[--autorespdelete] [--noisetimecourse FILENAME[:VALSPEC]]
[--noisefreq FREQ | --noisetstep TSTEP] [--noisestart START]
[--noiseinvert] [--acfix] [--negativegradient]
[--cleanrefined] [--dispersioncalc] [--tmask FILE] [--debug]
[--verbose] [--disabledockermemfix] [--alwaysmultiproc]
[--singleproc_confoundregress] [--singleproc_getNullDist]
[--singleproc_calcsimilarity] [--singleproc_peakeval]
[--singleproc_fitcorr] [--singleproc_refine]
[--singleproc_makelaggedtcs] [--singleproc_glm] [--isatest]
in_file outputname
Positional Arguments
- in_file
The input data file (BOLD fMRI file or NIRS text file).
- outputname
The root name for the output files. For BIDS compliance, this can only contain valid BIDS entities from the source data.
Analysis type
Single arguments that set several parameter values, tailored to particular analysis types. Any parameter set by an analysis type can be overridden by setting that parameter explicitly. Analysis types are mutually exclusive with one another.
- --denoising
Preset for hemodynamic denoising - this is a macro that sets searchrange=(-10.0, 10.0), passes=3, despeckle_passes=4, refineoffset=True, peakfittype=gauss, gausssigma=-1, nofitfilt=True, doglmfilt=True. Any of these options can be overridden with the appropriate additional arguments.
Default: False
- --delaymapping
Preset for delay mapping analysis - this is a macro that sets searchrange=(-10.0, 30.0), passes=3, despeckle_passes=4, refineoffset=True, pickleft=True, limitoutput=True, doglmfilt=False. Any of these options can be overridden with the appropriate additional arguments.
Default: False
- --CVR
Preset for calibrated CVR mapping. Given an input regressor that represents some measured quantity over time (e.g. mmHg CO2 in the EtCO2 trace), rapidtide will calculate and output a map of percent BOLD change in units of the input regressor. To do this, this sets: passes=1, despeckle_passes=4, searchrange=(-5.0, 20.0), filterfreqs=(0.0, 0.01), and calculates a voxelwise GLM using the optimally delayed input regressor and the percent normalized, demeaned BOLD data as inputs. This map is output as (XXX_desc-CVR_map.nii.gz). If no input regressor is supplied, this will generate an error. These options can be overridden with the appropriate additional arguments.
Default: False
- --globalpreselect
Treat this run as an initial pass to locate good candidate voxels for global mean regressor generation. This sets: passes=1, pickleft=True, despecklepasses=0, refinedespeckle=False, limitoutput=True, doglmfilt=False, saveintermediatemaps=False.
Default: False
Macros
Single arguments that change default values for many arguments. Macros override individually set parameters. Macros are mutually exclusive with one another.
- --venousrefine
This is a macro that sets lagminthresh=2.5, lagmaxthresh=6.0, ampthresh=0.5, and refineupperlag to bias refinement towards voxels in the draining vasculature for an fMRI scan.
Default: False
- --nirs
This is a NIRS analysis - this is a macro that sets nothresh, refineprenorm=var, ampthresh=0.7, and lagminthresh=0.1.
Default: False
Preprocessing options
- --datatstep
Set the timestep of the data file to TSTEP. This will override the TR in an fMRI file. NOTE: if using data from a text file, for example with NIRS data, using one of these options is mandatory.
Default: auto
- --datafreq
Set the timestep of the data file to 1/FREQ. This will override the TR in an fMRI file. NOTE: if using data from a text file, for example with NIRS data, using one of these options is mandatory.
Default: auto
- --noantialias
Disable antialiasing filter.
Default: True
- --invert
Invert the sign of the regressor before processing.
Default: False
- --interptype
Possible choices: univariate, cubic, quadratic
Use specified interpolation type. Options are “cubic”, “quadratic”, and “univariate”. Default is univariate.
Default: “univariate”
- --offsettime
Apply offset OFFSETTIME to the lag regressors.
Default: 0.0
- --autosync
Estimate and apply the initial offsettime of an external regressor using the global crosscorrelation. Overrides offsettime if present.
Default: False
- --detrendorder
Set order of trend removal (0 to disable). Default is 3.
Default: 3
- --spatialfilt
Spatially filter fMRI data prior to analysis using GAUSSSIGMA in mm. Set GAUSSSIGMA negative to have rapidtide set it to half the mean voxel dimension (a rule of thumb for a good value).
Default: -1
- --globalmean
Generate a global mean regressor and use that as the reference regressor. If no external regressor is specified, this is enabled by default.
Default: False
- --globalmaskmethod
Possible choices: mean, variance
Select whether to use timecourse mean or variance to mask voxels prior to generating global mean. Default is “mean”.
Default: “mean”
- --globalmeaninclude
Only use voxels in mask file NAME for global regressor generation (if VALSPEC is given, only voxels with integral values listed in VALSPEC are used).
- --globalmeanexclude
Do not use voxels in mask file NAME for global regressor generation (if VALSPEC is given, only voxels with integral values listed in VALSPEC are excluded).
- --motionfile
Read 6 columns of motion regressors out of MOTFILE file (.par or BIDS .json) (with timepoints rows) and regress them and/or their derivatives out of the data prior to analysis.
- --motderiv
Toggle whether derivatives will be used in motion regression. Default is True.
Default: True
- --confoundfile
Read additional (non-motion) confound regressors out of CONFFILE file (which can be any type of multicolumn text file rapidtide reads as long as data is sampled at TR with timepoints rows). Optionally do power expansion and/or calculate derivatives prior to regression.
- --confoundpowers
Include powers of each confound regressor up to order N. Default is 1 (no expansion).
Default: 1
- --confoundderiv
Toggle whether derivatives will be used in confound regression. Default is True.
Default: True
- --noconfoundorthogonalize
Do not orthogonalize confound regressors prior to regressing them out of the data.
Default: True
- --globalsignalmethod
Possible choices: sum, meanscale, pca
The method for constructing the initial global signal regressor - straight summation, mean scaling each voxel prior to summation, or MLE PCA of the voxels in the global signal mask. Default is “sum.”
Default: “sum”
- --globalpcacomponents
Number of PCA components used for estimating the global signal. If VALUE >= 1, will retain thismany components. If 0.0 < VALUE < 1.0, enough components will be retained to explain the fraction VALUE of the total variance. If VALUE is negative, the number of components will be to retain will be selected automatically using the MLE method. Default is 0.8.
Default: 0.8
- --slicetimes
Apply offset times from FILE to each slice in the dataset.
- --numskip
SKIP TRs were previously deleted during preprocessing (e.g. if you have done your preprocessing in FSL and set dummypoints to a nonzero value.) Default is 0.
Default: 0
- --numtozero
When calculating the moving regressor, set this number of points to zero at the beginning of the voxel timecourses. This prevents initial points which may not be in equilibrium from contaminating the calculated sLFO signal. This may improve similarity fitting and GLM noise removal. Default is 0.
Default: 0
- --timerange
Limit analysis to data between timepoints START and END in the fmri file. If END is set to -1, analysis will go to the last timepoint. Negative values of START will be set to 0. Default is to use all timepoints.
Default: (-1, -1)
- --nothresh
Disable voxel intensity threshold (especially useful for NIRS data).
Default: False
Filtering options
- --filterband
Possible choices: None, vlf, lfo, resp, cardiac, hrv_ulf, hrv_vlf, hrv_lf, hrv_hf, hrv_vhf, lfo_legacy
Filter data and regressors to specific band. Use “None” to disable filtering. Default is “lfo”.
Default: “lfo”
- --filterfreqs
Filter data and regressors to retain LOWERPASS to UPPERPASS. If –filterstopfreqs is not also specified, LOWERSTOP and UPPERSTOP will be calculated automatically.
- --filterstopfreqs
Filter data and regressors to with stop frequencies LOWERSTOP and UPPERSTOP. LOWERSTOP must be <= LOWERPASS, UPPERSTOP must be >= UPPERPASS. Using this argument requires the use of –filterfreqs.
- --filtertype
Possible choices: trapezoidal, brickwall, butterworth
Filter data and regressors using a trapezoidal FFT, brickwall FFT, or butterworth bandpass filter. Default is “trapezoidal”.
Default: “trapezoidal”
- --butterorder
Set order of butterworth filter (if used). Default is 6.
Default: 6
- --padseconds
The number of seconds of padding to add to each end of a filtered timecourse to reduce end effects. Default is 30.0.
Default: 30.0
Significance calculation options
- --permutationmethod
Possible choices: shuffle, phaserandom
Permutation method for significance testing. Default is “shuffle”.
Default: “shuffle”
- --numnull
Estimate significance threshold by running NREPS null correlations (default is 10000, set to 0 to disable).
Default: 10000
- --skipsighistfit
Do not fit significance histogram with a Johnson SB function.
Default: True
Windowing options
- --windowfunc
Possible choices: hamming, hann, blackmanharris, None
Window function to use prior to correlation. Options are hamming, hann, blackmanharris, and None. Default is hamming
Default: “hamming”
- --zeropadding
Pad input functions to correlation with PADVAL zeros on each side. A PADVAL of 0 does circular correlations, positive values reduce edge artifacts. Set PADVAL < 0 to set automatically. Default is 0.
Default: 0
Correlation options
- --oversampfac
Oversample the fMRI data by the following integral factor. Set to -1 for automatic selection (default).
Default: -1
- --regressor
Read the initial probe regressor from file FILE (if not specified, generate and use the global regressor).
- --regressorfreq
Probe regressor in file has sample frequency FREQ (default is 1/tr) NB: –regressorfreq and –regressortstep) are two ways to specify the same thing.
Default: auto
- --regressortstep
Probe regressor in file has sample frequency FREQ (default is 1/tr) NB: –regressorfreq and –regressortstep) are two ways to specify the same thing.
Default: auto
- --regressorstart
The time delay in seconds into the regressor file, corresponding in the first TR of the fMRI file (default is 0.0).
Default: 0.0
- --corrweighting
Possible choices: None, phat, liang, eckart, regressor
Method to use for cross-correlation weighting. ‘None’ performs an unweighted correlation. ‘phat’ weights the correlation by the magnitude of the product of the timecourse’s FFTs. ‘liang’ weights the correlation by the sum of the magnitudes of the timecourse’s FFTs. ‘eckart’ weights the correlation by the product of the magnitudes of the timecourse’s FFTs. ‘regressor’ weights the correlation by the magnitude of the sLFO regressor FFT. Default is “regressor”.
Default: “regressor”
- --corrtype
Possible choices: linear, circular
Cross-correlation type (linear or circular). Default is “linear”.
Default: “linear”
- --corrmaskthresh
Do correlations in voxels where the mean exceeds this percentage of the robust max. Default is 1.0.
Default: 1.0
- --corrmask
Only do correlations in nonzero voxels in NAME (if VALSPEC is given, only voxels with integral values listed in VALSPEC are used).
- --similaritymetric
Possible choices: correlation, mutualinfo, hybrid
Similarity metric for finding delay values. Choices are “correlation”, “mutualinfo”, and “hybrid”. Default is correlation.
Default: “correlation”
- --mutualinfosmoothingtime
Time constant of a temporal smoothing function to apply to the mutual information function. Default is 3.0 seconds. TAU <=0.0 disables smoothing.
Default: 3.0
- --simcalcrange
Limit correlation calculation to data between timepoints START and END in the fmri file. If END is set to -1, analysis will go to the last timepoint. Negative values of START will be set to 0. Default is to use all timepoints. NOTE: these offsets are relative to the start of the dataset AFTER any trimming done with ‘–timerange’.
Default: (-1, -1)
Correlation fitting options
- --fixdelay
Don’t fit the delay time - set it to DELAYTIME seconds for all voxels.
- --searchrange
Limit fit to a range of lags from LAGMIN to LAGMAX. Default is -30.0 to 30.0 seconds.
Default: (-30.0, 30.0)
- --sigmalimit
Reject lag fits with linewidth wider than SIGMALIMIT Hz. Default is 1000.0 Hz.
Default: 1000.0
- --bipolar
Bipolar mode - match peak correlation ignoring sign.
Default: False
- --nofitfilt
Do not zero out peak fit values if fit fails.
Default: True
- --peakfittype
Possible choices: gauss, fastgauss, quad, fastquad, COM, None
Method for fitting the peak of the similarity function “gauss” performs a Gaussian fit, and is most accurate. “quad” and “fastquad” use a quadratic fit, which is faster, but not as well tested. Default is “gauss”.
Default: “gauss”
- --despecklepasses
Detect and refit suspect correlations to disambiguate peak locations in PASSES passes. Default is to perform 4 passes. Set to 0 to disable.
Default: 4
- --despecklethresh
Refit correlation if median discontinuity magnitude exceeds VAL. Default is 5.0 seconds.
Default: 5.0
Regressor refinement options
- --refineprenorm
Possible choices: None, mean, var, std, invlag
Apply TYPE prenormalization to each timecourse prior to refinement. Default is “None”.
Default: “None”
- --refineweighting
Possible choices: None, NIRS, R, R2
Apply TYPE weighting to each timecourse prior to refinement. Default is “R2”.
Default: “R2”
- --passes
Set the number of processing passes to PASSES. Default is 3.
Default: 3
- --refineinclude
Only use voxels in file MASK for regressor refinement (if VALSPEC is given, only voxels with integral values listed in VALSPEC are used).
- --refineexclude
Do not use voxels in file MASK for regressor refinement (if VALSPEC is given, voxels with integral values listed in VALSPEC are excluded).
- --norefinedespeckled
Do not use despeckled pixels in calculating the refined regressor.
Default: True
- --lagminthresh
For refinement, exclude voxels with delays less than MIN. Default is 0.5 seconds.
Default: 0.5
- --lagmaxthresh
For refinement, exclude voxels with delays greater than MAX. Default is 5.0 seconds.
Default: 5.0
- --ampthresh
For refinement, exclude voxels with correlation coefficients less than AMP (default is 0.3). NOTE: ampthresh will automatically be set to the p<0.05 significance level determined by the –numnull option if NREPS is set greater than 0 and this is not manually specified.
Default: -1.0
- --sigmathresh
For refinement, exclude voxels with widths greater than SIGMA seconds. Default is 100.0 seconds.
Default: 100.0
- --offsetinclude
Only use voxels in file MASK for determining the zero time offset value (if VALSPEC is given, only voxels with integral values listed in VALSPEC are used).
- --offsetexclude
Do not use voxels in file MASK for determining the zero time offset value (if VALSPEC is given, voxels with integral values listed in VALSPEC are excluded).
- --norefineoffset
Disable realigning refined regressor to zero lag.
Default: True
- --pickleft
Will select the leftmost delay peak when setting the refine offset.
Default: False
- --pickleftthresh
Threshhold value (fraction of maximum) in a histogram to be considered the start of a peak. Default is 0.33.
Default: 0.33
- --refineupperlag
Only use positive lags for regressor refinement.
Default: “both”
- --refinelowerlag
Only use negative lags for regressor refinement.
Default: “both”
- --refinetype
Possible choices: pca, ica, weighted_average, unweighted_average
Method with which to derive refined regressor. Default is “pca”.
Default: “pca”
- --pcacomponents
Number of PCA components used for refinement. If VALUE >= 1, will retain this many components. If 0.0 < VALUE < 1.0, enough components will be retained to explain the fraction VALUE of the total variance. If VALUE is negative, the number of components will be to retain will be selected automatically using the MLE method. Default is 0.8.
Default: 0.8
- --convergencethresh
Continue refinement until the MSE between regressors becomes <= THRESH. By default, this is not set, so refinement will run for the specified number of passes.
- --maxpasses
Terminate refinement after MAXPASSES passes, whether or not convergence has occured. Default is 15.
Default: 15
GLM noise removal options
- --noglm
Turn off GLM filtering to remove delayed regressor from each voxel (disables output of fitNorm).
Default: True
- --glmsourcefile
Regress delayed regressors out of FILE instead of the initial fmri file used to estimate delays.
- --preservefiltering
Don’t reread data prior to performing GLM.
Default: False
- --glmderivs
When doing final GLM, include derivatives up to NDERIVS order. Default is 0
Default: 0
Output options
- --nolimitoutput
Save some of the large and rarely used files.
Default: True
- --savelags
Save a table of lagtimes used.
Default: False
- --histlen
Change the histogram length to HISTLEN. Default is 101.
Default: 101
- --saveintermediatemaps
Save lag times, strengths, widths, and mask for each pass.
Default: False
- --calccoherence
Calculate and save the coherence between the final regressor and the data.
Default: False
Version options
- --version
Show simplified version information and exit
- --detailedversion
Show detailed version information and exit
Miscellaneous options
- --noprogressbar
Will disable showing progress bars (helpful if stdout is going to a file).
Default: True
- --checkpoint
Enable run checkpoints.
Default: False
- --spcalculation
Use single precision for internal calculations (may be useful when RAM is limited).
Default: “double”
- --dpoutput
Use double precision for output files.
Default: “single”
- --cifti
Data file is a converted CIFTI.
Default: False
- --simulate
Simulate a run - just report command line options.
Default: False
- --displayplots
Display plots of interesting timecourses.
Default: False
- --nonumba
Disable jit compilation with numba.
Default: False
- --nosharedmem
Disable use of shared memory for large array storage.
Default: True
- --memprofile
Enable memory profiling - warning: this slows things down a lot.
Default: False
- --mklthreads
Use no more than MKLTHREADS worker threads in accelerated numpy calls.
Default: 1
- --nprocs
Use NPROCS worker processes for multiprocessing. Setting NPROCS to less than 1 sets the number of worker processes to n_cpus (unless –reservecpu is used).
Default: 1
- --reservecpu
When automatically setting nprocs, reserve one CPU for process management rather than using them all for worker threads.
Default: False
- --infotag
Additional key, value pairs to add to the options json file (useful for tracking analyses).
Experimental options (not fully tested, may not work)
- --psdfilter
Apply a PSD weighted Wiener filter to shifted timecourses prior to refinement.
Default: False
- --wiener
Do Wiener deconvolution to find voxel transfer function.
Default: False
- --corrbaselinespatialsigma
Spatial lowpass kernel, in mm, for filtering the correlation function baseline.
Default: 0.0
- --corrbaselinetemphpfcutoff
Temporal highpass cutoff, in Hz, for filtering the correlation function baseline.
Default: 0.0
- --spatialtolerance
When checking to see if the spatial dimensions of two NIFTI files match, allow a relative difference of EPSILON in any dimension. By default, this is set to 0.0, requiring an exact match.
Default: 0.0
- --echocancel
Attempt to perform echo cancellation on current moving regressor.
Default: False
- --autorespdelete
Attempt to detect and remove respiratory signal that strays into the LFO band.
Default: False
- --noisetimecourse
Find and remove any instance of the timecourse supplied from any regressors used for analysis. (if VALSPEC is given, and there are multiple timecourses in the file, use the indicated timecourse.This can be the name of the regressor if it’s in the file, or the column number).
- --noisefreq
Noise timecourse in file has sample frequency FREQ (default is 1/tr) NB: –noisefreq and –noisetstep) are two ways to specify the same thing.
Default: auto
- --noisetstep
Noise timecourse in file has sample frequency FREQ (default is 1/tr) NB: –noisefreq and –noisetstep) are two ways to specify the same thing.
Default: auto
- --noisestart
The time delay in seconds into the noise timecourse file, corresponding in the first TR of the fMRI file (default is 0.0).
Default: 0.0
- --noiseinvert
Invert noise regressor prior to alignment.
Default: False
- --acfix
Check probe regressor for autocorrelations in order to disambiguate peak location.
Default: False
- --negativegradient
Calculate the negative gradient of the fmri data after spectral filtering so you can look for CSF flow à la https://www.biorxiv.org/content/10.1101/2021.03.29.437406v1.full.
Default: False
- --cleanrefined
Perform additional processing on refined regressor to remove spurious components.
Default: False
- --dispersioncalc
Generate extra data during refinement to allow calculation of dispersion.
Default: False
- --tmask
Only correlate during epochs specified in MASKFILE (NB: each line of FILE contains the time and duration of an epoch to include.
Debugging options. You probably don’t want to use any of these unless I ask you to to help diagnose a problem
- --debug
Enable additional debugging output.
Default: False
- --verbose
Enable additional runtime information output.
Default: False
- --disabledockermemfix
Disable docker memory limit setting.
Default: True
- --alwaysmultiproc
Use the multiprocessing code path even when nprocs=1.
Default: False
- --singleproc_confoundregress
Force single proc path for confound regression.
Default: False
- --singleproc_getNullDist
Force single proc path for getNullDist.
Default: False
- --singleproc_calcsimilarity
Force single proc path for calcsimilarity.
Default: False
- --singleproc_peakeval
Force single proc path for peakeval.
Default: False
- --singleproc_fitcorr
Force single proc path for fitcorr.
Default: False
- --singleproc_refine
Force single proc path for refine.
Default: False
- --singleproc_makelaggedtcs
Force single proc path for makelaggedtcs.
Default: False
- --singleproc_glm
Force single proc path for glm.
Default: False
- --isatest
This run of rapidtide is in a unit test.
Default: False
Preprocessing for rapidtide
Rapidtide operates on data which has been subjected to “standard” preprocessing steps, most importantly motion correction and slice time correction.
Motion correction - Motion correction is good since you want to actually be looking at the same voxels in each timepoint. Definitely
do it. There may be spin history effects even after motion correction, so if you give rapidtide a motion file
using --motionfile FILENAME
(and various other options to tune how it does the motion regression)
it can regress out residual motion prior to estimating sLFO parameters. In cases of extreme motion, this will
make rapidtide work a lot better. If you choose to regress out the motion signals yourself, that’s fine too -
rapidtide is happy to work on data that’s been run through AROMA (not so much FIX - see a further discussion below).
Slice time correction - Since rapidtide is looking for subtle time differences in the arrival of the sLFO signal, it will absolutely see slice acquisition time differences. If you are doing noise removal, that’s not such a big deal, but if you’re doing delay mapping, you’ll get stripes in your delay maps, which tell you about the fMRI acquisition, but you care about physiology, so best to avoid that. Unfortunately, Human Connectome Project data does NOT have slice time correction applied, and unless you want to rerun the entire processing chain to add it in, you just have to deal with it. Fortunately the TR is quite short, so the stripes are subtle. The geometric distortion correction and alignment steps done in the HCP distort the stripes, but you can certainly see them. If you average enough subjects though, they get washed out.
Spatial filtering - I generally do NOT apply any spatial filtering
during preprocessing for a variety of reasons. fmriprep doesn’t do it, so I feel validated in this choice.
You can always do it later, and rapidtide lets you do spatial smoothing for the purpose of
estimating the delayed regressor using the --gausssigma
parameter. This turns out to stabilize the fits for
rapidtide and is usually a good thing, however you probably don’t want it for other processing (but that’s ok - see below).
Temporal filtering - Rapidtide does all it’s own temporal filtering; highpass filtering at 0.01Hz, common in r esting state preprocessing, doesn’t affect the frequency ranges rapidtide cares about for sLFOs, so you can do it or not during preprocessing as you see fit (but if you’re doing CVR or gas challenge experiments you probably shouldn’t).
NOTE: Astute readers will notice that between spatial filtering, motion regression, and other procedures, rapidtide
does a lot of it’s work of estimating sLFOs on potentially heavily filtered data, which is good for improving the
estimation and fitting of the sLFO signal. However, you may or may not
want this filtering to have been done for whatever your particular subsequent analysis is. So prior to GLM denoising, rapidtide
rereads the unmodified fMRI input file, and regresses the voxel specific sLFO out of that - since the filtering
process is linear, that’s cool - the data you get out is the data you put in, just minus the sLFO signal. If for
some reason you do want to use the data that rapidtide has abused, simply use the --preservefiltering
option,
but I’d recommend you don’t do that.
Working with standard fMRI packages
FSL - At the time I first developed rapidtide, I was using FSL almost exclusively, so some of the assumptions
the program makes about the data stem from this. If you want to integrate rapidtide into your FSL workflow, you would
typically use the filtered_func_data.nii.gz
file from your FEAT directory (the result of FSL preprocessing)
as input to rapidtide. Note that this is typically in native acquisition space. You can use this, or do the
processing in standard space if you’ve done that alignment - either is fine, but for conventional EPI acquisitions,
there are typically far fewer voxels at native resolution, so processing will probably be faster. On the flip side,
having everything in standard space makes it easier to combine runs and subjects.
fmriprep - If you do preprocessing in fmriprep, the easiest file to use for input to rapidtide would be either
derivatives/fmriprep/sub-XXX/ses-XXX/func/XXX_desc-preproc_bold.nii.gz
(native space) or
derivatives/fmriprep/sub-XXX/ses-XXX/func/XXX_space-MNI152NLin6Asym_res-2_desc-preproc_bold.nii.gz
(standard space - replace MNI152NLin6aAsym_res-2
with whatever space and resolution you used if not the FSL compatible
one). One caveat - unless this has changed recently, fmriprep does not store the transforms needed to go from
native BOLD space to standard space, so you’ll have to come up with that yourself either by fishing the transform
out of the workdir, or redoing the alignment. That’s a pretty strong argument for using the standard space. In addition,
if you do the analysis in standard space, it makes it easier to use freesurfer parcellations and gray/white/csf
segmentations that fmriprep provides for further tuning the rapidtide analysis. See the “Theory of Operation” section
for more on this subject.
AFNI - Here’s a case where you have to take some care - as I mentioned above, rapidtide assumes “FSL-like” data by
default. The most important difference between AFNI and FSL preprocessing (assuming you’ve put your AFNI data into
NIFTI format) is that AFNI removes the mean from the preprocessed fMRI data
(this is a valid implementation choice - no judgement, but, no, actually - seriously, WTF? WHY WOULD YOU DO THAT???).
This makes rapidtide sad, because the mean value of the fMRI data is used for all sorts of things like
generating masks. Fortunately, this can be easily accommodated. You have a couple of choices here. You can
supply a mean mask and correlation mask explicitly using --globalmeaninclude FILENAME
and --corrmask FILENAME
,
(FILENAME should definitely be a brain mask for --corrmask
- it can be more focussed for --globalmeaninclude
-
for example, a gray matter mask, but a brain mask works fine in most cases) which will get
rapidtide past the places that zero mean data will confuse it. Alternately, if you don’t have a brain mask, you can
use --globalmaskmethod variance
to make a mask based on the variance over time in a voxel rather than than the
mean. Rapidtide should then work as normal, although the display in tidepool
will be a little weird unless you
specify a background image explicitly.
SPM - I have no reason to believe rapidtide won’t work fine with data preprocessed in SPM. That said, I don’t use SPM, so I can’t tell you what file to use, or what format to expect the preprocessed data will be in. If you, dear reader, have any insight into this, PLEASE tell me and I’ll do what I need to to support SPM data in the code and documentation.
Analysis Examples:
Rapidtide can do many things - as I’ve found more interesting things to do with time delay processing, it’s gained new functions and options to support these new applications. As a result, it can be a little hard to know what to use for a new experiment. To help with that, I’ve decided to add this section to the manual to get you started. It’s broken up by type of data/analysis you might want to do.
NB: To speed up the analysis, adding the argument --nprocs XX
to any of the following commands will parallelize
the analysis to use XX CPUs - set XX to -1 to use all available CPUs. This can result in a speedup approaching a
factor of the number of CPUs used.
Removing low frequency physiological noise from fMRI data
This is what I figure most people will use rapidtide for - finding and removing the low frequency (LFO) signal from an existing dataset (including the case where the signal grows over time https://www.biorxiv.org/content/10.1101/2023.09.08.556939v2 ). This presupposes you have not made a simultaneous physiological recording (well, you may have, but it assumes you aren’t using it). For this, you can use a minimal set of options, since the defaults are set to be generally optimal for noise removal.
The base command you’d use would be:
rapidtide \ inputfmrifile \ outputname \ --denoising
This will do a the default analysis (but each and every particular can be changed by adding command line options). By default, rapidtide will:
Temporally prefilter the data to the LFO band (0.009-0.15Hz), and spatially filter with a Gaussian kernel of 1/2 the mean voxel dimension in x, y, and z.
Construct a probe regressor from the global mean of the signal in inputfmrifile (default behavior if no regressor or selections masks are specified).
Do three passes through the data. In each step, rapidtide will:
Perform a crosscorrelation of each voxel with the probe regressor using the “regressor” weighting.
Estimate the location and strength of the correlation peak using the correlation similarity metric within a range of +/-10 seconds around around the modal delay value.
Generate a new estimate of the global noise signal by:
Aligning all of the voxel timecourses to bring the global signal into phase,
Performing a PCA analysis,
Reconstructing each timecourse using the PCA components accounting for 80% of the signal variance in the aligned voxel timecourses,
Averaging the reconstructed timecourses to produce a new probe regressor,
Applying an offset to the recenter the peak of the delay distribution of all voxels to zero, which should make datasets easier to compare.
After the three passes are complete, rapidtide will then use a GLM filter to remove a voxel specific lagged copy of the final probe regressor from the data - this denoised data will be in the file
outputname_desc-lfofilterCleaned_bold.nii.gz
. There will also a number of maps output with the prefixoutputname_
of delay, correlation strength and so on. See the BIDS Output table above for specifics.
Please note that rapidtide plays happily with AROMA, so you don’t need to do anything special to process data that’s been run through AROMA. While FIX and AROMA both use spatiotemporal analysis of independent components to determine what components to remove, AROMA only targets ICs related to motion, which are quite distinct from the sLFO signal, so they don’t interfere with each other. In contrast, FIX targets components that are “bad”, for multiple definitions of the term, which includes some purely hemodynamic components near the back of the brain. As a result, FIX denoising impedes the operation of rapidtide. See below.
Removing low frequency physiological noise from fMRI data that has been processed with FIX
There is a special case if you are working on HCP data, which has both minimally processed and a fully processed
(including FIX denoising) data files. FIX denoising is a good thing, but it tends to distort the sLFO signals that
rapidtide is looking for, so the selection and refinement of the sLFO can wander off into the thicket if applied to
FIX processed data. So ideally, you would run rapidtide, and THEN FIX. However, since reprocessing the HCP data
is kind of a pain, there’s a hack that capitalizes on the fact that all of these operations are linear. You run
rapidtide on the minimmally processed data, to accurately assess the sLFO regressor and time delays in each voxel,
but you apply the final GLM to the FIX processed data, to remove the data that has the other denoising already done.
This works very well! To do this, you use the --glmsourcefile FILE
option to specify the file you want to
denoise. The outputname_desc-lfofilterCleaned_bold.nii.gz
file is the FIX file, with rapidtide denoising applied.
rapidtide \ minimallyprocessedinputfmrifile \ outputname \ --denoising \ --glmsourcefile FIXprocessedfile
Mapping long time delays in response to a gas challenge experiment:
Processing this sort of data requires a very different set of options from the previous case. Instead of the distribution of delays you expect in healthy controls (a slightly skewed, somewhat normal distribution with a tail on the positive side, ranging from about -5 to 5 seconds), in this case, the maximum delay can be extremely long (100-120 seconds is not uncommon in stroke, moyamoya disesase, and atherosclerosis). To do this, you need to radically change what options you use, not just the delay range, but a number of other options having to do with refinement and statistical measures.
For this type of analysis, a good place to start is the following:
rapidtide \ inputfmrifile \ outputname \ --numnull 0 \ --searchrange -10 140 \ --filterfreqs 0.0 0.01 \ --ampthresh 0.2 \ --noglm \ --nofitfilt
The first option (--numnull 0
), shuts off the calculation of the null correlation distribution. This is used to
determine the significance threshold, but the method currently implemented in rapidtide is a bit simplistic - it
assumes that all the time points in the data are exchangable. This is certainly true for resting state data (see
above), but it is very much NOT true for block paradigm gas challenges. To properly analyze those, I need to
consider what time points are ‘equivalent’, and up to now, I don’t, so setting the number of iterations in the
Monte Carlo analysis to zero omits this step.
The second option (--searchrange -10 140
) is fairly obvious - this extends the detectable delay range out
to 140 seconds. Note that this is somewhat larger than the maximum delays we frequently see, but to find the
correlation peak with maximum precision, you need sufficient additional delay values so that the correlation
can come to a peak and then come down enough that you can properly fit it. Obviously adjust this as needed
for your experiment, to fit the particulars of your gas challenge waveform and/or expected pathology.
Setting --filterfreqs 0.0 0.01
is VERY important. By default, rapidtide assumes you are looking at
endogenous low frequency oscillations, which typically between 0.009 and 0.15 Hz. However, gas challenge
paradigms are usually MUCH lower frequency (90 seconds off, 90 seconds on corresponds to 1/180s = ~0.006Hz).
So if you use the default frequency settings, you will completely filter out your stimulus, and presumably,
your response. If you are processing one of these experiments and get no results whatsoever, this is almost
certainly the problem.
The --noglm
option disables data filtering. If you are using rapidtide to estimate and remove low frequency
noise from resting state or task fMRI data, the last step is to use a glm filter to remove this circulatory signal,
leaving “pure” neuronal signal, which you’ll use in further analyses. That’s not relevant here - the signal you’d
be removing is the one you care about. So this option skips that step to save time and disk space.
--nofitfilt
skips a step after peak estimation. Estimating the delay and correlation amplitude in each voxel
is a two step process. First you make a quick estimate (where is the maximum point of the correlation function,
and what is its amplitude?), then you refine it by fitting a Gaussian function to the peak to improve the
estimate. If this step fails, which it can if the peak is too close to the end of the lag range, or
strangely shaped, the default behavior is to mark the point as bad and zero out the parameters for the
voxel. The nofitfilt option means that if the fit fails, output the initial estimates rather than all
zeros. This means that you get some information, even if it’s not fully refined. In my experience it
does tend to make the maps for the gas challenge experiments a lot cleaner to use this option since the
correlation function is pretty well behaved.
CVR mapping:
This is a slightly different twist on interpreting the strength of the lagged correlation. In this case, you supply an input regressor that corresponds to a measured, calibrated CO2 quantity (for example, etCO2 in mmHg). Rapidtide then does a modified analysis - it still uses the cross-correlation to find when the input regressor is maximally aligned with the variance in the voxel signal, but instead of only returning a correlation strength, it calculates the percentage BOLD change in each voxel in units of the input regressor (e.g. %BOLD/mmHg), which is the standard in CVR analysis.
rapidtide \ inputfmrifile \ outputname \ --regressor regressorfile \ --CVR
You invoke this with the --CVR
option. This is a macro that does a lot of things: I disabled refinement, set
--passes 1
, set --filterfreqs 0.0 0.01
(for the reasons described above regarding gas challenge experiments),
set --searchrange -5 20
,
hijacked the GLM filtering routine, and messed with some normalizations. If you want to refine your regressor
estimate, or filter the sLFO signal out of your data, you need to do a separate analysis.
You also need to supply the regressor using --regressor regressorfile
. If regressorfile is a bids
tsv/json pair, this will have the sample rate and offset specified. If the regressor file has sample
rate other than the fMRI TR, or a non-zero offset relative to the fMRI data, you will also need to specify
these parameters using --regressorfreq FREQ
or --regressortstep TSTEP
and/or --regressorstart START
.
Denoising NIRS data:
Fun face - when we started this whole research effort, I was originally planning to denoise NIRS data, not fMRI data. But one thing led to another, and the NIRS got derailed for the fMRI effort. Now that we have some time to catch our breaths, and more importantly, we have access to some much higher quality NIRS data, this moved back to the front burner. The majority of the work was already done, I just needed to account for a few qualities that make NIRS data different from fMRI data:
NIRS data is not generally stored in NIFTI files. While there is one now (SNIRF), at the time I started doing this, there was no standard NIRS file format. In the absence of one, you could do worse than a multicolumn text file, with one column per data channel. That’s what I did here - if the file has a ‘.txt’ extension rather than ‘.nii.’, ‘.nii.gz’, or no extension, it will assume all I/O should be done on multicolumn text files. However, I’m a firm believer in SNIRF, and will add support for it one of these days.
NIRS data is often zero mean. This turned out to mess with a lot of my assumptions about which voxels have significant data, and mask construction. This has led to some new options for specifying mask threshholds and data averaging.
NIRS data is in some sense “calibrated” as relative micromolar changes in oxy-, deoxy-, and total hemoglobin concentration, so mean and/or variance normalizing the timecourses may not be right thing to do. I’ve added in some new options to mess with normalizations.