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.