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:

Output files produced by rapidtide
Name	Extension(s)	Content	When present
XXX_DONE	txt	Run status file	Always if rapidtide has finished without error
XXX_ISRUNNING	txt	Run status file	Only present if rapidtide is running, or has failed
XXX_commandline	txt	Raw command line used to invoke rapidtide	Always
XXX_desc-autocorr_timeseries	tsv.gz, json	Autocorrelation of the probe regressor for each pass	Always
XXX_desc-cleansimdistdata_info	tsv.gz, json	Individual sham correlation datapoints after outlier removal	Present if numnull > 0
XXX_desc-confoundfilterCleaned_bold	nii.gz, json	fMRI data after motion/confound regression	Present if doing motion/confound regression and outputlevel is max
XXX_desc-confoundfilterR2_hist	tsv.gz, json	Histogram of confound filter R2 values	Present if doing motion/confound regression
XXX_desc-confoundfilterR2_map	nii.gz, json	R2 of the motion/confound regression	Present if doing motion/confound regression
XXX_desc-corrfit_mask	nii.gz, json	Voxels where correlation value was fit	Always
XXX_desc-corrfitfailreason_info	nii.gz, json	Result codes for correlation fit	Always
XXX_desc-corrfitwindow_info	nii.gz, json	The search window for the correlation peak fit	Present if outputlevel is max
XXX_desc-corrout_info	nii.gz, json	Correlation function	Present if outputlevel is ≥ normal
XXX_desc-corrtimes_timeseries	tsv.gz, json	Correlation time axis	Present if outputlevel is max
XXX_desc-CoV_map	nii.gz, json	Voxelwise coefficient of variation of fmri data	Always
XXX_desc-delayoffset_hist	tsv.gz, json	Histogram of delay offsets calculated from regression coefficients	Present if sLFO filtering is enabled (default)
XXX_desc-delayoffset_map	nii.gz, json	Delay offset correction from delay refinement	Always
XXX_desc-despeckle_mask	nii.gz, json	Voxels that underwent despeckling in the final pass	Present if despecklepasses > 0 (default) and outputlevel is max
XXX_desc-EV_timeseries	tsv.gz, json	sLFO filter regressor set	Present if sLFO filtering is enabled (default)
XXX_desc-expandedconfounds_timeseries	tsv.gz, json	The expanded (via derivatives and powers) set of confound regressors used for prefiltering the data	Present if doing motion/confound regression
XXX_desc-filteredregressderivratios_map	nii.gz, json	regressderivratios, with outliers patched using median filtered data	Present if outputlevel is ≥ normal
XXX_desc-formattedruntimings_info	tsv	No description	Always
XXX_desc-gaussout_info	nii.gz, json	Simulated correlation function	Present if outputlevel is max
XXX_desc-globallag_hist	tsv.gz, json	Histogram of lag times from global lag calculation	Always
XXX_desc-initialmovingregressor_timeseries	tsv.gz, json	The raw and filtered initial probe regressor, at the original sampling resolution	Always
XXX_desc-initregressor_mask	nii.gz, json	Voxels used to calculate initial regressor	Always
XXX_desc-lagtcgenerator_timeseries	tsv.gz, json	The lagged timecourse generator	Always
XXX_desc-lfofilterCleaned_bold	nii.gz, json	fMRI data with sLFO signal filtered out	Present if sLFO filtering is enabled (default) and outputlevel is ≥ less
XXX_desc-lfofilterCoeff_map	nii.gz, json	Fit coefficient	Present if sLFO filtering is enabled (default) and outputlevel is ≥ normal
XXX_desc-lfofilterCoeffDerivN_map	nii.gz, json	Fit coefficient for the Nth temporal derivative	Present if sLFO filtering is enabled (default), regressderivs > 0, and outputlevel is max
XXX_desc-lfofilterEV_bold	nii.gz, json	Shifted sLFO regressor to filter	Present if despecklepasses > 0 (default) and outputlevel is max
XXX_desc-lfofilterEVDerivN_bold	nii.gz, json	Nth time derivative of shifted sLFO regressor	Present if sLFO filtering is enabled (default), regressderivs > 0, and outputlevel is max
XXX_desc-lfofilterInbandVarianceAfter_map	nii.gz, json	Inband variance after filtering	Present if sLFO filtering is enabled (default)
XXX_desc-lfofilterInbandVarianceBefore_map	nii.gz, json	Inband variance prior to filtering	Present if sLFO filtering is enabled (default)
XXX_desc-lfofilterInbandVarianceChange_hist	tsv.gz, json	Histogram of percent of inband variance removed by sLFO filter	Present if sLFO filtering is enabled (default)
XXX_desc-lfofilterInbandVarianceChange_map	nii.gz, json	Change in inband variance after filtering, in percent	Present if sLFO filtering is enabled (default)
XXX_desc-lfofilterMean_map	nii.gz, json	Intercept from sLFO fit	Present if sLFO filtering is enabled (default) and outputlevel is ≥ normal
XXX_desc-lfofilterNoiseRemoved_timeseries	tsv.gz, json	Variance over space of data removed by the sLFO filter at each timepoint	Present if sLFO filtering is enabled (default) and outputlevel is ≥ less
XXX_desc-lfofilterNorm_map	nii.gz, json	Normalized fit coefficient	Present if sLFO filtering is enabled (default) and outputlevel is ≥ normal
XXX_desc-lfofilterNormDerivN_map	nii.gz, json	Normalized fit coefficient for the Nth temporal derivative	Present if sLFO filtering is enabled (default), regressderivs > 0, and outputlevel is max
XXX_desc-lfofilterR2_hist	tsv.gz, json	Histogram of sLFO filter R2 values	Present if sLFO filtering is enabled (default)
XXX_desc-lfofilterR2_map	nii.gz, json	Squared R value of the sLFO fit (proportion of variance explained)	Present if sLFO filtering is enabled (default) and outputlevel is ≥ less
XXX_desc-lfofilterR_map	nii.gz, json	R value of the sLFO fit	Present if sLFO filtering is enabled (default) and outputlevel is ≥ normal
XXX_desc-lfofilterRemoved_bold	nii.gz, json	sLFO signal filtered out of this voxel	Present if sLFO filtering is enabled (default) and outputlevel is ≥ more
XXX_desc-maxcorr_hist	tsv.gz, json	Histogram of maximum correlation coefficients	Always
XXX_desc-maxcorr_map	nii.gz, json	Maximum correlation strength	Always
XXX_desc-maxcorrsq_map	nii.gz, json	Squared maximum correlation strength (proportion of variance explained)	Always
XXX_desc-maxtime_hist	tsv.gz, json	Histogram of maximum correlation times	Always
XXX_desc-maxtime_map	nii.gz, json	Lag time in seconds	Always
XXX_desc-maxtimerefined_map	nii.gz, json	Lag time in seconds, refined	Always
XXX_desc-maxwidth_hist	tsv.gz, json	Histogram of correlation peak widths	Always
XXX_desc-maxwidth_map	nii.gz, json	Width of corrrelation peak	Always
XXX_desc-mean_map	nii.gz, json	Voxelwise mean of fmri data	Always
XXX_desc-medfiltregressderivratios_map	nii.gz, json	Median filtered version of the regressderivratios map	Present if outputlevel is ≥ normal
XXX_desc-mitimes_timeseries	tsv.gz, json	Cross mutual information time axis	Present if outputlevel is max
XXX_desc-movingregressor_timeseries	tsv.gz, json	The probe regressor used in each pass, at the time resolution of the data	Always
XXX_desc-MTT_hist	tsv.gz, json	Histogram of correlation peak widths	Always
XXX_desc-MTT_map	nii.gz, json	Mean transit time (estimated)	Always
XXX_desc-neglog10p_map	nii.gz, json	Negative log(10) of the p value of the r at each voxel	Present if numnull > 0
XXX_desc-nullsimfunc_hist	tsv.gz, json	Null correlation histogram	Present if numnull > 0
XXX_desc-oversampledmovingregressor_timeseries	tsv.gz, json	The probe regressor used in each pass, at the time resolution used for calculating the similarity function	Always
XXX_desc-preprocessedconfounds_timeseries	tsv.gz, json	The preprocessed (normalized, filtered, orthogonalized) set of expanded confound regressors used for prefiltering the data	Present if doing motion/confound regression
XXX_desc-processed_mask	nii.gz	No description	Always
XXX_desc-ratiotodelayfunc_timeseries	tsv.gz, json	The function mapping derivative ratio to delay	Present if outputlevel is ≥ less
XXX_desc-refine_mask	nii.gz, json	Voxels used for refinement	Present if passes > 1
XXX_desc-refinedmovingregressor_timeseries	tsv.gz, json	The raw and filtered probe regressor produced by the refinement procedure, at the time resolution of the data	Present if passes > 1
XXX_desc-regionalpostfilter_timeseries	tsv.gz, json	Regional timecourse averages	Present if sLFO filtering is enabled (default)
XXX_desc-regionalprefilter_timeseries	tsv.gz, json	Regional timecourse averages	Always
XXX_desc-regressderivratios_map	nii.gz, json	Ratio of the first derivative of delayed sLFO to the delayed sLFO	Present if outputlevel is ≥ normal
XXX_desc-runoptions_info	json	A detailed dump of all internal variables in the program. Useful for debugging and data provenance.	Always
XXX_desc-shiftedtcs_bold	nii.gz, json	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 is aligned.	Present if passes > 1 and outputlevel is max
XXX_desc-simdistdata_info	tsv.gz, json	Individual sham correlation datapoints	Present if numnull > 0
XXX_desc-sLFOamplitude_timeseries	tsv.gz, json	Filtered RMS amplitude of the probe regressor, and a linear fit	Always
XXX_desc-std_map	nii.gz, json	Voxelwise standard deviation of fmri data	Always
XXX_desc-timepercentile_map	nii.gz, json	Percentile ranking of this voxels delay	Always
XXX_desc-trimmedcorrtimes_timeseries	tsv.gz, json	Trimmed correlation time axis	Present if outputlevel is max
XXX_desc-trimmedmitimes_timeseries	tsv.gz, json	Trimmed cross mutual information time axis	Present if outputlevel is max
XXX_formattedcommandline	txt	Command line used to invoke rapidtide, nicely formatted	Always
XXX_log	txt	Diagnostic log file with a lot of informational output	Always
XXX_memusage	tsv	Memory usage statistics for performance tuning	Always

Output data size:

The amount of data output by rapidtide varies quite a bit, depending on your run options and the output level you select. What output level you use depends on what you are trying to do. The vast majority of the runtime of rapidtide is spent estimating, extracting and refining the sLFO signal, and calculating the voxelwise blood arrival time delay and signal strength. This produces a surprisingly small amount of data - the largest output files are the maps of the various hemodynamic parameters and some masks, each as large a single TR of the input data set. So at a minimum (as in, you select "--outputlevel min" and do not run sLFO denoising: "--nodenoise"), you produce 16 3D maps as NIFTI files, and a number of masks and timecourse files. For a single resting state run in the HCP-YA dataset, this is ~13MB of data (compared to the input data file size of about 1GB). If you want slightly more data to help you evaluate the fit quality, and make cool movies, you probably want to leave the outputlevel at the default of "normal".

You can calculate the output data size approximately with the following formulae (to first approximation, assuming that the image files dominate the size of the output data).

FMRISIZE is the number of TRs in the input fMRI data.

CORRFUNCSIZE is the size of the correlation function in TRs at the oversampled TR.

The TR oversampling factor is the smallest integer divisor of the fMRI TR that results in an oversampled TR <= 0.5 seconds.
CORRFUNCSIZE is the search range in seconds divided by the oversampled TR.

The output sizes in TRs (with no motion regression) are as follows:

Total image output data size in TRs
Output level	Passes>1?	Refine delay?	sLFO filter?	Number of TRs
min	No	No	No	15
min	No	Yes	No	18
min	Yes	No	No	15
min	Yes	Yes	No	18
min	No	No	Yes	16
min	Yes	No	Yes	16
less	No	No	No	15
less	No	Yes	No	19 + 1*FMRISIZE
less	Yes	No	No	15
less	Yes	Yes	No	19 + 1*FMRISIZE
normal	No	No	No	18 + 1*CORRFUNCSIZE
normal	No	Yes	No	26 + 1CORRFUNCSIZE + 1FMRISIZE
normal	Yes	No	No	18 + 1*CORRFUNCSIZE
normal	Yes	Yes	No	26 + 1CORRFUNCSIZE + 1FMRISIZE
more	No	No	No	18 + 1*CORRFUNCSIZE
more	No	Yes	No	26 + 1CORRFUNCSIZE + 2FMRISIZE
more	Yes	No	No	18 + 1*CORRFUNCSIZE
more	Yes	Yes	No	26 + 1CORRFUNCSIZE + 2FMRISIZE
max	No	No	No	18 + 3*CORRFUNCSIZE
max	No	Yes	No	26 + 3CORRFUNCSIZE + 3FMRISIZE
max	Yes	No	No	18 + 3*CORRFUNCSIZE
max	Yes	Yes	No	26 + 3CORRFUNCSIZE + 3FMRISIZE
max	No	No	Yes	19 + 3CORRFUNCSIZE + 1FMRISIZE
max	Yes	No	Yes	19 + 3CORRFUNCSIZE + 1FMRISIZE

The data size is then this number of TRs times the size of 1 TR worth of data in the input fMRI file, (plus the size of the various timecourse files and .json sidecars which are much smaller than the image files).

As an example, the following table shows the size of the data produced by running a rapidtide analysis on one HCP-YA resting state dataset with various output levels, with and without doing sLFO noise removal, either directly, or with the addition of one voxelwise time derivative. The correlation function fit was calculated from -5 to 10 seconds, resulting in a correlation function length of 41 points at the oversampled TR of 0.36 seconds. NB: motion regression is independent of the sLFO calculation, so to find the size of a sLFO filtered analysis with motion regression at a given output level, add the difference between the sizes of the motion regressed and non-motion regressed non-sLFO filtered analysis.

Output data size from running rapidtide on one HCP-YA rsfMRI dataset
Output level	Motion regression	sLFO filter?	Derivatives	Size in bytes
min	No	No		13M
min	Yes	No		15M
min	No	Yes	0	17M
min	No	Yes	1	17M
less	No	No		13M
less	Yes	No		15M
less	No	Yes	0	1.2G
less	No	Yes	1	1.2G
less	No	No		13M
less	Yes	No		15M
less	No	Yes	0	1.2G
less	No	Yes	1	1.2G
normal	No	No		86M
normal	Yes	No		88M
normal	No	Yes	0	1.3G
normal	No	Yes	1	1.3G
more	No	No		724M
more	Yes	No		702M
more	No	Yes	0	3.2G
more	No	Yes	1	3.2G
max	No	No		805M
max	Yes	No		2.9G
max	No	Yes	0	4.5G
max	No	Yes	1	5.7G

PRO TIP: Extraction of the sLFO regressor and calculation of the delay and strength maps take the VAST majority of the computation time, and generates only a small fraction of the data of a full analysis. If you are doing computation on AWS (where compute is cheap, storage is semi-pricey,and download costs are extortionate), it makes sense to do everything except sLFO filtering on your data, and download or store the outputs of that, only doing the sLFO filter step at the time when you need to do it. For example - running rapidtide on all of the HCP-YA resting state data generates less than 70GB of output data. That’s not too expensive to download, or store on S3, and costs nothing to upload. The denoised data, however is huge (bigger than the input dataset), so you don’t want to download it or even pay to store it for too long. So make it when you need it, use it for whatever, then throw it away, and make it again if you need it again. This will save you an enormous amount of money.

Usage:

Perform a RIPTiDe time delay analysis on a dataset.

usage: rapidtide [-h]
                 [--denoising | --delaymapping | --CVR | --globalpreselect]
                 [--venousrefine | --nirs] [--brainmask MASK[:VALSPEC]]
                 [--graymattermask MASK[:VALSPEC]]
                 [--whitemattermask MASK[:VALSPEC]] [--csfmask MASK[:VALSPEC]]
                 [--datatstep TSTEP | --datafreq FREQ] [--noantialias]
                 [--invert] [--interptype {univariate,cubic,quadratic}]
                 [--offsettime OFFSETTIME] [--autosync] [--dataiszeromean]
                 [--filterband {None,vlf,lfo,resp,cardiac,hrv_ulf,hrv_vlf,hrv_lf,hrv_hf,hrv_vhf,lfo_legacy,lfo_tight}]
                 [--filterfreqs LOWERPASS UPPERPASS]
                 [--filterstopfreqs LOWERSTOP UPPERSTOP]
                 [--filtertype {trapezoidal,brickwall,butterworth}]
                 [--butterorder ORDER] [--padseconds SECONDS]
                 [--padtype {reflect,zero,cyclic,constant,constant+}]
                 [--permutationmethod {shuffle,phaserandom}] [--numnull NREPS]
                 [--windowfunc {hamming,hann,blackmanharris,None}]
                 [--zeropadding PADVAL] [--detrendorder ORDER]
                 [--spatialfilt GAUSSSIGMA] [--premask] [--premasktissueonly]
                 [--globalmean] [--globalmeaninclude MASK[:VALSPEC]]
                 [--globalmeanexclude MASK[:VALSPEC]] [--motionfile MOTFILE]
                 [--motpowers N] [--nomotderiv] [--confoundfile CONFFILE]
                 [--confoundpowers N] [--noconfoundderiv]
                 [--noconfoundorthogonalize]
                 [--globalsignalmethod {sum,meanscale,pca,random}]
                 [--globalpcacomponents VALUE] [--slicetimes FILE]
                 [--numskip SKIP] [--timerange START END]
                 [--tincludemask FILE] [--texcludemask FILE] [--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,riptide}]
                 [--mutualinfosmoothingtime TAU] [--simcalcrange START END]
                 [--initialdelay DELAY]
                 [--searchrange LAGMIN LAGMAX | --nodelayfit]
                 [--sigmalimit SIGMALIMIT] [--bipolar] [--nofitfilt]
                 [--peakfittype {gauss,fastgauss,quad,fastquad,COM,None}]
                 [--despecklepasses PASSES] [--despecklethresh VAL]
                 [--baselinecutoff 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]
                 [--nopickleft] [--pickleftthresh THRESH]
                 [--sLFOnoiseampwindow SECONDS]
                 [--refineupperlag | --refinelowerlag]
                 [--refinetype {pca,ica,weighted_average,unweighted_average}]
                 [--pcacomponents VALUE] [--convergencethresh THRESH]
                 [--maxpasses MAXPASSES] [--nodenoise]
                 [--denoisesourcefile FILE] [--preservefiltering]
                 [--regressderivs NDERIVS] [--norefinedelay]
                 [--nofilterwithrefineddelay] [--delaypatchthresh NUMMADs]
                 [--delayoffsetspatialfilt GAUSSSIGMA]
                 [--outputlevel {auto,min,less,normal,more,max}] [--savelags]
                 [--histlen HISTLEN] [--saveintermediatemaps]
                 [--calccoherence] [--showtimings] [--version]
                 [--detailedversion] [--nprocs NPROCS] [--reservecpu]
                 [--mklthreads MKLTHREADS] [--nonumba] [--noprogressbar]
                 [--makepseudofile] [--checkpoint] [--spcalculation]
                 [--dpoutput] [--spatialtolerance EPSILON] [--cifti]
                 [--simulate] [--displayplots] [--nosharedmem]
                 [--infotag tagkey tagvalue] [--riptidestep STEP]
                 [--refinedelayeachpass] [--dofinalrefine] [--sLFOfiltmask]
                 [--territorymap MAP[:VALSPEC]] [--territorylabels FILE]
                 [--wiener] [--echocancel] [--autorespdelete] [--acfix]
                 [--negativegradient] [--cleanrefined]
                 [--donotfilterinputdata] [--dispersioncalc]
                 [--despeckle-patch-detection]
                 [--despeckle-patch-refkernel SIZE]
                 [--despeckle-patch-minsize NVOXELS]
                 [--despeckle-patch-consistency-ratio RATIO]
                 [--despeckle-patch-use-confidence]
                 [--despeckle-patch-confidence-weight WEIGHT]
                 [--despeckle-kernel SIZE] [--robustdelayfit]
                 [--robustdelay-dominance-threshold RATIO]
                 [--robustdelay-search-min-peak-fraction FRACTION]
                 [--robustdelay-search-width SECONDS] [--preppass]
                 [--preppass-lag-window SECONDS]
                 [--preppass-r2-threshold FLOAT] [--sharpenregressor]
                 [--sharpenregressor-thresh FLOAT]
                 [--sharpenregressor-noise-level FLOAT]
                 [--sharpenregressor-max-iters INT] [--prewhitenregressor]
                 [--prewhitenlags LAGS] [--refinedelay] [--nolimitoutput]
                 [--pickleft] [--noglm] [--debug] [--focaldebug] [--verbose]
                 [--disablecontainermemfix] [--alwaysmultiproc]
                 [--singleproc_confoundregress] [--singleproc_getNullDist]
                 [--singleproc_calcsimilarity] [--singleproc_peakeval]
                 [--singleproc_fitcorr] [--singleproc_refine]
                 [--singleproc_makelaggedtcs] [--singleproc_regressionfilt]
                 [--savecorrout] [--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, dolinfitfilt=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, gausssigma=2.5, refineoffset=True, refinedelay=True, outputlevel=’normal’. 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 regression fit 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, despecklepasses=0, refinedespeckle=False, outputlevel=’normal’, dolinfitfilt=False, saveintermediatemaps=False.

Default: False

Macros

Single arguments that change default values for many arguments. Macros override individually set parameters.

--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, dataiszeromean=True, refineprenorm=var, ampthresh=0.7, and lagminthresh=0.1.

Default: False

Anatomic information

These options allow you to tailor the analysis with some anatomic constraints. You don’t need to supply any of them, but if you do, rapidtide will try to make intelligent processing decisions based on these maps. Any individual masks set with anatomic information will be overridden if you specify that mask directly.

--brainmask: This specifies the valid brain voxels. No voxels outside of this mask will be used for global mean calculation, correlation, refinement, offset calculation, or denoising. If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise voxels with value > 0.1 are used. If this option is set, rapidtide will limit the include mask used to 1) calculate the initial global mean regressor, 2) decide which voxels in which to calculate delays, 3) refine the regressor at the end of each pass, 4) determine the zero time offset value, and 5) process to remove sLFO signal. Setting –initregressorinclude, –corrmaskinclude, –refineinclude or –offsetinclude explicitly will override this for the given include mask.
--graymattermask: This specifies a gray matter mask registered to the input functional data. If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise voxels with value > 0.1 are used. If this option is set, rapidtide will use voxels in the gray matter mask to calculate the initial global mean regressor. Setting –initregressorinclude explicitly will override this for the given include mask.
--whitemattermask: This specifies a white matter mask registered to the input functional data. If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise voxels with value > 0.1 are used. This will be used to calculate the white matter timecourse before running rapidtide, and after sLFO filtering (if enabled).
--csfmask: This specifies a CSF mask registered to the input functional data. If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise voxels with value > 0.1 are used. This will be used to calculate the CSF timecourse before running rapidtide, and after sLFO filtering (if enabled).

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

--dataiszeromean

Assume that the fMRI data is zero mean (this will be the case if you used AFNI for preprocessing). This affects how masks are generated. Rapidtide will attempt to detect this, but set explicitly if you know this is the case.

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). Set to 0 to disable.

Default: -1

--premask

Apply masking prior to spatial filtering to limit extracerebral sources (requires –brainmask)

Default: False

--premasktissueonly

Apply more stringent masking prior to spatial filtering, removing CSF voxels (requires –graymattermask and –whitemattermask).

Default: False

--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

--globalmeaninclude

Only use voxels in mask file NAME for the initial 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 the initial 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.

--motpowers

Include powers of each motion regressor up to order N. Default is 1 (no expansion).

Default: 1

--nomotderiv

Do not use derivatives in motion regression. Default is to use temporal derivatives.

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

--noconfoundderiv

Do not use derivatives in confound regression. Default is to use temporal derivatives.

Default: True

--noconfoundorthogonalize

Do not orthogonalize confound regressors prior to regressing them out of the data.

Default: True

--globalsignalmethod

Possible choices: sum, meanscale, pca, random

The method for constructing the initial signal regressor - straight summation, mean scaling each voxel prior to summation, MLE PCA of the voxels in the initial regressor mask, or initializing using random noise. Default is “sum.”

Default: 'sum'

--globalpcacomponents

Number of PCA components used for estimating the initial regressor. 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

--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)

--tincludemask

Only correlate during epochs specified in MASKFILE (NB: each line of FILE contains the time and duration of an epoch to include.

--texcludemask

Do not correlate during epochs specified in MASKFILE (NB: each line of FILE contains the time and duration of an epoch to exclude.

--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, lfo_tight

Filter data and regressors to specific band. Use “None” to disable filtering. Default is “lfo”. Ranges are: vlf: 0.0-0.009Hz, lfo: 0.01-0.15Hz, cardiac: 0.66-3.0Hz, hrv_ulf: 0.0-0.0033Hz, hrv_vlf: 0.0033-0.04Hz, hrv_lf: 0.04-0.15Hz, hrv_hf: 0.15-0.4Hz, hrv_vhf: 0.4-0.5Hz, lfo_legacy: 0.01-0.15Hz, lfo_tight: 0.01-0.1Hz

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 timecourse to be filtered to reduce end effects. Default is 30.0.

Default: 30.0

--padtype

Possible choices: reflect, zero, cyclic, constant, constant+

The type of padding at each end of a timecourse to be filtered to reduce end effects. Default is “reflect”.

Default: 'reflect'

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

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).

--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 “phat”.

Default: 'phat'

--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, riptide

Similarity metric for finding delay values. Choices are “correlation”, “mutualinfo”, “hybrid”, and “riptide”. 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

--initialdelay

Start the analysis with predefined delays. If DELAY is a filename, use it as an initial delay map; if DELAY is a float, initialize all voxels to a delay of DELAY seconds.

Default: 0.0

--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)

--nodelayfit

Fix the delay in every voxel to its initial value. Do not perform any fitting.

Default: False

--sigmalimit

Reject lag fits with linewidth wider than SIGMALIMIT seconds. Default is 1000.0 seconds.

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 is ‘auto’ (resolves to True unless overridden by a preset).

Default: 'auto'

--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 ‘auto’ (resolves to 4 unless overridden by a preset). Set to 0 to disable.

Default: auto

--despecklethresh

Refit correlation if median discontinuity magnitude exceeds VAL. Default is 5.0 seconds.

Default: 5.0

--baselinecutoff

Cutoff frequency (in seconds) of highpass filter to apply to the correlation function to eliminate baseline roll. Set to 0.0 to disable, negative to set automatically. Default is 0.0 seconds.

Default: 0.0

sLFO noise removal options

--nodenoise

Turn off regression filtering to remove delayed regressor from each voxel (disables output of fitNorm).

Default: True

--denoisesourcefile

Regress delayed regressors out of FILE instead of the initial fmri file used to estimate delays.

--preservefiltering

Don’t reread data prior to performing sLFO filtering. Default is ‘auto’ (resolves to False unless overridden by a preset).

Default: 'auto'

--regressderivs

When doing final sLFO filtering, include derivatives up to NDERIVS order. Default is 0

Default: 0

--norefinedelay

Do not calculate a refined delay map using sLFO regression information. Default is ‘auto’ (resolves to True unless overridden by a preset).

Default: 'auto'

--nofilterwithrefineddelay

Do not use the refined delay in sLFO filter.

Default: True

--delaypatchthresh

Maximum number of robust standard deviations to permit in the offset delay refine map. Default is 3.0

Default: 3.0

--delayoffsetspatialfilt

Spatially filter fMRI data prior to calculating delay offsets 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). Set to 0 to disable.

Default: -1

Output options

--outputlevel

Possible choices: auto, min, less, normal, more, max

The level of file output produced. ‘min’ produces only absolutely essential files, ‘less’ adds in the sLFO filtered data (rather than just filter efficacy metrics), ‘normal’ saves what you would typically want around for interactive data exploration, ‘more’ adds files that are sometimes useful, and ‘max’ outputs anything you might possibly want. Selecting ‘max’ will produce ~3x your input datafile size as output. Default is ‘auto’ (resolves to “normal” unless overridden by a preset).

Default: 'auto'

--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, mask (and shiftedtcs, if they’d normally be saved) for each pass. Default is ‘auto’ (resolves to False unless overridden by a preset).

Default: 'auto'

--calccoherence

Calculate and save the coherence between the final regressor and the data.

Default: False

--showtimings

Print out summary of run timing at the end of processing.

Default: False

Version options

--version: Show simplified version information and exit
--detailedversion: Show detailed version information and exit

Performance options

--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

--mklthreads

If mkl library is installed, use no more than MKLTHREADS worker threads in accelerated numpy calls. Set to -1 to use the maximum available. Default is 1.

Default: 1

--nonumba

By default, numba is used if present. Use this option to disable jit compilation with numba even if it is installed.

Default: False

Miscellaneous options

--noprogressbar

Will disable showing progress bars (helpful if stdout is going to a file).

Default: True

--makepseudofile

Make a simulated input file from the mean and the movingsignal.

Default: False

--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'

--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

--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

--nosharedmem

Disable use of shared memory for large array storage.

Default: True

--infotag

Additional key, value pairs to add to the options json file (useful for tracking analyses).

Experimental options (not fully tested, or not tested at all, may not work). Beware!

--riptidestep

Timestep between RIPTiDe regressors, in seconds. Default is 2.0.

Default: 2.0

--refinedelayeachpass

Do delay refinement in each pass.

Default: False

--dofinalrefine

Do regressor refinement on the final pass.

Default: False

--sLFOfiltmask

Limit sLFO filter to fit voxels.

Default: False

--territorymap

This specifies a territory map. Each territory is a set of voxels with the same integral value. If VALSPEC is given, only territories in the mask with integral values listed in VALSPEC are used, otherwise all nonzero voxels are used. If this option is set, certain output measures will be summarized over each territory in the map, in addition to over the whole brain. Some interesting territory maps might be: a gray/white/csf segmentation image, an arterial territory map, lesion area vs. healthy tissue segmentation, etc.

--territorylabels

The name of of a text file containing the labels of the territories, one per line. The first line is the label integer value 1, etc.

--wiener

Do Wiener deconvolution to find voxel transfer function.

Default: False

--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

--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

--donotfilterinputdata

Do not filter input data prior to similarity calculation. May make processing faster.

Default: True

--dispersioncalc

Generate extra data during refinement to allow calculation of dispersion.

Default: False

--despeckle-patch-detection

On despeckle passes 3+, detect large connected patches of shifted delay values using a large reference kernel and flag them for refitting. This catches patches that survive the median filter because they are locally consistent. This is the default.

Default: False

--despeckle-patch-refkernel

Size of the median filter kernel used to build the large-scale reference for patch detection. Must be odd. Larger values detect larger patches but may miss very large ones that approach half the kernel volume. Default is 9.

Default: 9

--despeckle-patch-minsize

Minimum number of connected voxels for a group to be considered a patch. Smaller clusters are ignored (handled by regular despeckle). Default is 10.

Default: 10

--despeckle-patch-consistency-ratio

Internal consistency threshold for patch detection: a candidate patch is confirmed only if its internal lag standard deviation divided by its offset from the exterior ring is less than this ratio. Lower values require more internally uniform patches. Default is 0.5.

Default: 0.5

--despeckle-patch-use-confidence

When detecting anomalous patches, use correlation quality metrics (R², peak strength) to modulate the detection threshold. Regions with poor fit quality are flagged as anomalous patches at a lower spatial threshold, improving sensitivity for borderline cases. Off by default.

Default: False

--despeckle-patch-confidence-weight

Weight [0.0..1.0] controlling how strongly fit confidence modulates the patch detection threshold when –despeckle-patch-use-confidence is active. 0.0 = no effect; 1.0 = maximum modulation. Default is 0.5.

Default: 0.5

--despeckle-kernel

Size of the despeckle kernel in each dimeension. Default is 3.

Default: 3

--robustdelayfit

After all despeckling passes, run anchor-based region growing to correct wrong-peak artifact patches. Correlation peaks are selected by spatial consistency rather than peak height, so the algorithm can recover voxels where the true-lag peak has been eroded below a sidelobe. Genuine vascular territory boundaries (including pathologically delayed territories) are preserved because the growing front stalls when no peak exists near the spatially extrapolated expected lag. Off by default.

Default: False

--robustdelay-dominance-threshold

Minimum ratio of the strongest to the second-strongest correlation peak for a voxel to qualify as an anchor in the robust delay estimation step. Higher values require a more clearly dominant peak. Default is 1.5.

Default: 1.5

--robustdelay-search-min-peak-fraction

A candidate peak must have absolute height >= min_peak_fraction * max peak height in that voxel’s corrout to be considered. Filters out noise bumps that could be selected when tau_expected falls between two genuine territory lags. Default is 0.2.

Default: 0.2

--robustdelay-search-width

Full width in seconds of the search window around the spatially extrapolated expected lag when looking for the true-lag peak during robust delay estimation. Should be less than the ACF sidelobe lag to avoid selecting the wrong peak. Default is 5.0 seconds.

Default: 5.0

--preppass

Run an internal single-pass correlation before the main passes to identify clean, short-delay voxels, then rebuild the global mean regressor from those voxels. This reduces sidelobe contamination from multi-pool vascular signals. Off by default.

Default: False

--preppass-lag-window

Width of the one-sided lag window below the modal lag used to select good voxels in the preparation pass. Only voxels with lag in [lag_mode - window, lag_mode] are considered clean. Default is 3.0 seconds.

Default: 3.0

--preppass-r2-threshold

Minimum R² value for a voxel to be selected as a clean voxel in the preparation pass. Default is 0.3.

Default: 0.3

--sharpenregressor

Apply Wiener deconvolution (with multi-echo iterative subtraction as fallback) to remove autocorrelation sidelobe structure from the regressor before computing correlations. Off by default.

Default: False

--sharpenregressor-thresh

Autocorrelation function sidelobe detection fraction. Controls the relative height of a sidelobe that triggers removal. Default is 0.1.

Default: 0.1

--sharpenregressor-noise-level

Wiener regularisation parameter λ for regressor sharpening. Controls the trade-off between noise suppression and sharpening. Default is 0.01.

Default: 0.01

--sharpenregressor-max-iters

Maximum number of iterations for the multi-echo fallback in regressor sharpening. Default is 5.

Default: 5

--prewhitenregressor

Prewhiten probe regressor prior to calculating correlations.

Default: False

--prewhitenlags

Set number of TRs to use in prewhitening. Set to -1 to calculate automatically. Default is -1.

Default: -1

Deprecated options. These options will go away in the indeterminate future. Don’t use them.

--refinedelay

Calculate a refined delay map using regression coefficient information. *DEPRECATED*: refinedelay is now on by default.

Default: True

--nolimitoutput

Save some of the large and rarely used files. *DEPRECATED*: Use ‘–outputlevel max’ instead.

Default: True

--pickleft

*DEPRECATED*: pickleft is now on by default. Use ‘nopickleft’ to disable it instead.

Default: True

--noglm

Turn off regression filtering to remove delayed regressor from each voxel (disables output of fitNorm).***DEPRECATED***: Use ‘–nodenoise’ instead.

Default: True

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

--focaldebug

Enable targeted additional debugging output (used during development).

Default: False

--verbose

Enable additional runtime information output.

Default: False

--disablecontainermemfix

Disable container 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_regressionfilt

Force single proc path for regression filtering.

Default: False

--savecorrout

Save the corrout file even if you normally wouldn’t.

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, slice acquisition time differences will show up as artifactual offsets in the delay maps if you don’t correct them beforehand. 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 sLFO 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.

TL;DR: ALL the filtering rapidtide does to the input data is discarded before the final filtering step. The ONLY filtering that is done to the lfoFilterCleaned dataset is removal of the moving sLFO regressor. There is NO other temporal, spatial, or confound filtering done to the final output data.

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). 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.

You can pass the confounds file from fMRIPrep (derivatives/fmriprep/sub-XXX/ses-XXX/func/XXX_desc-confounds_timeseries.tsv) directly to rapidtide as --motionfile. However, if you want to use the --confoundfile parameter, you need to create a reduced version of the confounds file with only the columns you want to use for confound regression.

You can also load the confounds file to identify non-steady-state volumes to use for the --numtozero parameter.

fMRIPrep includes the TR in the output NIfTI files’ headers, so you don’t need to provide --datatstep, and it usually performs slice timing correction (unless you don’t have slice timing information in your BIDS dataset or choose --ignore slicetiming), so you don’t need to use --slicetiming.

For most non-clinical participants, we recommend using the tissue type masks provided by fMRIPrep for many of the masks used in rapidtide. For example:

rapidtide \
    sub-XXX/func/sub-XXX_task-rest_space-MNI152NLin6Asym_res-2_desc-preproc_bold.nii.gz \
    /path/to/rapidtide/sub-XXX_task-rest_space-MNI152NLin6Asym_res-2 \
    --brainmask sub-XXX/anat/sub-XXX_space-MNI152NLin6Asym_res-2_desc-brain_mask.nii.gz \
    --graymattermask sub-XXX/anat/sub-XXX_space-MNI152NLin6Asym_res-2_desc-GM_probseg.nii.gz \
    --whitemattermask sub-XXX/anat/sub-XXX_space-MNI152NLin6Asym_res-2_desc-WM_probseg.nii.gz \
    --motionfile sub-XXX/func/sub-XXX_task-rest_desc-confounds_timeseries.tsv

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 [1]). 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 multiple regression 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 prefix outputname_ 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 sLFO filtration 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 --denoisesourcefile 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 \
    --denoisesourcefile 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 disease, 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 \
    --nodenoise \
    --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 exchangeable. 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 --nodenoise 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 multiple regression 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.

Getting an initial regressor from the Superior Sagittal Sinus (SSS)

Sometimes a subject will have severe pathology, such as a stroke, that will mean that the global mean signal has a wide distribution of delays, which will confuse rapidtide and make it hard to find the driving sLFO signal. In cases like this, using the SSS as a preselection mask is a very good solution. The only two complications are that 1) fMRIprep (which I tend to use) uses a very tight mask that pretty efficiently removes the SSS from preprocessed data, you have to get it from data prior to skull stripping. Because of that, 2) you often have to hand draw a mask, which is quite inconvenient (but on the plus side, the SSS is really easy to find - even physicists like me can get it reliably).

If you do have MNI152 data that somehow does NOT have the SSS stripped off, or if you’ve got the transverse sinus in your image (what the SSS drains into, often preserved in fMRIprep data), there’s another option. Go into the rapidtide/data/reference directory, which has all sorts of useful bric-a-brac and find “venous_sinus_template_2mm.nii.gz” (or 1mm, if you have that), and use it to set your initial regressor using –globalmeaninclude RAPIDTIDEROOT/rapidtide/data/reference/venous_sinus_template_2mm.nii.gz. That should get you a nice clean blood regressor.

CVR mapping:

This is a slightly different twist on interpreting the strength of the lagged correlation, validated in Donahue et al.[2]. 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 sLFO 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 fact - 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 thresholds 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.

Can I use this for other frequency ranges?:

This is actually two questions. The first is: “Can rapidtide be used to clean out noise in other frequency bands?” (to which the answer is very much yes - you can choose to run the rapidtide processing over a number of predefined ranges using the --filterband argument, or use arbitrary frequency limits with the --filterfreqs argument. This is in recognition of the fact that LFO, respiratory and cardiac noise are distinct phenomena, with different sources, spatial distributions, and propagation speeds. This type of processing was used in:

Tong, Y., Lindsey, K. P. & Frederick, B. deB. Partitioning of Physiological Noise Signals in the Brain with Concurrent Near-Infrared Spectroscopy and fMRI. J. Cereb. Blood Flow Metab. 31, 2352–2362 (2011). Tong et al.[3]
Frederick, B. deB., Nickerson, L. D. & Tong, Y. Physiological denoising of BOLD fMRI data using Regressor Interpolation at Progressive Time Delays (RIPTiDe) processing of concurrent fMRI and near-infrared spectroscopy (NIRS). NeuroImage 60, 1913–1923 (2012). Frederick et al.[4]
Tong, Y., Hocke, L. M. & Frederick, B. deB. Short repetition time multiband echo‐planar imaging with simultaneous pulse recording allows dynamic imaging of the cardiac pulsation signal. Magn. Reson. Med. 72, 1268–1276 (2014). Tong and Frederick[5]

The second, and more subtle question is “Is this useful?” (to which the answer is “yes and no”).

The sLFO signal is clearly traveling with bulk blood flow, giving it a range of delays of several seconds from the ascending carotid and vestibular arteries to the descending jugular veins. Rapidtide processing is a big win here, because simply regressing out the sLFO signal without accounting for delays 1) removes less signal than doing it properly and 2) introduces artifacts like negative correlations between unrelated regions.

As far as I’ve been able to tell, the respiratory noise (i.e. the direct breathing waveform, not derived metrics like RVT and the like, which seem to end up in the LFO band) doesn’t really have any sort of delay between voxels - the signal you want to remove appears to be synchronous across the brain, since it’s mostly due to a combination of respiratory related rigid body head motion and through space magnetic field shifts due to the lungs inflating. If you do phase sensitive reconstruction of the rs-fMRI data, the respiratory noise looks mostly like a periodic phase shift across the entire brain at the respiratory frequency, which sort of points to the second cause being more of an issue. So rapidtide doesn’t really buy you anything there - a simple GLM filter (and motion correction, especially if your acquisition is fast enough that respiration doesn’t alias - TR <= ~800ms) would probably work better.

The cardiac signal is the most interesting case - in most situations, the cardiac signal is pretty aliased, but if you have a sufficiently short TR (less than or equal to 415ms is good for up to 72bpm) that the fundamental of the cardiac signal is not aliased, then rapidtide is useful for noise removal (and mapping cardiac propagation, and all that). It’s very different from the delay maps you get from rapidtide, because the cardiac signal is a pressure wave, so it goes much faster than the blood that’s carrying it. The wave also propagates outside of the vessels, compressing tissue around the arteries and making waves that don’t closely follow the vasculature. So it is useful, but only if the acquisition supports it.

If you really want to remove cardiac noise, and you don’t have a sufficiently short TR (but you do have multiband data with an appropriate combination of TR and multi band factor), happy with the --temporalregression argument might be a better fit for you. The noise removal is still a little experimental, but I’ve been told people are using it and liking it.

rapidtide

Description:

Inputs:

Outputs:

BIDS Outputs:

Output data size:

Usage:

Positional Arguments

Analysis type

Macros

Anatomic information

Preprocessing options

Filtering options

Significance calculation options

Windowing options

Correlation options

Correlation fitting options

Regressor refinement options

sLFO noise removal options

Output options

Version options

Performance options

Miscellaneous options

Experimental options (not fully tested, or not tested at all, may not work). Beware!

Deprecated options. These options will go away in the indeterminate future. Don’t use them.

Debugging options. You probably don’t want to use any of these unless I ask you to to help diagnose a problem

Preprocessing for rapidtide

Working with standard fMRI packages

Analysis Examples:

Removing low frequency physiological noise from fMRI data

Removing low frequency physiological noise from fMRI data that has been processed with FIX

Mapping long time delays in response to a gas challenge experiment:

Getting an initial regressor from the Superior Sagittal Sinus (SSS)

CVR mapping:

Denoising NIRS data:

Can I use this for other frequency ranges?:

References