Usage Notes

Warning

sMRIPost-LINC requires preprocessing outputs in MNI152NLin6Asym space with 2 mm3 voxels (i.e., res-02). Make sure you run fMRIPrep with --output-spaces MNI152NLin6Asym:res-02.

Warning

sMRIPost-LINC 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 sMRIPost-LINC 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 sMRIPost-LINC depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

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

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

Command-Line Arguments

sMRIPost-LINC: fMRI POSTprocessing AROMA workflow v0.1.dev5+g899b498

usage: smripost_linc [-h] [--anat-only] [--atlases ATLAS [ATLAS ...]]
                     [--min-coverage MIN_COVERAGE] [--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] [--fs-license-file PATH]
                     [--fs-subjects-dir PATH] [--nprocs NPROCS]
                     [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_MB]
                     [--low-mem] [--use-plugin FILE] [--sloppy]
                     [--boilerplate-only] [--reports-only]
                     [--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 or sMRIPrep derivatives dataset (sub-XXXXX folders should be found at the top level in this folder).

output_dir

The output path for the outcomes of postprocessing and visual reports

analysis_level

Possible choices: participant

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

Options for anatomical postprocessing

--anat-only

Run anatomical processing only

Options for parcellation

--atlases

Selection of atlases to apply to the data. All of sMRIPost-LINC’s built-in atlases are used by default.

--min-coverage, --min_coverage

Coverage threshold to apply to parcels in each atlas. Any parcels with lower coverage than the threshold will be replaced with NaNs. Must be a value between zero and one, indicating proportion of the parcel. Default is 0.5.

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation

Assume the input dataset is BIDS compliant and skip the validation

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

Search PATH(s) for pre-computed derivatives or BIDS-atlas datasets. These may be provided as named folders (e.g., –datasets 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.

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

--fs-subjects-dir

Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)

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 sMRIPost-LINC processes

--low-mem

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

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

Nipype plugin configuration file

--sloppy

Use low-quality tools for speed - TESTING ONLY

Options for performing only a subset of the workflow

--boilerplate-only, --boilerplate_only

Generate boilerplate only

--reports-only

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

Options for modulating outputs

--md-only-boilerplate

Skip generation of HTML and LaTeX formatted citation with pandoc

--aggregate-session-reports

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

Options for carbon usage tracking

--track-carbon

Tracks power draws using CodeCarbon package

--country-code

Country ISO code used by carbon trackers

Other options

--version

show program’s version number and exit

-v, --verbose

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

-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 sMRIPost-LINC.

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

--stop-on-first-crash

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

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

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

sMRIPost-LINC 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>/smripost_linc/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://smripost_linc.org/en/latest/.

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

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

Previous questions about sMRIPost-LINC are available here: https://neurostars.org/tag/smripost_linc/

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

About the NiPreps framework licensing

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

License information

Copyright (c) the NiPreps Developers.

sMRIPost-LINC 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 sMRIPost-LINC developers and the CRN. All rights reserved.

All trademarks referenced herein are property of their respective holders.