FitLins is a tool for estimating linear models, defined by the BIDS Model specification proposal, to BIDS-formatted datasets.
This software is in alpha stage, and should be considered unstable. Users are welcome to test the software, and open issues.
The CLI follows the BIDS-Apps convention:
Usage:
fitlins <bids_root> <out_dir> <analysis_level> [--model <model_name>]
See the output of fitlins --help
for all valid options:
usage: fitlins [-h] [-v] [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-m MODEL] [-d DERIVATIVES [DERIVATIVES ...]] [--derivative-label DERIVATIVE_LABEL] [--space {MNI152NLin2009cAsym,}] [--force-index FORCE_INDEX] [--ignore IGNORE] [--desc-label DESC_LABEL] [-s TYPE:FWHM] [--n-cpus N_CPUS] [--debug] [-w WORK_DIR] bids_dir output_dir {run,session,participant,dataset} FitLins: Workflows for Fitting Linear models to fMRI 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 {run,session,participant,dataset} processing stage to be run (see BIDS-Apps specification). optional arguments: -h, --help show this help message and exit -v, --version show program's version number and exit Options for filtering BIDS queries: --participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...] one or more participant identifiers (the sub- prefix can be removed) -m MODEL, --model MODEL location of BIDS model description -d DERIVATIVES [DERIVATIVES ...], --derivatives DERIVATIVES [DERIVATIVES ...] location of derivatives (including preprocessed images). If none specified, indexes all derivatives under bids_dir/derivatives. --derivative-label DERIVATIVE_LABEL execution label to append to derivative directory name --space {MNI152NLin2009cAsym,} registered space of input datasets. Empty value for no explicit space. --force-index FORCE_INDEX regex pattern or string to include files --ignore IGNORE regex pattern or string to ignore files --desc-label DESC_LABEL use BOLD files with the provided description label Options for preprocessing BOLD series: -s TYPE:FWHM, --smoothing TYPE:FWHM Smooth BOLD series with FWHM mm kernel prior to fitting. Valid types: iso (isotropic); e.g., `--smothing iso:5` will use an isotropic 5mm FWHM kernel Options to handle performance: --n-cpus N_CPUS maximum number of threads across all processes --debug run debug version of workflow Other options: -w WORK_DIR, --work-dir WORK_DIR path where intermediate results should be stored
At present, FitLins does not operate in subject-native space. It is developed against FMRIPREP-preprocessed datasets, but is intended to work with any dataset following the BIDS Derivatives draft specification.
By default, FitLins will look for a model.json
in the root of the BIDS
directory.
A simple example model for OpenFMRI dataset ds000030 is reproduced below:
{ "name": "ds000030_bart", "description": "model for balloon analog risk task", "input": { "task": "bart" }, "blocks": [ { "level": "run", "transformations": [ { "name": "factor", "input": [ "trial_type", "action" ] }, { "name": "and", "input": [ "trial_type.BALOON", "action.ACCEPT" ], "output": [ "accept" ] }, { "name": "and", "input": [ "trial_type.BALOON", "action.EXPLODE" ], "output": [ "explode" ] } ], "model": { "HRF_variables":[ "accept", "explode" ], "variables": [ "accept", "explode", "FramewiseDisplacement", "X", "Y", "Z", "RotX", "RotY", "RotZ" ] }, "contrasts": [ { "name": "accept_vs_explode", "condition_list": [ "accept", "explode" ], "weights": [1, -1], "type": "T" } ] }, { "level": "dataset", "model": { "variables": [ "accept_vs_explode" ] }, "contrasts": [ { "name": "group_accept_vs_explode", "condition_list":[ "accept_vs_explode" ], "weights": [1], "type": "T" } ] } ] }
Additional examples can be found in the models branch of the main FitLins repository.
Note
The BIDS Model specification is a draft standard, and some details may change over time.
FitLins is in Alpha-stage, and is not suitable for use as a library, as the internal organization may change substantially without deprecation periods. Similarly the outputs (or derivatives) are subject to change, as experience and user feedback prompt. The command-line interface outlined above should be fairly stable, however.