3. analysis: Model specification for BIDS datasets

3.1. An overview of the analysis module

BIDS models

The BIDS Models specification is an extension to the BIDS standard for describing and organizing general linear models (GLMs) or similar models fitted to BIDS datasets.

A GLM can be concisely described with a json file, regardless of the software used to fit the model (e.g., nilearn, AfNI, FSL, SPM).

The PyBIDS analysis module provides high-level model specification functionality for BIDS datasets. It assumes that model information is represented in line with the (upcoming) BIDS-Model specification.

Note that, at present, pybids.modeling does not provide a one-stop model-fitting solution. You will need to call some other package (e.g., nilearn, or a non-Python package like FSL or SPM via Nipype) to handle model estimation. What pybids.modeling will do for you is automatically handle the loading and transformation of all variables, and the construction of design matrices and contrasts.

3.2. Quickstart

A simple example of standard usage follows. We assume that we have a root folder containing a BIDS-compliant project in /bidsproject, as well as a BIDS-Models JSON specification in model.json.

>>> from bids.modeling import BIDSStatsModelsGraph
>>> # Initialize the BIDSStatsModelsGraph
>>> analysis = BIDSStatsModelsGraph('/bidsproject', 'model1.json')
>>> # Setup constructs all the design matrices
>>> analysis.setup()
>>> # Sample query: retrieve first-level design matrix for one run
>>> dm = analysis[0].get_design_matrix(subject='01', run=1, task='taskA')
>>> # Sample query: retrieve session-level contrast matrix
>>> cm = analysis[1].get_contrasts(subject='01', session='retest')

Note

For a more detailed example, please refer to the Tutorial: Executing and inspecting StatsModels with pybids.modeling