Usage

Execution and the BIDS format

The FitLins workflow takes as principal inputs a BIDS dataset, one or more derivative datasets, and a BIDS Stats Models file. We recommend using fMRIPrep for preprocessing your dataset.

The exact command to run fitlins depends on the Installation method. The common parts of the command follow the BIDS-Apps definition.

Example:

fitlins data/bids_root/ out/ participant \
    -d data/derivatives/fmriprep/ -w work/

Command-Line Arguments

FitLins: Workflows for Fitting Linear models to fMRI

usage: fitlins [-h] [--version] [-v] [-q]
               [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [-m MODEL] [-d DERIVATIVES [DERIVATIVES ...]]
               [--derivative-label DERIVATIVE_LABEL] [--space SPACE]
               [--force-index FORCE_INDEX [FORCE_INDEX ...]]
               [--ignore IGNORE [IGNORE ...]] [--desc-label DESC_LABEL]
               [--database-path DATABASE_PATH] [-s FWHM[:LEVEL:[TYPE]]]
               [--n-cpus N_CPUS] [--mem-gb MEM_GB] [--debug] [--reports-only]
               [-w WORK_DIR] [--drop-missing]
               [--estimator {nistats,nilearn,afni}]
               [--drift-model {polynomial,cosine,None}] [--error-ts]
               bids_dir output_dir {run,session,participant,dataset}

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: run, session, participant, dataset

processing stage to be runa (see BIDS-Apps specification).

Named Arguments

--version

show program’s version number and exit

-v, --verbose

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

-q, --quiet

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

Options for filtering BIDS queries

--participant-label

one or more participant identifiers (the sub- prefix can be removed)

-m, --model

location of BIDS model description

-d, --derivatives

location of derivatives (including preprocessed images).If none specified, indexes all derivatives under bids_dir/derivatives.

--derivative-label

DEPRECATED. Was “execution label to append to derivative directory name”

--space

registered space of input datasets. Empty value for no explicit space.

--force-index

regex pattern or string to include files

--ignore

regex pattern or string to ignore files

--desc-label

use BOLD files with the provided description label

--database-path

Path to directory containing SQLite database indices for this BIDS dataset. If a value is passed and the file already exists, indexing is skipped.

Options for preprocessing BOLD series

-s, --smoothing

Smooth BOLD series with FWHM mm kernel prior to fitting at LEVEL. Optional analysis LEVEL (default: l1) may be specified numerically (e.g., l1) or by name (run, subject, session or dataset). Optional smoothing TYPE (default: iso) must be one of: iso (isotropic additive smoothing), isoblurto (isotropic smoothing progressivley applied till the target smoothness is reached). e.g., –smoothing 5:dataset:iso will perform a 5mm FWHM isotropic smoothing on subject-level maps, before evaluating the dataset level.

Options to handle performance

--n-cpus

maximum number of threads across all processes

--mem-gb

maximum amount of memory to allocate across all processes

--debug

run debug version of workflow

--reports-only

skip running of workflow and generate reports

Other options

-w, --work-dir

path where intermediate results should be stored

--drop-missing

drop missing inputs/contrasts in model fitting.

--estimator

Possible choices: nistats, nilearn, afni

Estimator to use to fit the (first level) models.| nilearn: Default estimator using nilearn.glm| nistats: Deprecated synonym for nilearn| afni: 3dREMLfit

--drift-model

Possible choices: polynomial, cosine, None

specifies the desired drift model

--error-ts

save error time series for first level models. Currently only implemented for afni estimator.

A Note about Processing CIFTIs

FitLins (as of v0.7.0) can process CIFTI outputs (e.g., from fMRIPrep’s --cifti-output flag). For FitLins to load fMRIPrep CIFTI outputs, define --space fsLR and --desc-label "". The FitLins statistical map outputs will be saved as .dscalar.nii images. Figures in the reports will include a surface representation as well as separate images for subcortical regions.