Usage Notes

Warning

This app runs on fMRIprep derivatives (versions prior to 24.0.0), fMRIprep needs to be run prior to running fMRIStroke. Derivatives obtained with other tools will most likely not work on this tool.

Execution and the BIDS format

The fMRIStoke workflow takes as principal input the path of the dataset that is to be processed and the path to the fMRIprep derivatives. The input dataset must include at least one T1w structural image, an ROI mask of the stroke lesion and a BOLD series.

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

fmristroke data/bids_root/ out/ participant -w work/ --fmriprep_dir derivatives/

ROI mask in BIDS format

Lesion masks should be binary NIfTI images (damaged areas = 1, everywhere else = 0) in the same space and resolution as the T1w image, and use the _roi suffix, for example, sub-01_label-lesion_roi.nii.gz. This file should be located in the sub-01/anat directory of the BIDS dataset. Since lesion masks are not yet part of the BIDS standard, it is also necessary to add a .bidsignore file in the root of the BIDS dataset to prevent the BIDS validator from raising errors. Your .bidsignore file should contain the following line:

*_roi.nii.gz

Note

As mentioned by the fMRIprep documentation (v23.x.x): The lesion masking instructions in this section predate the release of BIDS Derivatives. As of BIDS 1.4.0, the recommended naming convention is:

manual_masks/
└─ sub-001/
   └─ anat/
      ├─ sub-001_desc-tumor_mask.nii.gz
      └─ sub-001_desc-tumor_mask.json

In an upcoming version, fmriprep will search for lesion masks as pre-computed derivatives. Until this is supported, we will continue to look for the _roi suffix.

Command-Line Arguments

fMRIStroke: fMRI Stroke workflows v1.0.0

usage: fmristroke [-h]
                  [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                  [--bids-filter-file FILE] [--fmriprep_dir PATH]
                  [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
                  [--mem MEMORY_MB] [--low-mem] [--use-plugin FILE]
                  [--reports-only] [--boilerplate-only]
                  [--output-spaces [OUTPUT_SPACES ...]] [--session-level]
                  [--croprun CROPRUN]
                  [--output_pipelines OUTPUT_PIPELINES [OUTPUT_PIPELINES ...]]
                  [--conn_measure {covariance,correlation,partial correlation,tangent,precision} [{covariance,correlation,partial correlation,tangent,precision} ...]]
                  [--output_atlases OUTPUT_ATLASES [OUTPUT_ATLASES ...]]
                  [--ncomp_method {varexp,aic,kic,mdl}]
                  [--ica_method {canica,dictlearning}]
                  [--lower_cutoff LOWER_CUTOFF] [--upper_cutoff UPPER_CUTOFF]
                  [--maxlag MAXLAG] [--fs-license-file FILE] [--freesurfer]
                  [-w WORK_DIR] [--clean-workdir] [--resource-monitor]
                  [--config-file FILE] [--write-graph] [-v]
                  [--stop-on-first-crash]
                  bids_dir output_dir {participant}

Positional Arguments

bids_dir

The root folder of a BIDS valid 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 fMRIStroke as fMRIprep (see BIDS-Apps specification).

Options for filtering BIDS queries

--participant-label, --participant_label

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

--bids-filter-file

A JSON file describing custom BIDS input filters using PyBIDS.

--fmriprep_dir

Derivatives from fMRIPrep run

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

--low-mem

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

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

Nipype plugin configuration file

Options for performing only a subset of the workflow

--reports-only

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

--boilerplate-only, --boilerplate_only

Only generate boilerplate for the workflow.

Workflow configuration

--output-spaces

Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form <SPACE>[:cohort-<label>][:res-<resolution>][...], where <SPACE> is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. Important to note, the res-* modifier does not define the resolution used for the spatial normalization. To generate no BOLD outputs, use this option without specifying any spatial references. For further details, please check out https://fmriprep.readthedocs.io/en/latest/spaces.html

--session-level

Run analysis at session level, when multiple run of same session and task, concatenate the runs together

--croprun

Crop beginning of run when session-level is true and runs are concatenated, crops the first n TR of fMRI before concatenating

Denoising pipeline configuration

--output_pipelines

Pipelines to use for denoising, space separated pipeline name, accepts either json file describing pipeline or name of pipeline from package.

Connectivity configuration

--conn_measure

Possible choices: covariance, correlation, partial correlation, tangent, precision

method to measure functional connectivity, space delimited

--output_atlases

Atlases for connectivity estimation

Options relating to confounds

--ncomp_method

Possible choices: varexp, aic, kic, mdl

method to estimate number of components for ICA lesion confounds

--ica_method

Possible choices: canica, dictlearning

Method to run ICA lesion

--lower_cutoff, --lower-cutoff

lower cutoff for nilearn.masking.compute_epi_mask

--upper_cutoff, --upper-cutoff

upper cutoff for nilearn.masking.compute_epi_mask

Specific options for hemodynmics analysis

--maxlag

Max lag for hemodynamic analysis

Specific options for FreeSurfer preprocessing

--fs-license-file

Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

--freesurfer

Was freesurfer run

Other options

-w, --work-dir

Path where intermediate results should be stored

--clean-workdir

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

--resource-monitor

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

--config-file

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

--write-graph

Write workflow graph.

-v, --verbose

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

--stop-on-first-crash

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

Troubleshooting

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

Support and communication. The documentation of this project is found here: http://fmristroke.readthedocs.org/en/latest/.

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