Usage Notes

Warning

fMRIPost-rapidtide includes a tracking system to report usage statistics and errors for debugging and grant reporting purposes. Users can opt-out using the --notrack command line argument.

Execution and the BIDS format

The fMRIPost-rapidtide workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T1w structural image and (unless disabled with a flag) a BOLD series. We highly recommend that you validate your dataset with the free, online BIDS Validator.

The exact command to run fMRIPost-rapidtide depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

fmripost_rapidtide data/bids_root/ out/ participant -w work/

Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.

Command-Line Arguments

fMRIPost-rapidtide: fMRI POSTprocessing Rapidtide workflow v0.1.dev66+g06816c1

usage: fmripost_rapidtide [-h] [--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]
                          [--numnull NREPS] [--detrendorder ORDER]
                          [--spatialfilt GAUSSSIGMA] [--confoundfile CONFFILE]
                          [--confoundpowers N] [--noconfoundderiv]
                          [--globalsignalmethod {sum,meanscale,pca,random}]
                          [--globalpcacomponents VALUE] [--numskip NUMPOINTS]
                          [--timerange START END]
                          [--corrweighting {None,phat,liang,eckart,regressor}]
                          [--simcalcrange START END]
                          [--fixdelay DELAYTIME | --searchrange LAGMIN LAGMAX]
                          [--sigmalimit SIGMALIMIT] [--bipolar]
                          [--lagminthresh MIN] [--lagmaxthresh MAX]
                          [--ampthresh AMP] [--sigmathresh SIGMA]
                          [--pcacomponents VALUE] [--convergencethresh THRESH]
                          [--maxpasses MAXPASSES] [--glmsourcefile FILE]
                          [--regressderivs NDERIVS]
                          [--outputlevel {min,less,normal,more,max}]
                          [--territorymap MAP[:VALSPEC]] [--autorespdelete]
                          [--skip_bids_validation]
                          [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                          [-t TASK_ID] [--bids-filter-file FILE]
                          [-d PACKAGE=PATH [PACKAGE=PATH ...]]
                          [--bids-database-dir PATH] [--nprocs NPROCS]
                          [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_MB]
                          [--low-mem] [--use-plugin FILE] [--sloppy]
                          [--boilerplate-only] [--reports-only]
                          [--ignore {fieldmaps,slicetiming,jacobian} [{fieldmaps,slicetiming,jacobian} ...]]
                          [--dummy-scans DUMMY_SCANS]
                          [--random-seed _RANDOM_SEED] [--md-only-boilerplate]
                          [--aggregate-session-reports AGGR_SES_REPORTS]
                          [--track-carbon] [--country-code COUNTRY_CODE]
                          [--version] [-v] [-w WORK_DIR] [--clean-workdir]
                          [--resource-monitor] [--config-file FILE]
                          [--write-graph] [--stop-on-first-crash] [--notrack]
                          [--debug {compcor,fieldmaps,pdb,all} [{compcor,fieldmaps,pdb,all} ...]]
                          bids_dir output_dir {participant}

Positional Arguments

bids_dir

The root folder of a BIDS-valid raw dataset (sub-XXXXX folders should be found at the top level in this folder).

output_dir

The output path for the outcomes of preprocessing and visual reports

analysis_level

Possible choices: participant

Processing stage to be run, only ‘participant’ in the case of fMRIPost-rapidtide (see BIDS-Apps specification).

Preprocessing options

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

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

--noconfoundderiv

Toggle whether derivatives will be used in confound regression.

Default: True

--globalsignalmethod

Possible choices: sum, meanscale, pca, random

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

Default: 'sum'

--globalpcacomponents

Number of PCA components used for estimating the global signal. 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: 0.8

--numskip

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

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

Significance calculation options

--numnull

Estimate significance threshold by running NREPS null correlations. Set to 0 to disable.

Default: 10000

Correlation options

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

--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: (-30.0, 30.0)

--sigmalimit

Reject lag fits with linewidth wider than SIGMALIMIT Hz.

Default: 1000.0

--bipolar

Bipolar mode - match peak correlation ignoring sign.

Default: False

Regressor refinement options

--lagminthresh

For refinement, exclude voxels with delays less than MIN.

Default: 0.25

--lagmaxthresh

For refinement, exclude voxels with delays greater than MAX.

Default: 3.0

--ampthresh

For refinement, exclude voxels with correlation coefficients less than AMP. 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: 100.0

--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: 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 occurred.

Default: 15

GLM noise removal options

--glmsourcefile

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

--regressderivs

When doing final GLM, include derivatives up to NDERIVS order.

Default: 0

Output options

--outputlevel

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

The level of file output produced. ‘min’ produces only absolutely essential files, ‘less’ adds in the GLM 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: 'normal'

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

--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. NB: at the moment this is just a placeholder - it doesn’t do anything.

--autorespdelete

Attempt to detect and remove respiratory signal that strays into the LFO band.

Default: False

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation

Assume the input dataset is BIDS compliant and skip the validation

Default: False

--participant-label, --participant_label

A space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)

-t, --task-id

Select a specific task to be processed

--bids-filter-file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://fmriprep.readthedocs.io/en/latest/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep

-d, --derivatives

Search PATH(s) for pre-computed derivatives. These may be provided as named folders (e.g., –derivatives smriprep=/path/to/smriprep).

--bids-database-dir

Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.

Options to handle performance

--nprocs, --nthreads, --n_cpus, --n-cpus

Maximum number of threads across all processes

--omp-nthreads

Maximum number of threads per-process

--mem, --mem_mb, --mem-mb

Upper bound memory limit for fMRIPost-rapidtide processes

--low-mem

Attempt to reduce memory usage (will increase disk usage in working directory)

Default: False

--use-plugin, --nipype-plugin-file

Nipype plugin configuration file

--sloppy

Use low-quality tools for speed - TESTING ONLY

Default: False

Options for performing only a subset of the workflow

--boilerplate-only, --boilerplate_only

Generate boilerplate only

Default: False

--reports-only

Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Default: False

Workflow configuration

--ignore

Possible choices: fieldmaps, slicetiming, jacobian

Ignore selected aspects of the input dataset to disable corresponding parts of the resampling workflow (a space delimited list)

Default: []

--dummy-scans

Number of nonsteady-state volumes. Overrides automatic detection.

--random-seed

Initialize the random seed for the workflow

Options for modulating outputs

--md-only-boilerplate

Skip generation of HTML and LaTeX formatted citation with pandoc

Default: False

--aggregate-session-reports

Maximum number of sessions aggregated in one subject’s visual report. If exceeded, visual reports are split by session.

Default: 4

Options for carbon usage tracking

--track-carbon

Tracks power draws using CodeCarbon package

Default: False

--country-code

Country ISO code used by carbon trackers

Default: 'CAN'

Other options

--version

show program’s version number and exit

-v, --verbose

Increases log verbosity for each occurrence, debug level is -vvv

Default: 0

-w, --work-dir

Path where intermediate results should be stored

Default: /home/docs/checkouts/readthedocs.org/user_builds/fmripost-rapidtide/checkouts/latest/docs/work

--clean-workdir

Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of fMRIPost-rapidtide.

Default: False

--resource-monitor

Enable Nipype’s resource monitoring to keep track of memory and CPU usage

Default: False

--config-file

Use pre-generated configuration file. Values in file will be overridden by command-line arguments.

--write-graph

Write workflow graph.

Default: False

--stop-on-first-crash

Force stopping on first crash, even if a work directory was specified.

Default: False

--notrack

Opt-out of sending tracking information of this run to the FMRIPREP developers. This information helps to improve FMRIPREP and provides an indicator of real world usage crucial for obtaining funding.

Default: False

--debug

Possible choices: compcor, fieldmaps, pdb, all

Debug mode(s) to enable. ‘all’ is alias for all available modes.

Reusing precomputed derivatives

Reusing a previous, partial execution of fMRIPost-rapidtide

fMRIPost-rapidtide will pick up where it left off a previous execution, so long as the work directory points to the same location, and this directory has not been changed/manipulated. Some workflow nodes will rerun unconditionally, so there will always be some amount of reprocessing.

Troubleshooting

Logs and crashfiles are output into the <output dir>/fmripost_rapidtide/sub-<participant_label>/log directory. Information on how to customize and understand these files can be found on the Debugging Nipype Workflows page.

Support and communication. The documentation of this project is found here: https://fmripost_rapidtide.org/en/latest/.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/nipreps/fmripost_rapidtide/issues.

If you have a problem or would like to ask a question about how to use fMRIPost-rapidtide, please submit a question to NeuroStars.org with an fmripost_rapidtide tag. NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.

Previous questions about fMRIPost-rapidtide are available here: https://neurostars.org/tag/fmripost_rapidtide/

To participate in the fMRIPost-rapidtide development-related discussions please use the following mailing list: https://mail.python.org/mailman/listinfo/neuroimaging Please add [fmripost_rapidtide] to the subject line when posting on the mailing list.

About the NiPreps framework licensing

Please check https://www.nipreps.org/community/licensing/ for detailed information on the criteria we use to license fMRIPost-rapidtide and other projects of the framework.

License information

Copyright (c) the NiPreps Developers.

fMRIPost-rapidtide is licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright (c), the fMRIPost-rapidtide developers and the CRN. All rights reserved.

All trademarks referenced herein are property of their respective holders.