API#

At the highest levels bidspm is organized in workflows:

they all start with the prefix bids (for example bidsRealignReslice)
they are in the folder src.workflows
they run on all the subjects specified in the options structure.

Most workflows run by creating matlab batches that are saved as .mat files in a jobs then passed to the SPM jobman to run. To do this the workflows call “batch creating functions”:

all start with the prefix setBatch (for example setBatchCoregistration).
are in the folder src.batches.

Many workflows include some post-processing steps (like file renaming) after the execution of the batch, so in many cases the output of running just the batch and running the whole workflow will be different.

Preprocessing, Statistics and Fieldmaps handling have their own document pages.

Other workflows, batches and related helper functions are listed below.

workflows#

bidsChangeSuffix(varargin)#

USAGE:

bidsChangeSuffix(opt, newSuffix, 'filter', struct([]), 'force', false)

Parameters:

opt (structure) – Options chosen for the analysis. To test the output, set opt.dryRun to true. See checkOptions().
newSuffix (char)
filter (structure) – structure to decide which files to include. Default: struct([]) for no filter
force (logical) – If set to true it will overwrite already existing files. Default: false

EXAMPLE:

opt.dir.input = path_to_dataset;
opt.dryRun = true;

newSuffix = 'vaso';

filter = struct('suffix', 'bold');

bidsChangeSuffix(opt, newSuffix, ...
                'filter', filter, ...
                'force', false)

bidsCheckVoxelSize(opt)#

Check that all file to preprocess have the same voxel size

USAGE:

status = bidsCheckVoxelSize(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

bidsCopyInputFolder(varargin)#

Copies data from the opt.dir.input folder to the opt.dir.output folder

Then it will search the derivatives directory for any zipped *.gz image and uncompress the files of interest.

USAGE:

bidsCopyInputFolder(opt, 'unzip', true, 'force', true)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
unzip (logical) – defaults to true
force (logical) – defaults to true

roi#

bidsCreateROI(opt)#

Use CPP_ROI and marsbar to create a ROI in MNI space based on a given atlas and inverse normalize those ROIs in native space if requested.

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

USAGE:

% to create ROI in MNI space
opt.dir.roi = pwd;
opt.roi.atlas = 'wang';
opt.roi.hemi = {'L', 'R'};
opt.roi.name = {'V1v', 'V1d'};
opt.roi.space = {'IXI549Space'};

bidsCreateROI(opt);


% to create ROI in subject space
opt.dir.roi = pwd;
opt.roi.atlas = 'wang';
opt.roi.hemi = {'L', 'R'};
opt.roi.name = {'V1v', 'V1d'};
opt.roi.space = {'IXI549Space', 'individual'};
opt.dir.input = fullfile(opt.dir.raw, '..', 'derivatives', 'bidspm-preproc');

bidsCreateROI(opt);

bidsRoiBasedGLM(opt)#

Will run a GLM within a ROI using MarsBar.

USAGE:

bidsRoiBasedGLM(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

skipped:

Will compute the absolute maximum percent signal change and the time course of the events or blocks of contrast specified in the BIDS model and save and plot the results in tsv / json / jpeg files.

Warning

If your blocks are modelled as series of fast paced “short” events, the results of this workflow might be misleading. It might be better to make sure that the each block has a single event with a “long” duration.

Adapted from the MarsBar tutorial: lib/CPP_ROI/lib/marsbar-0.44/examples/batch

See: bidsCreateRoi(), plotRoiTimeCourse(), getEventSpecificationRoiGlm()

QA#

bidsQA(opt, varargin)#

Run QA on a BIDS dataset.

Find outliers in MRIQC output or to view number of outlier timepoints (for a given metric and threshold) in each functional run

USAGE:

figurePath = bidsQA(opt, varargin);

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

bidsQAbidspm(opt)#

Run QA on preproc output generated by bidspm.

USAGE:

bidsQAbidspm(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

For each run works on the realigned (and unwarped) data:

plots motion, global signal, framewise displacement

bidsQAmriqc(opt, suffix)#

uses the report from MRIQC (bold and T1) identify outliers using robust statistics (interquartile range).

https://mriqc.readthedocs.io/en/stable/iqms/bold.html https://mriqc.readthedocs.io/en/stable/iqms/t1w.html

USAGE:

bidsQAmriqc(opt, suffix);

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

EXAMPLE:

opt.dir.mriqc = '/home/remi/gin/dataset/derivatives/mriqc';

bidsQAmriqc(opt, 'T1w');
bidsQAmriqc(opt, 'bold');

Dependencies (in case you want to use it as standalone):

bids-matlab

bidsQApreproc(opt, varargin)#

Use confounds preprocessed datasets to estimate the number of timepoints with values superior to threshold.

Plots the proportion of timepoints per run (to identify runs with that goes above a limit).

USAGE:

figurePath = bidsQApreproc(opt, 'metric', metric, 'threshold', threshold);

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
metric (char) – default = ‘framewise_displacement’
threshold – default = 0.2
threshold – numeric

lesion#

bidsLesionAbnormalitiesDetection(opt, extraOptions)#

Use the ALI toolbox to detect lesion abnormalities in anatomical image after segmentation of the image.

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

bidsLesionAbnormalitiesDetection(opt, extraOptions)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
extraOptions (structure) – Options chosen for analysis of another dataset in case they need to be merged. See checkOptions().

Lesion abnormalities detection will be performed using the information provided from the lesion segmentation output in BIDS format.

bidsLesionOverlapMap(opt)#

Creates lesion overlap map on the anatomical image after initial segmentation and lesion abnormality detection of the image.

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

bidsLesionOverlapMap(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Lesion overlap map will be created using the information provided from the Lesion abnormalities detection output in BIDS format.

bidsLesionSegmentation(opt)#

Use the ALI toolbox to perform segmentation to detect lesions of anatomical image.

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

bidsLesionSegmentation(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Segmentation will be performed using the information provided in the BIDS data set.

stats#

bidsConcatBetaTmaps(opt, deleteTmaps)#

Make 4D images of beta and t-maps for the MVPA.

USAGE:

bidsConcatBetaTmaps(opt, deleteIndTmaps)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
deleteIndTmaps (logical) – decide to delete t-maps. Default to false.

A valid BIDS stats model is required for this workflow: this is because the beta images to concatenate are those of the conditions mentioned in the DummyContrasts of the RUN level of the BIDS stats model.

When concatenating betamaps:

Ensures that there is only 1 image per “contrast”.
Creates a tsv that lists the content of the 4D image.
This TSV is in the subject level GLM folder where the beta map came from.
This TSV file is named sub-subLabel_task-taskName_space-space_labelfold.tsv.

bidsFFX(varargin)#

specify the subject level fMRI model
estimates it
do both in one go
or compute the contrasts

To run this workflows get the BOLD input images from derivatives BIDS dataset that contains the preprocessed data and get the condition, onsets, durations from the events files in the raw BIDS dataset.

For the model specification, if opt.model.designOnly is set to true, then it is possible to specify a model with no data: this can useful for debugging or to quickly inspect designs specification.

For the model estimation, it is possible to do some rough QA, by setting opt.QA.glm.do = true.

USAGE:

bidsFFX(action, opt, 'nodeName', 'run_level')

Parameters:: action (char) – Action to be conducted

'specify' to specify the fMRI GLM
'specifyAndEstimate' for fMRI design + estimate
'contrasts' to estimate contrasts.

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char) – Only for action 'contrasts'. Specifies which Node to work on.

bidsModelSelection(varargin)#

Uses the MACS toolbox to perform model selection.

USAGE:

bidsModelSelection(opt, 'action', 'all')

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
action (char) – any of 'all', 'modelSpace', 'cvLME', 'posterior', 'BMS'

Steps are performed in that order:

MA_model_space: defines a model space
MA_cvLME_auto: computes cross-validated log model evidence
MS_PPs_group_auto: calculate posterior probabilities from cvLMEs
MS_BMS_group_auto: perform cross-validated Bayesian model selection
MS_SMM_BMS: generate selected models maps from BMS

'all' : performs 1 to 5
'modelSpace': : performs step 1
'cvLME': performs steps 1 and 2
'posterior': performs steps 1 and 3, assuming step 2 has already been run
'BMS': performs 1, 4 and 5, assuming step 2 and 3 have already been run

This way you can run all steps at once:

.. code-block:: matlab

bidsModelSelection(opt, ‘action’, ‘all’);

Or in sequence (can be useful to split running cvLME in several batches of subjects)

bidsModelSelection(opt, 'action', 'cvLME');
bidsModelSelection(opt, 'action', 'posterior');
bidsModelSelection(opt, 'action', 'BMS');

Requirements:

define the list of BIDS stats models in a cell string of fullpaths
```
opt.toolbox.MACS.model.files
```
all models must have the same space and task defined in their inputs
for a given subject / model, all runs must have the same numbers of regressors This requires to create dummy regressors in case some subjects are missing a condition or a confound. This can be done by using the bidsFFX(opt) with the option opt.glm.useDummyRegressor set to true.

Note

Adding dummy (empty) regressors will make your model non-estimable by SPM, where as the MACS toolbox can deal with this.

specify each model for each subject

opt = opt_stats_subject_level();

opt.glm.useDummyRegressor = true;

models = opt.toolbox.MACS.model.files

for i = 1:numel(models)
  opt.model.file = models{i};
  bidsFFX('specify', opt);
end

For more information see the toolbox manual in the folder lib/MACS/MACS_Manual.

Links:

MACS toolbox repo

If you use this workflow, please cite the following paper:

@article{soch2018jnm,
  title={MACS - a new SPM toolbox for model assessment, comparison and selection.},
  author={Soch J, Allefeld C},
  journal={Journal of Neuroscience Methods},
  year={2018},
  volume={306},
  doi={https://doi.org/10.1016/j.jneumeth.2018.05.017}
}

If you use cvBMS or cvBMA, please also cite the respective method:

@article{soch2016nimg,
  title={How to avoid mismodelling in GLM-based fMRI data analysis:
         cross-validated Bayesian model selection.},
  author={Soch J, Haynes JD, Allefeld C},
  journal={NeuroImage},
  year={2016},
  volume={141},
  doi={https://doi.org/10.1016/j.neuroimage.2016.07.047}
}

@article{soch2017nimg,
  title={How to improve parameter estimates in GLM-based fMRI data analysis:
         cross-validated Bayesian model averaging.},
  author={Soch J, Meyer AP, Haynes JD, Allefeld C},
  journal={NeuroImage},
  year={2017},
  volume={158},
  doi={https://doi.org/10.1016/j.neuroimage.2017.06.056}
}

bidsRFX(varargin)#

creates a mean structural image and mean mask over the sample

specifies and estimates the group level model,
computes the group level contrasts.

USAGE:

bidsRFX(action, opt, 'nodeName', '')

Parameters:

action (char) – Action to be conducted: 'RFX' or 'meanAnatAndMask' or 'contrast'
opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char) – name of the BIDS stats model to run analysis on

bidsResults(varargin)#

Computes the results for a series of contrast that can be specified at the run, subject or dataset step level (see contrast specification following the BIDS stats model specification).

USAGE:

bidsResults(opt,'nodeName', '')

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions
nodeName (char or cellstr) – name of the BIDS stats model Node(s) to show results of

Below is an example of how specify the option structure to get some specific results outputs for certain contrasts.

See the online documentation for example of those outputs.

The field opt.results allows you to get results from several Nodes from the BIDS stats model. So you could run bidsResults once to view results from the subject and the dataset level.

Specify a default structure result for this node:

opt.results(1) = defaultResultsStructure();

Specify the Node name (usually “run_level”, “subject_levle” or “dataset_level”):

opt.results(1).nodeName = 'subject_level';

Specify the name of the contrast whose result we want to see. This must match one of the existing contrats (dummy contrast or contrast) in the BIDS stats model for that Node:

opt.results(1).name = 'listening_1';

For each contrat, you can adapt:

voxel level threshold (p) [between 0 and 1]
cluster level threshold (k) [positive integer]
type of multiple comparison (MC):
- 'FWE' is the default
- 'FDR'
- 'none'

You can thus specify something different for a second contrast:

opt.results(2).name = {'listening_lt_baseline'};
opt.results(2).MC =  'none';
opt.results(2).p = 0.01;
opt.results(2).k = 0;

Specify how you want your output (all the following are on false by default):

% simple figure with glass brain view and result table
opt.results(1).png = true();

% result table as a .csv: very convenient when comes the time to write papers
opt.results(1).csv = true();

% thresholded statistical map
opt.results(1).threshSpm = true();

% binarised thresholded statistical map (useful to create ROIs)
opt.results(1).binary = true();

You can also create a montage to view the results with opt.results(1).csv = true(); activation neuroanatomical location will be labelled. You can specify the atlas to use for that by choosing between

'Neuromorphometrics' (default)
'aal'
'visfatlas'
'anatomy_toobox'
'hcpex'
'glasser'
'wang'

opt.results(1).atlas = 'Neuromorphometrics';

on several slices at once:

opt.results(1).montage.do = true();

% slices position in mm [a scalar or a vector]
opt.results(1).montage.slices = -0:2:16;

% slices orientation: can be 'axial' 'sagittal' or 'coronal'
% axial is default
opt.results(1).montage.orientation = 'axial';

% path to the image to use as underlay
% Will use the SPM MNI T1 template by default
opt.results(1).montage.background = ...
     fullfile(spm('dir'), 'canonical', 'avg152T1.nii');

% Can also be a structure to pick up the correct file for each subject
% opt.results(1).montage.background = struct('suffix', 'T1w', ...
%                                            'desc', 'preproc', ...
%                                            'modality', 'anat');

Finally you can export as a NIDM results zip files.

NIDM results is a standardized results format that is readable by the main neuroimaging software (SPM, FSL, AFNI). Think of NIDM as BIDS for your statistical maps. One of the main other advantage is that it makes it VERY easy to share your group results on neurovault (which you should systematically do).

NIDM paper
NIDM specification
NIDM results viewer for SPM <https://github.com/incf-nidash/nidmresults-spmhtml>

To generate NIDM results zip file for a given contrats simply:

opt.results(1).nidm = true();

bidsSmoothContrasts(varargin)#

smooths all contrast images created at the subject level

USAGE:

bidsSmoothContrasts(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

preproc#

bidsCreateVDM(opt)#

Creates the voxel displacement maps from the fieldmaps of a BIDS dataset.

USAGE:

bidsCreateVDM(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Inspired from spmup spmup_BIDS_preprocess (@ commit 198c980d6d7520b1a99) (URL missing)

bidsGenerateT1map(opt)#

Brief workflow description

USAGE:

bidsGenerateT1map(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

bidsRealignReslice(opt)#

Realigns and reslices the functional data of a given task.

USAGE:

bidsRealignReslice(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Assumes that bidsSTC() has already been run if opt.stc.skip is not set to true.

bidsRealignUnwarp(opt)#

Realigns and unwarps the functional data of a given task.

USAGE:

bidsRealignReslice(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Assumes that bidsSTC has already been run.

If the bidsCreateVDM() workflow has been run before the voxel displacement maps will be used unless opt.useFieldmaps is set to false.

bidsRemoveDummies(varargin)#

Removes dummies from functional files

USAGE:

bidsRemoveDummies(opt, 'dummyScans', someInteger, 'force', false)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
dummyScans (integer >= 0) – number of volumes to remove
force (logical) – use 'force', true to remove dummy scans even if metadata say they have already been removed

EXAMPLE:

opt.taskName = 'auditory';
opt.dir.input = fullfile(pwd, 'inputs', 'raw');
bidsRemoveDummies(opt, 'dummyScans', 4, 'force', false);

bidsResliceTpmToFunc(opt)#

Reslices the tissue probability map (TPMs) from the segmentation to the mean functional and creates a mask for the bold mean image

USAGE:

bidsResliceTpmToFunc(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

Assumes that the anatomical has already been segmented by bidsSpatialPrepro() or bidsSegmentSkullStrip().

It is necessary to run this workflow before running the bidsQAbidspm() pipeline as the computation of the tSNR by spmup requires the TPMs to have the same dimension as the functional.

bidsSTC(opt)#

Performs the slice timing correction of the functional data.

USAGE:

bidsSTC(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

STC will be performed using the information provided in the BIDS data set. It will use the mid-volume acquisition time point as as reference.

In general slice order and reference slice is entered in time unit (ms) (this is the BIDS way of doing things) instead of the slice index of the reference slice (the “SPM” way of doing things).

If no slice timing information is available from the file metadata this step will be skipped.

bidsSegmentSkullStrip(opt)#

Segments and skullstrips the anatomical image. This workflow is already included in the bidsSpatialPrepro workflow.

USAGE:

bidsSegmentSkullStrip(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

bidsSmoothing(opt)#

This performs smoothing to the functional data using a full width half maximum smoothing kernel of size “opt.fwhm.func”.

USAGE:

bidsSmoothing(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

bidsSpatialPrepro(opt)#

Performs spatial preprocessing of the functional and anatomical data.

The anatomical data are segmented, skull-stripped [and normalized to MNI space].

The functional data are re-aligned (unwarped), coregistered with the anatomical, [and normalized to MNI space].

Assumes that bidsSTC() has already been run if opt.stc.skip is not set to true.

USAGE:

bidsSpatialPrepro([opt])

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

If you want to:

only do realign and not realign AND unwarp, make sure you set opt.realign.useUnwarp to false.
normalize the data to MNI space, make sure opt.space includes IXI549Space.

See the preprocessing section of the FAQ to know at what resolution files are resampled during normalization.

If you want to:

use another type of anatomical data than T1w as a reference or want to specify which anatomical session is to be used as a reference, you can set this in opt.bidsFilterFiler.t1w:
```
opt.bidsFilterFiler.t1w.suffix = 'T1w';
opt.bidsFilterFiler.t1w.ses = 1;
```

bidsWholeBrainFuncMask(opt)#

Create segmented-skull stripped mean functional image

USAGE:

mask = bidsWholeBrainFuncMask(opt)

batches#

saveMatlabBatch(matlabbatch, batchType, opt, subLabel)#

Saves the matlabbatch job in a .m file. Environment information are saved in a .json file.

USAGE:

saveMatlabBatch(matlabbatch, batchType, opt, [subLabel])

Parameters:

matlabbatch (structure)
batchType (char)
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

The .m file can directly be loaded with the SPM batch or run directly by SPM standalone or SPM docker.

The .json file also contains heaps of info about the “environment” used to set up that batch including the version of:

OS,
MATLAB or Octave,
SPM,
bidspm

This can be useful for methods writing though if the the batch is generated in one environment and run in another (for example set up the batch with Octave on Mac OS and run the batch with Docker SPM), then this information will be of little value in terms of computational reproducibility.

setBachRename(varargin)#

USAGE:

matlabbatch = setBachRename(matlabbatch, files, moveTo, patternReplace, overwriteDuplicate)

Returns:

matlabbatch:: (cell) The matlabbatch ready to run the spm job

setBatch3Dto4D(matlabbatch, opt, volumesList, RT, outputName, dataType)#

Set the batch for 3D to 4D conversion

USAGE:

matlabbatch = setBatch3Dto4D(matlabbatch, volumesList, RT, [outputName], [dataType])

Parameters:

matlabbatch (structure)
volumesList (array) – List of volumes to be converted in a single 4D brain
outputName (char) – The string that will be used to save the 4D brain
dataType (integer) – It identifies the data format conversion
RT (float) – It identifies the TR in seconds of the volumes to be written in the 4D file header

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

dataType:

0: SAME
2: UINT8 - unsigned char
4: INT16 - signed short
8: INT32 - signed int
16: FLOAT32 - single prec. float
64: FLOAT64 - double prec. float

setBatchImageCalculation(varargin)#

Set a batch for a image calculation

USAGE:

matlabbatch = setBatchImageCalculation(matlabbatch, input, output, outDir, expression)

Parameters:

matlabbatch (structure)
input (cell) – list of images
output (char) – name of the output file
outDir (char) – output directory
expression (char) – mathematical expression to apply (for example ‘(i1+i2)>3’)
expression – data type that must be one of the following: - ‘uint8’ - ‘int16’ (default) - ‘int32’ - ‘float32’ - ‘float64’ - ‘int8’ - ‘uint16’ - ‘uint32’

See spm_cfg_imcalc.m for more information:

``edit(fullfile(spm('dir'), 'config', 'spm_cfg_imcalc.m'))``

Returns:: matlabbatch

setBatchMeanAnatAndMask(matlabbatch, opt, outputDir)#

Creates batxh to create mean anatomical image and a group mask

USAGE:

matlabbatch = setBatchMeanAnatAndMask(matlabbatch, opt, funcFWHM, outputDir)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
outputDir (string)

Returns:

matlabbatch

Return type:

structure

setBatchPrintFigure(matlabbatch, opt, figureName)#

template to create new setBatch functions

USAGE:

matlabbatch = setBatchPrintFigure(matlabbatch, figureName)

Parameters:

matlabbatch
figureName (string)

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

setBatchReorient(varargin)#

Set up a batch to reorient images.

USAGE:

matlabbatch = setBatchReorient(matlabbatch, opt, images, reorientMatrix, 'prefix', '')

Parameters:

matlabbatch (cell) – matlabbatch to append to.
opt (structure) – Options chosen for the analysis. See checkOptions().
images (cell string)
reorientMatrix – 4 X 4 transformation matrix or .mat file containing a transformationMatrix variable
prefix (char)

Returns:

matlabbatch:: (cell) The matlabbatch ready to run the spm job

setBatchSelectAnat(matlabbatch, BIDS, opt, subLabel)#

Creates a batch to set an anatomical image

USAGE:

matlabbatch = setBatchSelectAnat(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure) – list of SPM batches
BIDS (structure) – dataset layout. See: bids.layout(), getData().
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch

Return type:

structure

matlabbatch = setBatchSelectAnat(matlabbatch, BIDS, opt, subLabel)

image type = opt.bidsFilterFiler.t1w.suffix (default = T1w)
session to select the anat from opt.bidsFilterFiler.t1w.ses (default = 1)

We assume that the first anat of that type is the “correct” one

lesion#

setBatchLesionAbnormalitiesDetection(matlabbatch, opt, images)#

Creates a batch to detect lesion abnormalities

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

matlabbatch = setBatchLesionAbnormalitiesDetection(matlabbatch, BIDS, opt, subLabel)

Parameters:: matlabbatch (structure) – list of SPM batches
Returns:: matlabbatch
Return type:: structure

setBatchLesionOverlapMap(matlabbatch, BIDS, opt, subLabel)#

Creates a batch for the lesion overlap map

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

matlabbatch = setBatchLesionOverlapMap(matlabbatch, BIDS, opt, subLabel)

Parameters:: matlabbatch (structure) – list of SPM batches
Returns:: matlabbatch
Return type:: structure

setBatchLesionSegmentation(matlabbatch, BIDS, opt, subLabel)#

Creates a batch to segment the anatomical image for lesion detection

Requires the ALI toolbox: https://doi.org/10.3389/fnins.2013.00241

USAGE:

matlabbatch = setBatchSegmentationDetectLesion(matlabbatch, BIDS, opt, subLabel)

Parameters:: matlabbatch (structure) – list of SPM batches
Returns:: matlabbatch
Return type:: structure

stats#

setBatchContrasts(matlabbatch, opt, spmMatFile, consess)#

Add a contrast to the batch for SPM.

USAGE:

matlabbatch = setBatchContrasts(matlabbatch, opt, spmMatFile, consess)

Parameters:

matlabbatch (cell)
opt (structure) – Options chosen for the analysis. See checkOptions().
spmMatFile (char)
consess (cell)

Returns:

matlabbatch

Return type:

structure

setBatchEstimateModel(matlabbatch, opt, tmp, contrastsList, groups)#

Set up the estimate model batch for run/subject or group level GLM

USAGE:

% for subject level
matlabbatch = setBatchEstimateModel(matlabbatch, opt, subLabel)

% for group level
matlabbatch = setBatchEstimateModel(matlabbatch, opt, nodeName, contrastsList, groups)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char)
contrastsList (cell string)

Returns:

matlabbatch

Return type:

structure

setBatchFactorialDesign(matlabbatch, opt, nodeName)#

Handles group level GLM specification

USAGE:

[matlabbatch, contrastsList] = setBatchFactorialDesign(matlabbatch, opt, nodeName)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char)

Returns:

matlabbatch

Return type:

structure

setBatchFactorialDesignGlobalCalcAndNorm(factorialDesign)#

USAGE:

factorialDesign = setBatchFactorialDesignGlobalCalcAndNorm(factorialDesign)

setBatchFactorialDesignImplicitMasking(factorialDesign)#

USAGE:

factorialDesign = setBatchFactorialDesignImplicitMasking(factorialDesign)

setBatchGoodnessOfFit(matlabbatch, opt)#

setBatchGroupLevelContrasts(matlabbatch, opt, nodeName)#

USAGE:

matlabbatch = setBatchGroupLevelContrasts(matlabbatch, opt, nodeName)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char)

Returns:

matlabbatch

setBatchGroupLevelResults(varargin)#

USAGE:

matlabbatch = setBatchGroupLevelResults(matlabbatch, opt, result)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
result (structure)

Returns:

matlabbatch

Return type:

structure

setBatchInformationCriteria(matlabbatch, opt, outputDir)#

setBatchResults(matlabbatch, opt, result)#

Outputs the typical matlabbatch to compute the result for a given contrast

Common for all type of results: run, session, subject, dataset

USAGE:

matlabbatch = setBatchResults(matlabbatch, opt, result)

Parameters:

matlabbatch (structure)
results (structure)

results.dir = ffxDir;
results.contrastNb = conNb;
results.label = subLabel;
results.nbSubj = 1;

Returns:: matlabbatch
Return type:: structure

See: setBatchSubjectLevelResults(), setBatchGroupLevelResults()

setBatchSubjectLevelContrasts(matlabbatch, opt, subLabel, nodeName)#

set batch for run and subject level contrasts

USAGE:

matlabbatch = setBatchSubjectLevelContrasts(matlabbatch, opt, subLabel, nodeName)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

Returns:

matlabbatch

See also: bidsFFX, specifyContrasts(), setBatchContrasts()

setBatchSubjectLevelGLMSpec(varargin)#

Sets up the subject level GLM

USAGE:

matlabbatch = setBatchSubjectLevelGLMSpec(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure)
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

Returns:

matlabbatch

Return type:

structure

setBatchSubjectLevelResults(varargin)#

USAGE:

matlabbatch = setBatchSubjectLevelResults(matlabbatch, opt, subLabel, result)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

Returns:

matlabbatch

Return type:

structure

preproc#

setBatchComputeVDM(matlabbatch, fmapType, refImage)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchComputeVDM(matlabbatch, fmapType, refImage)

Parameters:

matlabbatch (structure) – list of SPM batches
fmapType (char) – ''phasediff'' or 'phase&mag'
refImage – Reference image

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

matlabbatch = setBatchComputeVDM(type)

adapted from spmup get_FM_workflow.m (@ commit 198c980d6d7520b1a996f0e56269e2ceab72cc83)

setBatchCoregistration(varargin)#

Set the batch for coregistering the source images into the reference image

USAGE:

matlabbatch = setBatchCoregistration(matlabbatch, opt, ref, src, other)

Parameters:

matlabbatch (structure) – list of SPM batches
opt (structure) – Options chosen for the analysis. See checkOptions().
ref (char) – Reference image
src (char) – Source image
other (cell string) – Other images to apply the coregistration to

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

setBatchCoregistrationFmap(matlabbatch, BIDS, opt, subLabel)#

Set the batch for the coregistration of field maps

USAGE:

matlabbatch = setBatchCoregistrationFmap(matlabbatch, BIDS, opt, subLabel)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

TODO implement for ‘phase12’, ‘fieldmap’, ‘epi’

setBatchCoregistrationFuncToAnat(matlabbatch, BIDS, opt, subLabel)#

Set the batch for coregistering the functional images to the anatomical image.

USAGE:

matlabbatch = setBatchCoregistrationFuncToAnat(matlabbatch, BIDS, subLabel, opt)

Parameters:

matlabbatch (structure) – list of SPM batches
BIDS (structure) – dataset layout. See: bids.layout, getData
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

setBatchCreateVDMs(matlabbatch, BIDS, opt, subLabel)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchCreateVDMs(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure)
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

TODO implement for ‘phase12’, ‘fieldmap’, ‘epi’

setBatchGenerateT1map(varargin)#

batch to create a T1 and R1 map from MP2RAGE

USAGE:

matlabbatch = setBatchGenerateT1map(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (cell) – matlabbatch to append to.
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch:: (cell) The matlabbatch ready to run the spm job

Relies on the MP2RAGE toolbox for SPM.

benoitberanger/mp2rage

Some non-BIDS metadata need to be added to the JSON files of the inversion images for this to work (check the README of the toolbox for more info):

EchoSpacing
SlicePartialFourier or PartialFourierInSlice: between 0 and 1 (example: 6/8)
FatSat: must be “yes” or “no”

Most of the those metadata should be available from the PDF of with yout sequence details.

setBatchInverseNormalize(matlabbatch, BIDS, opt, subLabel, imgToResample)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchNormalize(matlabbatch, deformField, subLabel, imgToResample)

Parameters:: matlabbatch (structure)
Returns:: matlabbatch
Return type:: structure

setBatchNormalizationSpatialPrepro(matlabbatch, BIDS, opt, voxDim)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchNormalizationSpatialPrepro(matlabbatch, opt, voxDim)

Parameters:

matlabbatch (structure)
opt (array) – Options chosen for the analysis. See checkOptions().
voxDim

Returns:

matlabbatch

Return type:

structure

setBatchNormalize(matlabbatch, deformField, voxDim, imgToResample)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchNormalize(matlabbatch [, deformField] [, voxDim] [, imgToResample])

Parameters:

matlabbatch (structure)
deformField
voxDim
imgToResample

Returns:

matlabbatch

Return type:

structure

setBatchRealign(varargin)#

Set the batch for realign / realign and reslice / realign and unwarp

USAGE:

[matlabbatch, voxDim] = setBatchRealign(matlabbatch, ...
                                        BIDS, ...
                                        opt, ...
                                        subLabel, ...
                                        [action = 'realign'])

Parameters:

matlabbatch (cell) – SPM batch
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label
action (char) – realign, realignReslice, realignUnwarp, 'reslice'

Returns:

matlabbatch - :voxDim: (array) - :srcMetadata: (structure)

Return type:

structure

setBatchRenameSegmentParameter(varargin)#

USAGE:

matlabbatch = setBachRenameSegmentParameter(matlabbatch, opt)

Parameters:

matlabbatch (cell) – matlabbatch to append to.
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

matlabbatch The matlabbatch ready to run the spm job

Return type:

cell

setBatchReslice(matlabbatch, opt, referenceImg, sourceImages, interp)#

Set the batch for reslicing source images to the reference image resolution

USAGE:

matlabbatch = setBatchReslice(matlabbatch, opt, referenceImg, sourceImages, interp)

Parameters:

matlabbatch (structure) – list of SPM batches
opt (structure) – Options chosen for the analysis. See checkOptions().
referenceImg (char or cellstring) – Reference image (only one image)
sourceImages (char or cellstring) – Source images
interp (integer >= 0) – type of interpolation to use (default = 4). Nearest neighbour = 0.

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

setBatchSTC(varargin)#

Creates batch for slice timing correction

USAGE:

matlabbatch = setBatchSTC(matlabbatch, BIDS, opt, subLabel)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

Slice timing units is in seconds to be BIDS compliant and not in slice number as is more traditionally the case with SPM.

If no slice order can be found, the slice timing correction will not be performed.

If not specified in the options, this function will take the mid-volume time point as reference to do the slice timing correction.

setBatchSaveCoregistrationMatrix(matlabbatch, BIDS, opt, subLabel)#

Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchSaveCoregistrationMatrix(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure)
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)

Returns:

matlabbatch

setBatchSegmentation(matlabbatch, opt, imageToSegment)#

Creates a batch to segment the anatomical image

USAGE:

matlabbatch = setBatchSegmentation(matlabbatch, opt)

Parameters:

matlabbatch (structure) – list of SPM batches
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

matlabbatch

Return type:

structure

setBatchSkullStripping(matlabbatch, BIDS, opt, subLabel)#

Creates a batch to compute a brain mask based on the tissue probability maps from the segmentation.

USAGE:

matlabbatch = setBatchSkullStripping(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure) – list of SPM batches
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch, The matlabbatch ready to run the spm job

Return type:

structure

This function will get its inputs from the segmentation batch by reading the dependency from opt.orderBatches.segment. If this field is not specified it will try to get the results from the segmentation by relying on the anat image returned by getAnatFilename.

The threshold for inclusion in the mask can be set by:

opt.skullstrip.threshold (default = 0.75)

Any voxel with p(grayMatter) + p(whiteMatter) + p(CSF) > threshold will be included in the skull stripping mask.

It is also possible to segment a functional image by setting opt.skullstrip.mean to true

Skullstripping can be skipped by setting opt.skullstrip.do to false

setBatchSmoothConImages(matlabbatch, opt)#

Creates a batch to smooth all the con images of all subjects

USAGE:

matlabbatch = setBatchSmoothConImages(matlabbatch, opt)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

matlabbatch

setBatchSmoothing(matlabbatch, opt, images, fwhm, prefix)#

Small wrapper to create smoothing batch

USAGE:

matlabbatch = setBatchSmoothing(matlabbatch, opt, images, fwhm, prefix)

Parameters:

matlabbatch (structure)
opt (structure) – Options chosen for the analysis. See checkOptions().
images (fullpath)
fwhm (positive integer)
prefix (char)

Returns:

matlabbatch

Return type:

structure

See also: bidsSmoothing, bidsRFX(), setBatchSmoothingFunc(), setBatchSmoothConImages()

setBatchSmoothingAnat(matlabbatch, BIDS, opt, subLabel)#

Creates a batch to smooth the anat files of a subject

USAGE:

matlabbatch = setBatchSmoothingAnat(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure)
BIDS (structure) – dataset layout.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel

Returns:

matlabbatch

Return type:

structure

See also: bidsSmoothing, setBatchSmoothing()

setBatchSmoothingFunc(matlabbatch, BIDS, opt, subLabel)#

Creates a batch to smooth the bold files of a subject

USAGE:

matlabbatch = setBatchSmoothingFunc(matlabbatch, BIDS, opt, subLabel)

Parameters:

matlabbatch (structure)
BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Returns:

matlabbatch

Return type:

structure

See also: bidsSmoothing, setBatchSmoothing()

IO#

addGitIgnore(fullpath)#

Adds a basic gitignore

USAGE:

addGitIgnore(fullpath)

Parameters:: fullpath – char

addLicense(fullpath)#

Copy CCO license in directory

USAGE:

addLicense(fullpath)

Parameters:: fullpath – char

addReadme(fullpath)#

Adds a basic README

USAGE:

addReadme(fullpath)

Parameters:: fullpath – char

cleanCrash()#

Removes any files left over from a previous unfinished run of the pipeline, like any *.png imgages

USAGE:

cleanCrash()

convertRealignParamToTsv(rpTxtFile, opt, rmInput)#

Convert SPM typical realignement files to a BIDs compatible TSV one.

USAGE:

rpTsvFile = convertRealignParamToTsv(rpTxtFile, opt, rmInput)

Parameters:

rpTxtFile (path) – path to SPM realignement parameter txt file.
opt (structure) – Options chosen for the analysis. See checkOptions().
rmInput (logical) – Optional. Default to false. If true remove original txt file.

createDerivativeDir(opt)#

Creates the derivative folder if it does not exist.

USAGE:

opt = createDerivativeDir(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

getData(varargin)#

Reads the specified BIDS data set and updates the list of subjects to analyze.

USAGE:

[BIDS, opt] = getData(opt, bidsDir, indexDependencies)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
bidsDir (char) – the directory where the data is ; defaults to fullfile(opt.dataDir, '..', 'derivatives', 'bidspm')
indexDependencies (logical) – Use 'index_dependencies', true in bids.layout.
layoutFilter (struct) – filter to pass to bids.layout. default = struct()

Returns:

opt

Return type:

structure

Returns:

BIDS

Return type:

structure

loadAndCheckOptions(optionJsonFile)#

Loads the json file provided describing the options of an analysis. It then checks its content and fills any missing fields with the defaults.

If no argument is provided, it checks in the current directory for any opt_task-*.json files and loads the most recent one by name (using the date- key).

USAGE:

opt = loadAndCheckOptions(optionJsonFile)

Parameters:: optionJsonFile (char) – Fullpath to the json file describing the options of an analysis. It can also be an opt structure containing the options.
Returns:: opt, Options chosen for the analysis. See checkOptions().
Return type:: structure

onsetsMatToTsv(varargin)#

Takes an SPM _onset.mat file and converts it to a _onsets.mat file.

Onsets are assumed to be in seconds.

USAGE:

onsetTsvFile = onsetMatToTsv(onsetMatFile)

Parameters:

onsetMatFile (fullpath) – obligatory argument.

Returns:

onsetTsvFile:: (path)

overwriteDir(directory, opt)#

USAGE:

overwriteDir(directory, opt)

regressorsMatToTsv(varargin)#

Takes an SPM _desc-confounds_regressors.mat file and converts it to a _desc-confounds_regressors.tsv file.

USAGE:

regressorsTsvFile = regressorsMatToTsv(regressorsMatFile)

Parameters:

regressorsMatFile (fullpath) – obligatory argument.

Returns:

regressorsTsvFile:: (path)

renameSegmentParameter(BIDS, subLabel, opt)#

USAGE:

renameSegmentParameter(BIDS, subLabel, opt)

renameUnwarpParameter(BIDS, subLabel, opt)#

USAGE:

renameUnwarpParameter(BIDS, subLabel, opt)

saveAndRunWorkflow(matlabbatch, batchName, opt, subLabel)#

Saves the SPM matlabbatch and runs it

USAGE:

saveAndRunWorkflow(matlabbatch, batchName, opt, [subLabel])

Parameters:

matlabbatch (structure) – list of SPM batches
batchName (char) – name of the batch
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – subject label

Return type:

status

Return type:

output - files generated for each batch

saveOptions(opt)#

Saves options in a JSON file in a options folder.

USAGE:

saveOptions(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().

saveSpmScript(varargin)#

Saves a matlabbatch as .m file

USAGE:

outputFilename = saveSpmScript(input, outputFilename)

Parameters:

input – a matlabbatch variable (cell) or the fullpath to a .mat file containing such matlabbatch variable.
outputFilename (path) – optional. Path to output file

Returns:

outputFilename:: (path)

unzipAndReturnsFullpathName(fullpathName, opt)#

Unzips a file if necessary

USAGE:

unzippedFullpathName = unzipAndReturnsFullpathName(fullpathName)

Parameters:

fullpathName (char array)

Returns:

unzippedFullpathName:: (string)

QA#

anatQA(varargin)#

anatomical QA measures from the Preprocessed Connectome Project Quality Assurance Protocol (QAP) <http://preprocessed-connectomes-project.org/quality-assessment-protocol/>

USAGE:

[json, fig] = anatQA(anatImageFile, grayMatterFile, whiteMatterFile, ...
                     'noBackground', true, 'visible', 'on')

Parameters:

anatImageFile (valid file path)
grayMatterFile (valid file path) – gray matter probabilistic segmentation
whiteMatterFile (valid file path) – white matter probabilistic segmentation
noBackground (logical)
visible (char) – figure visibility. Any of: 'off', 'on'

OUTPUT

fig is a spm figure handle

json is a structure with the following fields:

SNRthe signal-to-Noise Ratio.
That is: the mean intensity within gray and white matter divided by the standard deviation of the values outside the brain. Higher values are better.
CNRthe Contrast to Noise Ratio.
That is: the mean of the white matter intensity values minus the mean of the gray matter intensity values divided by the standard deviation of the values outside the brain. Higher values are better.
FBER: Foreground to Background Energy Ratio,
That is: the variance of voxels in grey and white matter divided by the variance of voxels outside the brain. Higher values are better.
EFCEntropy Focus Criterion,
That is: the entropy of voxel intensities proportional to the maximum possible entropy for a similarly sized image. Indicates ghosting and head motion-induced blurring. Lower values are better. See <http://ieeexplore.ieee.org/document/650886/>

Note

When the background has 0 variance (e.g. a sequence with noise suppression like FLAIR) then the standard deviation of the white matter is used as reference instead of the background

GM and WM are thresholded by making them mutually exclusive. The background is found using data outside a large brain mask and trimming extreme values.

Adapted from Cyril Pernet’s spmup

censoring(data)#

routine that computes robust outliers for each column of the data in and return a matrix of censoring regressors (0s and a 1 per column)

USAGE:

censoringRegressors = censoring(data)

INPUT data is a n volumes * m matrix to censor column wise

OUTPUT censoring_regressors matrix with ones in each column for: outliers found in coumns of data

Adapted from Cyril Pernet’s spmup

compileScrubbingStats(statsFolder)#

Make a list of *_desc-confounds_timeseries.json and compile their results in a single tsv.

USAGE:

compileScrubbingStats(statsFolder)

computeDesignEfficiency(tsvFile, opt)#

Calculate efficiency for fMRI GLMs. Relies on Rik Henson’s fMRI_GLM_efficiency function.

For more information on design efficiency, see Jeanette Mumford excellent videos and the dedicated videos from the Principles of fMRI Part 2, Module 7-9.

Warning

This function should NOT be used for proper design efficiency optimization as there are better tools for this.

In general see the BrainPower doc but more specifically the tools below:

USAGE:

e = computeDesignEfficiency(tsvFile, opt)

Parameters:

tsvFile (char) – Path to a bids _events.tsv file.
opt (structure) – Options chosen for the analysis. See checkOptions().

Required:

opt.model.file: path to bids stats model file
opt.TR: inter-scan interval (s) - can be read from the _bold.json

Optional:

opt.t0: initial transient (s) to ignore (default = 1)
opt.Ns: number of scans

bids#

addStcToQuery(BIDS, opt, subLabel)#

USAGE:

opt = addStcToQuery(opt, subLabel)

In case slice timing correction was performed this update the query to fetch the correct files for realignment.

buildIndividualSpaceRoiFilename(deformationField, roiFilename)#

Creates a roi filename in individual space given a roi filename and a deformation field

USAGE:

roiBidsFile = buildIndividualSpaceRoiFilename(deformationField, roiFilename)

Parameters:

deformationField (path) – path to deformation field image.
roiFilename (path) – path to roi image.

Returns:

roiBidsFile:: (bids.File object)

checkFmriprep(BIDS)#

only fmriprep version >= 1.2 supported

USAGE:

status = checkFmriprep(BIDS)

Parameters:: BIDS (struct) – dataset layout. See: bids.layout, getData.

fileFilterForBold(opt, subLabel, type)#

USAGE:

[filter, opt] = fileFilterForBold(opt, subLabel, type)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)
type (char) – any of {‘glm’, ‘stc’, ‘confounds’, ‘events’}

generatedBy(BIDS)#

Get pipeline info

USAGE:

[name, version] = generatedBy(BIDS)

Parameters:: BIDS (struct) – dataset layout. See: bids.layout, getData.

getAnatFilename(varargin)#

Get the filename and the directory of some anat files for a given session and run. Unzips the files if necessary.

It several images are available it will take the first one it finds.

USAGE:

[anatImage, anatDataDir] = getAnatFilename(BIDS, subLabel, opt, nbImgToReturn, tolerant)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
subLabel (char)
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

anatImage

Return type:

string

Returns:

anatDataDir

Return type:

string

getAndCheckRepetitionTime(varargin)#

Gets the repetition time for a given bids.query filter (for several files) Throws an error if it returns empty or finds inconsistent repetition times.

USAGE:

repetitionTime = getAndCheckRepetitionTime(BIDS, filter)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
filter (structure) – obligatory argument.

Returns:

repetitionTime:: (float) (1x1)

Example:

filter = opt.query;
filter.sub =  subLabel;
filter.suffix = 'bold';
filter.extension = {'.nii', '.nii.gz'};
filter.prefix = '';
filter.task = opt.taskName;

TR = getAndCheckRepetitionTime(BIDS, filter);

getAndCheckSliceOrder(BIDS, opt, filter)#

Get the slice order information from the BIDS metadata. If inconsistent slice timing is found across files it throws an error.

USAGE:

sliceOrder = getAndCheckSliceOrder(opt)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

sliceOrder:

a vector of the time when each slice was acquired in in a volume or indicating the order of acquisition of the slices.

getAndCheckSliceOrder will try to read the opt structure for any relevant information about slice timing. If this is empty, it queries the BIDS dataset to see if there is any consistent slice timing information for a given filter.

bids_model#

checkContrast(model, node, iCon)#

Validates contrast specification

USAGE:

contrast = checkContrast(model, node, iCon)

createDefaultStatsModel(BIDS, opt, ignore)#

Creates a default model json file for a BIDS dataset

USAGE:

opt = createDefaultStatsModel(BIDS, opt)

Parameters:

BIDS (struct or path) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
ignore (cellstr) – Optional. Cell string that can contain: - "Transformations" - "Contrasts" - "Dataset" Can be used to avoid generating certain objects of the BIDS stats model.

Returns:

opt

Outputs a model file in the current directory:

fullfile(pwd, 'models', ['model-default' opt.taskName '_smdl.json']);

This model has 3 “Nodes” in that order

Run level
- will create a GLM with a design matrix that includes all all the possible type of trial_types that exist across all subjects and runs for the task specified in opt, as well as the realignment parameters.
- use DummyContrasts to generate contrasts for each trial_type for each run. This can be useful to run MVPA analysis on the beta images of each run.
Subject level
- will create a GLM with a design matrix that includes all all the possible type of trial_types that exist across all subjects and runs for the task specified in opt, as well as the realignment parameters.
- use DummyContrasts to generate contrasts for all each trial_type across runs
Dataset level
- use DummyContrasts to generate contrasts for each trial_type for at the group level.

EXAMPLE:

opt.taskName = 'myFascinatingTask';
opt.dir.raw = fullfile(pwd, 'data', 'raw');
opt = checkOptions(opt);

[BIDS, opt] = getData(opt, opt.dir.raw);

createDefaultStatsModel(BIDS, opt);

createModelFamilies(varargin)#

Create a family of models from a default one.

USAGE:

createModelFamilies(defaultModel, multiverse, outputDir)

Parameters:

defaultModel (BidsModel instance or path to a _smdl.json file) – bids stats model that serves as template.
multiverse (struct) –
Structure to describe the multiverse of models.

Each field of the structure is a dimension of the multiverse. Possible dimensions are:
- motion: motion regressors strategy
- scrub: scrubbing strategy
- wm_csf: white matter and cerebrospinal fluid regressors strategy
- non_steady_state: non steady state regressors strategy

EXAMPLE:

multiverse.motion = {'none', 'basic', 'full'};
multiverse.scrub = {false, true};
multiverse.wm_csf = {'none', 'basic', 'full'};
multiverse.non_steady_state = {false, true};

createModelFamilies(path_to_statsmodel_file, multiverse, output_path);

getContrastsFromParentNode(model, node)#

Recursively look for contrasts at previous levels

UISAGE:

contrastsList = getContrastsFromParentNode(model, node)

getContrastsList(model, node, participants)#

Get list of names of Contrast from this Node or gets its from the previous Nodes

USAGE:

contrastsList = getContrastsList(model, node)

Parameters:

node (char or structure) – node name or node content
model (BIDS stats model object)

Returns:

contrastsList (cellstr)

getContrastsListForFactorialDesign(opt, nodeName)#

assuming a GroupBy that contains at least “contrast”

we try to grab the contrasts list from the Edge.Filter otherwise we dig in this in Node or the previous one to find the list of contrasts

USAGE:

contrastsList = getContrastsListForFactorialDesign(opt, nodeName)

getDummyContrastFromParentNode(model, node)#

USAGGE:

dummyContrastsList = getDummyContrastFromParentNode(model, node)

Parameters:

node (struct)
model (BidsModel object)

getDummyContrastsList(model, node, participants)#

Get list of names of DummyContrast from this Node or gets its from the previous Nodes

USAGE:

dummyContrastsList = getDummyContrastsList(model, mode)

Parameters:

node (char or structure) – node name or node content
model (BIDS stats model object)

Returns:

dummyContrastsList (cellstr)

getInclusiveMask(opt, nodeName, BIDS, subLabel)#

Use the mask specified in the BIDS stats model as explicit mask.

If none is specified and we are in MNI space, then use the Intra Cerebral Volume SPM mask.

USAGE:

mask = getInclusiveMask(opt, nodeName, BIDS, subLabel)

bidspm#

data#

pycache#

cli#

baseInputParser()#

Returns an input parser with the common arguments for all bids apps calls.

Type bidspm help for more info.

cliBayesModel(varargin)#

Run stats on bids datasets.

Type bidspm help for more info.

cliCopy(varargin)#

Copy the content of the fmriprep directory to the output directory.

Type bidspm help for more info.

cliCreateRoi(varargin)#

Create a ROI from an atlas.

Type bidspm help for more info.

cliDefaultModel(varargin)#

Create a default bids stats model for a raw dataset.

Type bidspm help for more info.

cliPreprocess(varargin)#

Preprocess a bids dataset.

Type bidspm help for more info.

cliSmooth(varargin)#

Smooth an fmriprep dataset.

Type bidspm help for more info.

cliStats(varargin)#

Run stats on bids datasets.

Type bidspm help for more info.

getBidsFilterFile(args)#

getOptionsFromCliArgument(args)#

USAGE:

opt = getOptionsFromCliArgument(args)

inputParserForBayesModel()#

Returns an input parser for cliSBayesModel

Type bidspm help for more info.

inputParserForCopy()#

Returns an input parser for cliCopy.

Type bidspm help for more info.

inputParserForCreateModel()#

Returns an input parser for cliDefaultModel.

Type bidspm help for more info.

inputParserForCreateRoi()#

Returns an input parser for cliDefaultModel.

Type bidspm help for more info.

inputParserForPreprocess()#

Returns an input parser for cliPreprocess.

Type bidspm help for more info.

inputParserForSmooth()#

Returns an input parser for cliSmooth.

Type bidspm help for more info.

inputParserForStats()#

Returns an input parser for cliStats.

Type bidspm help for more info.

constants#

bidsAppsActions()#: Returns a cell array of the supported bids apps actions

lowLevelActions()#: Returns a cell array of the low level actions that can be performed

defaults#

ALI_my_defaults()#

Return default for the ALI toolbox.

USAGE:

defaults = ALI_my_defaults()

This is where we set the defaults we want to use for the ALI (lesion) toolbox. These will override the spm defaults. When “not enough” information is specified in the batch files, SPM falls back on the defaults to fill in the blanks. This allows to make the script simpler.

MACS_my_defaults()#

USAGE:

defaults = MACS_my_defaults()

Set defaults for the MACS toolbox

checkOptions(opt)#

Check the option inputs and add any missing field with some defaults

USAGE:

opt = checkOptions(opt)

Parameters:: opt (structure) – Options chosen for the analysis.
Returns:: opt
Return type:: structure

GENERIC OPTIONS

opt.dir - See setDirectories().
opt.groups = {''} - Group of subjects to analyze
opt.subjects = {[]} - Suject to run in each group.
opt.space = {'individual', 'IXI549Space'} - Space where we conduct the analysis
opt.taskName
opt.query = struct('modality', {{'anat', 'func'}}) - a structure used to specify subset of files to only run analysis on. See bids.query() to see how to specify.

Warning

opt.query might be progressively deprecated in favor of opt.bidsFilterFile that allows using different filters for T1w and bold data.

opt.bidsFilterFile - Sets how to define a typical images “bold”, “T1w”… in terms of their bids entities. The default value is:

struct('fmap', struct('modality', 'fmap'), ...
       'bold', struct('modality', 'func', 'suffix', 'bold'), ...
       't2w',  struct('modality', 'anat', 'suffix', 'T2w'), ...
       't1w',  struct('modality', 'anat', 'space', '', 'suffix', 'T1w'), ...
       'roi',  struct('modality', 'roi', 'suffix', 'mask'), ...
       'xfm',  struct('modality', 'anat', 'suffix', 'xfm', 'to', 'T1w'));

opt.verbosity = 1 - Set it to 0 if you want to see less output on the prompt.
opt.tolerant = true - Set it to false if you want turn warning into errors.
opt.dryRun = false - Set it to true in case you don’t want to run the analysis.
opt.pipeline.type = 'preproc' - Switch it to stats when running GLMs.
opt.pipeline.name
opt.pipeline.isBms whether this is a bayesion model selection pipeline
opt.boilerplateOnly = false - If set to true only creates dataset description reports and methods description. Overwrites previous versions.
opt.zeropad = 2 - Number of zeros used for padding subject numbers, in case subjects should be fetched by their index 1 and not their label O1'.
opt.rename.do = true - Set to false to skip renaming files with bidsRename(). Mostly for debugging as the output files won’t be usable by any of the stats workflows.
opt.rename.overwrite = true - To overwrite any eventual previous output of bidsRename().
opt.msg.color = blue - Default font color of the prompt messages.

PREPROCESSING OPTIONS

opt.realign.useUnwarp = true
opt.useFieldmaps = true - When set to true the preprocessing pipeline will look for the voxel displacement maps (created by bidsCreateVDM()) and will use them for realign and unwarp.
opt.fwhm.func = 6 - FWHM to apply to the preprocessed functional images.
opt.anatOnly = false - Set to true to only preprocess the anatomical file.
opt.segment.force = false - Set to true to ignore previous output of the segmentation and force to run it again
opt.skullstrip.mean = false - Set to true to skulstrip mean functional image
opt.skullstrip.threshold = 0.75 - Threshold used for the skull stripping. Any voxel with p(grayMatter) + p(whiteMatter) + p(CSF) > threshold will be included in the mask.
opt.skullstrip.do = true - Set to true to skip skullstripping.
opt.stc.skip = false - Boolean flag to skip slice time correction or not.
opt.stc.referenceSlice = [] - Reference slice (in seconds) for the slice timing correction. If left empty the mid-volume acquisition time point will be selected at run time.
opt.funcVoxelDims = [] - Voxel dimensions to use for resampling of functional data at normalization.

STATISTICS OPTIONS

opt.model.file = '' - Path to the BIDS model file that contains the model to specify and the contrasts to compute. A path to a dir can be passed as well. In this case all *_smdl.json files will be used and looped over. This can useful to specify several models at once Before running Bayesion model selection on them.
opt.fwhm.contrast = 0 - FWHM to apply to the contrast images before bringing them at the group level.
opt.model.designOnly = false - If set to true, the GLM will be specified without associating any data to it. Can be useful for quick design matrix inspection before running estimation.
opt.glm.roibased.do = false - Set to true to use the bidsRoiBasedGLM workflow.
opt.glm.useDummyRegressor = false - Set to true to add dummy regressors when a condition is missing from a run. See bidsModelSelection() for more information.
opt.glm.maxNbVols = Inf - Sets the maximum number of volumes to include in a run in a subject level GLM. This can be useful if some time series have more volumes than necessary.
opt.glm.keepResiduals = false - Keep the subject level GLM residuals if set to true.
opt.glm.concatenateRuns = false - Concatenate “vertically” the images and and onsets of several run when set to true. Necessary to run a psycho-physiologial interaction analysis.
opt.QA.glm.do = false - If set to true the residual images of a GLM at the subject levels will be used to estimate if there is any remaining structure in the GLM residuals (the power spectra are not flat) that could indicate the subject level results are likely confounded. See plot_power_spectra_of_GLM_residuals.m and Accurate autocorrelation modeling substantially improves fMRI reliability for more info.

defaultContrastsStructure()#

defaultResultsStructure()#

getOptionsFromModel(opt)#

USAGE:

opt = getOptionsFromModel(opt)

mniToIxi(varargin)#

Convert mention of MNI space to the SPM default space IXI549Space

USAGE:

optOut = mniToIxi(opt)

Parameters:: foo (structure) – options
Returns:: optOut
Return type:: structure

setDirectories(opt)#

USAGE:

opt = setDirectories(opt)

setRenamingConfig(opt, workflowName)#

set default map for renaming for a specific workflow

USAGE:

opt = setRenamingConfig(opt, workflowName)

set_spm_2_bids_defaults(opt)#

set default map for renaming for bidspm

USAGE:

opt = set_spm_2_bids_defaults(opt)

Further renaming mapping can then be added, changed or removed through the opt.spm_2_bids object.

spm_my_defaults()#

USAGE:

spm_my_defaults()

This is where we set the defaults we want to use. These will override the spm defaults. When “not enough” information is specified in the batch files, SPM falls back on the defaults to fill in the blanks. This allows to make the scripts simpler.

validateResultsStructure(result)#

make sure there is no extra field in the result structure of a bids stats model or in the

USAGE:

validateResultsStructure(result)

infra#

checkDependencies(opt)#

Checks that that the right dependencies are installeda and loads the spm defaults.

USAGE:

checkDependencies()

checkToolbox(varargin)#

Checks that a given SPM toolbox is installed. Possible to install it if necessary.

USAGE:

status = checkToolbox(toolboxName, 'verbose', false, 'install', false)

Parameters:

toolboxName (char) – obligatory argument. Any of {‘ALI’, ‘MACS’, ‘mp2rage’}.
verbose (logical) – parameter
install (logical) – parameter

EXAMPLE:

checkToolbox('MACS', 'verbose', true, 'install', true)

elapsedTime(opt, action, startTime, runTime, nbIteration)#

USAGE:

[start, runTime] = elapsedTime(input, startTime, runTime, nbIteration)

getEnvInfo(opt)#

Gets information about the environment and operating system to help generate data descriptors for the derivatives.

USAGE:

[OS, generatedBy] = getEnvInfo()

Returns:: OS: (structure) (dimension) :generatedBy: (structure) (dimension)

getRepoInfo(rootDir)#

Return the branch and commit shasum

USAGE:

[branch, commit] = getRepoInfo()

getVersion()#

Reads the version number of the pipeline from the txt file in the root of the repository.

USAGE:

versionNumber = getVersion()

Returns:: versionNumber: (string) Use semantic versioning format (like v0.1.0)

resizeAliMask(opt)#

USAGE:

aliMask = resizeAliMask(opt)

returnBsmDocURL(section)#

USAGE:

url = returnBsmDocURL()

returnHomeDir()#

Return the fullpath of the home directory of the user.

USAGE:

home = returnHomeDir()

returnRepoURL()#

USAGE:

repoURL = returnRepoURL()

returnRootDir()#

USAGE:

rootDir = returnRootDir()

returnRtdURL(page, anchor)#

USAGE:

rtdURL = returnRtdURL()

setGraphicWindow(opt)#

Open SPM graphic window.

USAGE:

[interactiveWindow, graphWindow, cmdLine] = setGraphicWindow(opt)

Parameters:: opt (structure) – Options chosen for the analysis. See checkOptions().
Returns:: interactiveWindow, graphWindow, cmdLine

silenceOctaveWarning()#

USAGE:

silenceOctaveWarning()

messages#

bidspmHelp()#

General intro function for bidspm

Note

all parameters use snake_case
most “invalid” calls simply initialize bidspm

BIDS APP CALLS

generic call:

bidspm(bids_dir, output_dir, analysis_level, ...
       'action', 'some_action', ...
       'participant_label', {}, ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'verbosity', 2, ...
       'options', struct([]))

Obligatory parameters

Parameters:

bids_dir (path) – path to a raw BIDS dataset
output_dir (path) – path where to output data
analysis_level (string) – Can either be 'subject' or 'dataset'. Defaults to 'subject'
action (char) –
defines the pipeline to run; can be any of:
- 'copy': copies fmriprep data for smoothing
- 'preprocess': preprocesses data
- 'smooth': smooths data
- 'default_model': creates a default BIDS stats model
- 'create_roi': creates ROIs from a given atlas
- 'stats': runs model specification / estimation, contrast computation, display results
- 'contrasts': runs contrast computation, display results
- 'results': displays results
- 'bms': performs bayesian model selection
- 'specify_only' only specifies the models
participant_label (cellstr) – cell of participants labels. For example: {'01', '03', '08'}. Can be a regular expression. Defaults to {}
bids_filter_file (path) – path to JSON file or structure
verbosity (positive integer) – can be any value between 0 and 3. Defaults to 2
options (path to JSON file or structure) – See the checkOptions help to see the available options.

Note

Arguments passed to bidspm have priorities over the options defined in opt. For example passing the argument 'dry_run', true will override the option opt.dryRun = false.

PREPROCESSING

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'preprocess', ...
       'participant_label', {}, ...
       'task', '', ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'verbosity', 2, ...
       'options', struct([]), ...
       'boilerplate_only', false, ...
       'dry_run', false, ...
       'dummy_scans', 0, ...
       'anat_only', false, ...
       'ignore', {}, ...
       'fwhm', 6, ...
       'skip_validation', false)

Parameters:

boilerplate_only (logical) – Only creates dataset description reports. and methods description. Defaults to false.
space (cell string) – Defaults to {}
task (char) – Only a single task can be processed at once. Defaults to ''.
dry_run (logical) – Defaults to false
dummy_scans (positive scalar) – Number of dummy scans to remove. Defaults to 0.
anat_only (logical) – Only preprocesses anatomical data. Defaults to false.
ignore (cellstr) – can be any of {'fieldmaps', 'slicetiming', 'unwarp', 'qa'}
fwhm (positive scalar) – Smoothing to apply to the preprocessed data. Defaults to 6.
skip_validation (logical) – To skip bids dataset or bids stats model validation. Defaults to false.

COPY

Copies and unzips input data to output dir. For example for fmriprep data before smoothing.

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'copy', ...
       'participant_label', {}, ...
       'task', {}, ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'verbosity', 2, ...
       'options', struct([]), ...
       'anat_only', false, ...
       'force', false)

Parameters:

space (cell string) – Defaults to {}
task (char or cell string) – Defaults to {}
force (logical) – Overwrites previous data if true. Defaults to false.
anat_only (logical) – Only copies anatomical data. Defaults to false.

CREATE_ROI

Creates ROIs from a given atlas.

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'create_roi', ...
       'participant_label', {}, ...
       'space', {'MNI'}, ...
       'bids_filter_file', struct([]), ...
       'preproc_dir', preproc_dir, ...
       'verbosity', 2, ...
       'options', struct([]), ...
       'roi_atlas', 'wang', ...
       'roi_name', {'V1v', 'V1d'}, ...
       'hemisphere', {'L', 'R'})

Parameters:

space (cell string) – Defaults to {}
roi_atlas (char) –
Can be any of:
- 'visfatlas'
- 'anatomy_toobox'
- 'neuromorphometrics'
- 'hcpex'
- 'wang'
- 'glasser'
Defaults to 'neuromorphometrics'
roi_name (cell string) – Name of the roi to create. If the ROI does not exist in the atlas, the list of available ROI will be returned in the error message.
hemisphere (cell string containing any of 'L', 'R') – Hemisphere of the ROI to create. Not all ROIs have both hemispheres. Defaults to {'L', 'R'}.
preproc_dir (path) – path to preprocessed data Necessary when using 'T1w' or 'individual' space to access deformation fields to inverse normalize ROIs.

SMOOTH:

Copies files to output dir and smooths them.

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'smooth', ...
       'participant_label', {}, ...
       'task', {}, ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'options', struct([]), ...
       'verbosity', 2, ...
       'fwhm', 6, ...
       'dry_run', false)

Parameters:

space (cell string) – Defaults to {}
task (char or cell string) – Defaults to {}
fwhm (positive scalar) – Smoothing to apply to the preprocessed data. Defaults to 6.
dry_run (logical) – Defaults to false.
anat_only (logical) – Only smooths the anatomical data. Defaults to false.

CREATE DEFAULT_MODEL

Creates a default BIDS stats model for a given raw BIDS dataset.

bidspm(bids_dir, output_dir, 'dataset', ...
       'action', 'default_model', ...
       'participant_label', {}, ...
       'task', {}, ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'verbosity', 2, ...
       'options', struct([]), ...
       'options', struct([]), ...
       'ignore', {}, ...
       'skip_validation', false)

Parameters:

space (cell string) – Defaults to {}
task (char or cell string) – Defaults to {}
ignore (cell string) – can be any of {'contrasts', 'transformations', 'dataset'}
skip_validation (logical) – To skip bids dataset or bids stats model validation. Defaults to false.

STATS

Note

'stats' runs model specification / estimation, contrast computation, display results
'contrasts' runs contrast computation, display results
'results' displays results
'specify_only' only specifies the models

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'stats', ...
       'participant_label', {}, ...
       'task', {}, ...
       'space', {'individual', 'IXI549Space'}, ...
       'bids_filter_file', struct([]), ...
       'options', struct([]), ...,
       'verbosity', 2, ...
       'preproc_dir', preproc_dir, ...
       'model_file', model_file, ...          % specific to stats
       'fwhm', 6, ...
       'dry_run', false, ...
       'boilerplate_only', false, ...
       'roi_atlas', 'neuromorphometrics', ...
       'roi_based', false, ...
       'roi_dir', '', ...
       'roi_name', {''}, ...
       'design_only', false, ...
       'ignore', {}, ...
       'concatenate', false, ...
       'use_dummy_regressor', false)
       'skip_validation', false)

Obligatory parameters

Parameters:

preproc_dir (path) – path to preprocessed data
model_file (path to JSON file or dir or structure) – Path to the BIDS model file that contains the model to specify and the contrasts to compute. A path to a dir can be passed as well. In this case all *_smdl.json files will be used and looped over. This can useful to specify several models at once Before running Bayesion model selection on them.
space (cell string) – Defaults to {}

Optional parameters

Parameters:

fwhm (positive scalar) – smoothing level of the preprocessed data
design_only (logical) – to only run the model specification
ignore (cell string) – can be any of {'qa'}, to skip quality controls into a single 4D image.
concatenate (logical) – will concatenate the beta images of the conditions of interest convolved by an HRF.
dry_run (logical) – Defaults to false.
roi_atlas (char) – Name of the atlas to use to label activations in MNI space.
roi_based (logical) – Set to true to run a ROI-based analysis. Defaults to false.
roi_dir (path) – Path to the directory containing the ROIs.
roi_name (cell string) – Names or regex expression of the ROI to use.
boilerplate_only (logical) – Only creates dataset description reports. and methods description. Defaults to false.
use_dummy_regressor (logical) – If true any missing condition will be modelled by a dummy regressor of NaN. Defaults to false.
skip_validation (logical) – To skip bids dataset or bids stats model validation. Defaults to false.
node_name (char) – Model node to run.

BAYESIAN MODE SELECTION

bidspm(bids_dir, output_dir, 'subject', ...
       'action', 'bms', ...
       'participant_label', {}, ...
       'options', struct([]), ...,
       'verbosity', 2, ...
       'models_dir', models_dir, ...
       'fwhm', 6, ...
       'dry_run', false, ...
       'skip_validation', false)

Parameters:

action (char) – Any of: {'bms', 'bms-posterior', 'bms-bms'} ‘bms’ will performm all steps for the baeysian model selection. If ‘bms’ has been performed then 'bms-posterior' can``’bms-bms’`` be performed one after the other. See the help section of bidsModelSelection() for more details.
models_dir – A path to a dir can be passed as well. In this case all *_smdl.json files will be used and looped over.
dry_run (logical) – Defaults to false.
fwhm (positive scalar) – smoothing level of the preprocessed data
skip_validation (logical) – To skip bids dataset or bids stats model validation. Defaults to false.

Note

For the bayesian model selection to function you must first specify all your models using the 'specify_only' action with the options 'use_dummy_regressor', true.

opt.glm.useDummyRegressor = true;

bidspm(bids_dir, output_dir, 'subject', ...
      'participant_label', participant_label, ...
      'preproc_dir', preproc_dir, ...
      'action', 'specify_only', ...
      'model_file', models_dir, ...
      'use_dummy_regressor', true
      'fwhm', FWHM);

low level calls

USAGE:

% initialise (add relevant folders to path)
bidspm

% equivalent to
bidspm init
bidspm('action', 'init')

% help
bidspm help
bidspm('action', 'help')

% uninitialise (remove relevant folders from path)
bidspm uninit
bidspm('action', 'uninit')

% also adds folder for testing to the path
bidspm dev
bidspm('action', 'dev')

% tried to update the current branch from the upstream repository
bidspm update
bidspm('action', 'update')

% misc
bidspm version
bidspm('action', 'version')

bidspm run_tests
bidspm('action', 'run_tests')

For a more readable version of this help section, see the online <a href=”https://bidspm.readthedocs.io/en/latest/usage_notes.html”>documentation</a>.

bugReport(opt, ME)#

Write a small bug report.

USAGE:

bugReport(opt)

deprecated(varargin)#

Throws a deprecation warning

USAGE:

deprecated(functionName)

Parameters:: functionName (path) – obligatory argument.

errorHandling(varargin)#

USAGE:

errorHandling(functionName, id, msg, tolerant, verbose)

Parameters:

functionName (char)
id (char) – Error or warning id
msg (char) – Message to print
tolerant (logical) – If set to true errors are converted into warnings
verbose (logical) – If set to 0 or false this will silence any warning

EXAMPLE:

msg = sprintf('this error happened with this file %s', filename)
id = 'thisError';
errorHandling(mfilename(), id, msg, true, opt.verbosity)

adapted from bids-matlab

logger(varargin)#

Returns logger message

USAGE:

logger(logLevel, msg, 'options', opt, 'filename', filename, 'id', id)

Parameters:

logLevel (char) – Any of {'ERROR', 'WARNING', 'INFO', 'DEBUG'}
msg (char)

noRoiFound(varargin)#

USAGE:

status = noRoiFound(opt, roiList, folder)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
roiList (cell) – obligatory argument.
folder (path) – optional argument. default: ''

Returns:

status

Return type:

logical

notImplemented(varargin)#

Throws a not implemented warning

USAGE:

notImplemented(functionName, msg, opt)

Parameters:

functionName (path) – obligatory argument.
msg (char) – optional
opt (struct)

Returns:

status

Return type:

logical

EXAMPLE:

notImplemented(mfilename(), ...
               'Meaning of life the universe and everything not impemented', ...
               opt);

printAvailableContrasts(varargin)#

USAGE:

printAvailableContrasts(SPM, opt)

Parameters:

SPM (structure or path) – fullpath to SPM.mat file or content of SPM.mat file
opt (structure) – Options chosen.

printBatchName(batchName, opt)#

printCredits(opt)#

printProcessingSubject(iSub, subLabel, opt)#

USAGE:

printProcessingSubject(iSub, subLabel, opt)

printToScreen(varargin)#

USAGE:

printToScreen(msg, opt, 'format', 'blue')

printWorkflowName(workflowName, opt)#

timeStamp()#

Returns the current time in a BIDS (ish) valid format: ‘yyyy-mm-ddTHH-MM’

USAGE:

output = timeStamp()

preproc#

fieldmaps#

getBlipDirection(metadata)#

Gets the total read out time of a sequence.

USAGE:

blipDir = getBlipDirection(metadata)

Parameters:: metadata (structure) – image metadata
Returns:: blipDir

Used to create the voxel dsiplacement map (VDM) from the fieldmap

getMetadataFromIntendedForFunc(BIDS, fmapMetadata)#

Gets metadata of the associated bold file: - finds the bold file a fmap is intended for, - parse its filename, - get its metadata.

USAGE:

[totalReadoutTime, blipDir] = getMetadataFromIntendedForFunc(BIDS, fmapMetadata)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
fmapMetadata (structure)

Returns:

totalReadoutTime: (type) (dimension) :blipDir: (type) (dimension)

At the moment the VDM is created based on the characteristics of the last func file in the IntendedFor field

getTotalReadoutTime(metadata)#

Gets the total read out time of a sequence. Used to create the voxel dsiplacement map (VDM) from the fieldmap

USAGE:

totalReadoutTime = getTotalReadoutTime(metadata)

Parameters:

metadata (structure) – image metadata

Returns:

totalReadoutTime:: (float) in millisecond

Currently this relies on the user adding extra metadata in the json of the functional files as the metadata queried are not “official” BIDS metadata but can usually be found in the DICOM headers (for example: PixelBandwidth)

getVdmFile(BIDS, opt, boldFilename)#

returns the voxel displacement map associated with a given bold file

USAGE:

vdmFile = getVdmFile(BIDS, opt, boldFilename)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
boldFilename (path)

Returns:

vdmFile:: (string)

utils#

collectSrcMetadata(srcMetadata, metadata)#

createPialSurface(varargin)#

creates a gifti image of the the pial surface

EXAMPLE:

surfaceFile = createPialSurface(grayMatterFile, whiteMatterFile, opt)

Parameters:

grayMatterFile (valid file path) – gray matter probabilistic segmentation
whiteMatterFile (valid file path) – white matter probabilistic segmentation
opt (structure)

getAcquisitionTime(sliceOrder, repetitionTime)#

USAGE:

acquisitionTime = getAcquisitionTime(sliceOrder)

Parameters:: metadata (vector) – sliceOrder
Returns:: acquisitionTime

removeDummies(varargin)#

Remove dummy scans from a time series and update file metadata.

USAGE:

removeDummies(inputFile, dummyScans, metadata, 'force', false, 'verbose', true)

Parameters:

inputFile (structure)
dummyScans (positive integer) – number of dummy scans to remove
metadata (structure)
force (logical)
verbose (logical)

segmentationAlreadyDone(anatFile, BIDS)#

USAGE:

status = checkForPreviousSegmentOutput(anatFile, BIDS, opt)

Parameters:: anatFile (path)
Returns:: returns true

to skip segmentation if done previously

skullstrippingAlreadyDone(anatFile, BIDS)#

USAGE:

status = skullstripAlreadyDone(anatFile, BIDS, opt)

Parameters:: anatFile (path)
Returns:: returns true

to skip skullstripping if done previously

transferMetadataFromJson(createdFiles, extraMetadata)#

Add repetition time and slice timing metadata to prepocessed or smoothed files metadata by reading them from the Sources files mentioned in the sidecar JSON.

USAGE:

Parameters:

createdFiles (cellstr) – Files renamed by spm_2_bids
extraMetadata (struct) – Extra metadata to add.

reports#

boilerplate(varargin)#

USAGE:

outputFile = boilerplate(opt, ...
                        'outputPath', outputPath, ...
                        'pipelineType', pipelineType, ...
                        'partialsPath', partialsPath, ...
                        'verbosity', 2)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
outputPath (char)
pipelineType (char) – 'preprocess', 'stats', 'create_roi'
partialsPath (path)
verbose (logical)

EXAMPLE:

opt.model.file = path_to_model;
opt.designType = 'event';
opt = checkOptions(opt);

outputFile = boilerplate(opt, ...
                          'outputPath', pwd, ...
                          'pipelineType', 'stats', ...
                          'verbosity', 2)

copyFigures(BIDS, opt, subLabel)#

Copy the figures from spatial preprocessing into a separate folder.

USAGE:

copyFigures(BIDS, opt, subLabel)

Parameters:

BIDS (structure) – dataset layout. See: bids.layout, getData.
opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – Subject label (for example ‘01’).

copyGraphWindownOutput(opt, subLabel, action, imgNb)#

Looks into the current directory for an spm_.*imgNb.png file and moves it into the output directory sub-label/figures.

The output name of the file is

yyyymmddHHMM_sub-label_task-label_action.png

USAGE:

imgNb = copyGraphWindownOutput(opt, subLabel, [action = '',] [imgNb = 1])

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char) – Subject label (for example ‘01’).
action (char) – Name to be given to the figure.
imgNb (vector of integer) – Image numbers to look for. SPM increments them automatically when adding a new figure a folder.

Returns:

imgNb: (integer) number of the next image to get.

partials#

stats#

results#

convertPvalueToString(p)#: convert p value to char

renameNidm(opt, result, subLabel)#

Rename the nidm files to a bids friendly filename.

USAGE:

renameNidm(opt, result, subLabel)

renameOutputResults(opt, result, subLabel)#

we create new name for the nifti output by removing the spmT_XXXX prefix and using the XXXX as label- for the file

also rename PNG and labels activations

renamePngCsvResults(opt, result, ext, subLabel)#

Rename the results png and csv files to a bids friendly filename.

USAGE:

renamePngCsvResults(opt, result, ext, subLabel)

renameSpmT(result)#

Rename the results spmT (theresholed or binarized) outputted in GLM.

USAGE:

renameSpmT(result)

returnName(contrast)#: To help naming of files generated when computing results of a given contrast

returnResultNameSpec(opt, result)#: Return a bids.File name specification for a result file

setMontage(result)#

USAGE:

montage = setMontage(result)

setNidm(export, result)#

Handles the NIDM results aspect of the result batches

USAGE:

export = setNidm(export, result)

subject_level#

allRunsHaveSameNbRegressors(spmMat)#

USAGE:

allRunsHaveSameNbRegressors(spmMatFile)

appendContrast(contrasts, C, counter, type)#

USAGE:

[contrasts, counter] = appendContrast(contrasts, C, counter, type)

Parameters:

contrasts (struct)
C (struct)
counter (integer)
type (char?)

See also: specifyContrasts()

checkRegressorName(SPM)#

extra checks for bidsModelSelection to make sure that:

all sessions can be vertically concatenated
after concatenation all regressors have the same name (or that there are dummy regressors)

USAGE:

checkRegressorName(SPM)

See also: specifyContrasts()

orderAndPadCounfoundMatFile(varargin)#

When doing model comparison all runs must have same number of confound regressors and have exactly the same names (be from the same conditions), so

so we pad them with zeros if necessary

we reorder them

USAGE:

status = padCounfoundMatFile(spmSess, opt)

Parameters:

spmSess (cell) – obligatory argument.
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

status

Return type:

logical

See also: specifyContrasts()

specifySessionLvlContrasts(model, node, contrasts, counter)#

USAGE:

[contrasts, counter] = specifySessionLvlContrasts(model, node, contrasts, counter)

Parameters:

contrasts (struct)
node
counter (integer)
model (BidsModel object)

See also: specifyContrasts()

specifySubLvlContrasts(model, node, contrasts, count)#

USAGE:

[contrasts, counter] = specifySubLvlContrasts(model, node, contrasts, counter)

Parameters:

model (BidsModel instance)
contrasts (struct)
node (struct)
counter (integer)

See also: specifyContrasts()

group_level#

computeCumulativeFwhm(opt)#

Compute resulting fwhm when smoothing both time series and contrasts.

USAGE:

fwhm = computeCumulativeFwhm(opt)

findSubjectConImage(varargin)#

Returns the fullpath of a con image(s) for a given subject label and contrast name(s).

USAGE:

file = findSubjectConImage(opt, subLabel, contrastName)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
subLabel (char)
contrastName (char or cellstr)

Returns:

file : a fullpath or a cellstrng of fullpath

getRFXdir(varargin)#

Sets the name the group level analysis directory and creates it if it does not exist

USAGE:

rfxDir = getRFXdir(opt, nodeName, contrastName, thisGroup)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
nodeName (char)
contrastName (char)
thisGroup (cellstr)

Returns:

rfxDir: (string) Fullpath of the group level directory

Typical output:

opt.dir.derivatives/bidspm-stats/derivatives/bidspm-groupStats/bidspm-stats

['sub-ALL-task-',     model.Input.task, ...
 '_space-'    model.Input.space, ...
 '_FWHM-',    num2str(opt.fwhm.func), ...
 '_conFWHM-', opt.fwhm.contrast, ...
 'node-', model.Input.Nodes(dataset_level).Name, ...             % optional
 'contrast-', model.Input.Nodes(dataset_level).Contrast(i).Name  % if ~= from "dataset_level"
 ]

utils#

checkSpmMat(dir, opt, strict)#

createGlmDirName(opt)#

USAGE:

glmDirName = createGlmDirName(opt)

designMatrixFigureName(varargin)#

USAGE:

filename = designMatrixFigureName(opt, desc, subLabel)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
desc (char) – optional argument. default: ''
subLabel (char) – optional argument. default: ''

Returns:

filename:: (string)

endsWithRunNumber(contrastName)#

USAGE:

endsWithRunNumber(contrastName)

Returns true if the contrast name ends with an underscore followed by some number.

fillInResultStructure(thisResult)#

Fill a structure use to display results with defaults

USAGE:

thisResult = fillInResultStructure(thisResult)

Parameters:: thisResult (struct)

getContrastNb(result, opt, SPM)#

Identify the contrast nb actually has the name the user asked

The search is regex based and any string (like ‘foo’) will be by default regexified (into ‘^foo$’).

USAGE:

contrastNb = getContrastNb(result, opt, SPM)

Parameters:

SPM (structure or path) – content of SPM.mat file
result (struct) – structure with at least a name field with a chat with the name of the contrast of interest
opt (structure) – Options chosen.

getRegressorIdx(cdtName, SPM, bidsSes)#

Gets from the SPM structure the regressors index corresponding to the a condition convolved with the canonical HRF. This can also look for non convolved conditions to identify a confound regressor.

Throws a warning if there is no regressor for that condition.

USAGE:

[cdtName, regIdx, status] = getRegressorIdx(cdtName, SPM)

Parameters:

cdtName (char or cellstr) – name of the condition to look for
SPM (structure) – content of SPM.mat
bidsSes (char) – bids session label

Returns:

cdtName:

(char) name of the condition stripped of any eventual 'trial_type.' prefix
regIdx:

(logical) vector of the columns of the design matrix containing the regressor of interest
status:

(logical) is false if no regressor was found for that condition

labelActivations(varargin)#

Add MNI labels to a csv output file from SPM and saves it as TSV.

Can choose which atlas to use.

USAGE:

tsvFile = labelActivations(csvFile, 'atlas', 'Neuromorphometrics')

Parameters:

csvFile (path)
atlas (char) –
Any of
- ’Neuromorphometrics’`
- ’aal’`
- ’hcpex’`
- ’wang’`
- ’glasser’`
- ’visfatlas’`
Defaults to 'neuromorphometrics'

Returns:

tsvFile:: (path)

labelSpmSessWithBidsSesAndRun(SPM)#

Adds the bids session and run label to each SPM.Sess.

USAGE:

:param SPM: content of SPM.mat
:type  SPM: structure

removeIntercept(designMatrix)#: remove intercept because SPM includes it anyway

returnContrastImageFile(varargin)#

Return the contrast image file for the contrast name the user asked

The search is regex based and any string (like ‘foo’) will be by default regexified (into ‘^foo$’).

USAGE:

conImageFile = returnContrastImageFile(SPM, name, opt)

Parameters:

SPM (structure or path) – fullpath to SPM.mat file or content of SPM.mat file
name (char) – name of the contrast of interest
opt (structure) – Options chosen.

returnNumberScrubbedTimePoints(confounds)#: Return number of regressors that have one and only 1 in the whole column.

validateContrasts(contrasts)#

USAGE:

validateContrasts(contrasts)

Parameters:: contrasts (struct) – structure with at least fields “name”, “C”

utils#

checkMaskOrUnderlay(image, opt, type)#

USAGE:

image = checkMaskOrUnderlay(image, opt, type)

Parameters:

image (path)
type (char) – any of {'underlay', 'background', 'mask'}

cleanUpWorkflow(opt)#

USAGE:

cleanUpWorkflow(opt)

computeMeanValueInMask(image, mask)#

USAGE:

value = computeMeanValueInMask(image, mask)

image: image filename mask: mask filename

computeTsnr(boldImage)#

calculate temporal SNR from single run of fMRI timeseries data

USAGE:

[tsnrImage, volTsnr] = computeTsnr(boldImage)

Parameters:: boldImage (path) – path to the 4D nifti image. The file must have a BIDS like name (example: key1_label1_key2-label2_suffic.nii)

Output:

tsnrImage: fullpath filename of the tSNR output image
volTsnr: 3D volume of the tSNR image

Adapted from fmrwhy: jsheunis/fMRwhy

createDataDictionary(tsvContent)#

USAGE:

jsonContent = createDataDictionary(tsvContent)

deregexify(string)#

Removes eventual initial ^ and ending $

Input –> Output

^foo$ –> foo

USAGE:

string = deregexify(string)

displayArguments(varargin)#

getDist2surf(varargin)#

Loads the pial surface and computes the mean distance to the surface. Will return a default value of 50 mm if this fails.

USAGE:

davg = getDist2surf(anatImage, opt)

Parameters:

anatImage (cell)
opt (structure) – Options chosen for the analysis. See checkOptions().

Returns:

davg:: (float) (1 x 1)

Adapted from motion finger print functions and script (mw_mfp.m) from Marko Wilke https://www.medizin.uni-tuebingen.de/kinder/en/research/neuroimaging/software/ see http://www.dx.doi.org/10.1016/j.neuroimage.2011.10.043 and http://www.dx.doi.org/10.1371/journal.pone.0106498

getFuncVoxelDims(opt, subFuncDataDir, fileName)#

Get the resolution of an image and update the relevant field in the options.

USAGE:

[voxDim, opt] = getFuncVoxelDims(opt, subFuncDataDir, fileName)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
subFuncDataDir
fileName

Returns:

voxDim, opt

regexify(string)#

Turns a string into a simple regex. Useful to query bids dataset with bids.query that by default expects will treat its inputs as regex.

Input –> Output

foo –> ^foo$

USAGE:

string = regexify(string)

renamePng(directory, prefix)#

Removes the _XXX suffix before the PNG extension in files generated by SPM in a directory

Will overwrite any file that already exists

USAGE:

renamePng(directory)

returnBatchFileName(batchType, ext)#

USAGE:

batchFileName = returnBatchFileName([batchType] [, ext])

Parameters:

batchType (cell)
ext (structure) – optional.

Returns:

batchFileName:: (path)

returnDependency(opt, type)#

Use to create dependencies between batches in workflows.

USAGE:

dep = returnDependency(opt, type)

returnVolumeList(varargin)#

USAGE:

volumes = returnVolumeList(opt, boldFile)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
boldFile (fullpath)

Returns:

volumes:: (cell string)

setFields(structure, fieldsToSet, overwrite)#

Recursively loop through the fields of a target structure and sets the values as defined in the structure fieldsToSet if they don’t exist.

Content of the target structure can be overwritten by setting the overwrite```to ``true.

USAGE:

structure = setFields(structure, fieldsToSet, overwrite = false)

Parameters:

structure
fieldsToSet (char)
overwrite (logical)

Returns:

structure

setUpWorkflow(varargin)#

Calls some common functions to:

check the configuration,

remove some old files from an eventual previous crash

loads the layout of the BIDS dataset

tries to open a graphic window

USAGE:

[BIDS, opt] = setUpWorkflow(opt, workflowName, bidsDir, indexData, index_dependencies)

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions().
workflowName (char) – name that will be printed on screen
bidsDir – optional
bidsDir – fullpath, default = ‘’
indexData – Set to false if you want to skip the datindexing with getData. Can be useful for some group level workflow where indexing will happen later at the batch level. This will also skip updating the subject list done by getData. Default to true.
indexData – logical, default = true
index_dependencies (logical) – Use 'index_dependencies', true in bids.layout. default = true
layoutFilter (struct) – filter to pass to bids.layout. default = struct()

Returns:

BIDS layout returned by getData, opt options checked

Return type:

structure, structure

tempName()#: Creates a temporary directory and returns its fullpath

unfoldStruct(input)#

USAGE:

unfoldStruct(input)

validationInputFile(dir, fileNamePattern, prefix)#

Looks for file name pattern in a given directory and returns all the files that match that pattern but throws an error if it cannot find any.

A prefix can be added to the filename.

This function is mostly used that a file exists so that an error is thrown early when building a SPM job rather than at run time.

USAGE:

files = validationInputFile(dir, fileName, prefix)

Parameters:

dir (char) – Directory where the search will be conducted.
fileName (char) – file name pattern. Can be a regular expression except for the starting ^ and ending $. For example: 'sub-.*_ses-.*_task-.*_bold.nii'.
prefix (char) – prefix to be added to the filename pattern. This can also be a regular expression (ish). For example ,f looking for the files that start with c1 or c2 or c3, the prefix can be c[123].

Returns:

files:: (string array) returns the fullpath file list of all the files matching the required pattern.

validators#

isMni(input)#

Check if input is a valid MNI space

USAGE:

[idx, allowedSpaces] = isMni(input)

Parameters:: input (string or cell array of strings) – The space to check
Return idx:: A logical array indicating which elements of input are valid MNI spaces
Rtype idx:: logical array
Return allowedSpaces:: A cell array of valid MNI spaces
Rtype allowedSpaces:: cell array of strings

isSkullstripped(bidsFile)#

Check if the image is skullstripped.

USAGE:

status = isSkullstripped(bidsFile)

Parameters:: bidsFile (bids.File) – bids.File object
Returns:: status: true if the image is skullstripped
Return type:: logical

EXAMPLE:

bf = bids.File('sub-01_T1w', 'use_schema', false);

status = isSkullstripped(bf)

isTtest(structure)#

isZipped(file)#

USAGE:

status = isZipped(file)

API#

workflows#

roi#

QA#

lesion#

stats#

preproc#

batches#

lesion#

stats#

preproc#

IO#

QA#

bids#

bids_model#

bidspm#

data#

__pycache__#

cli#

constants#

defaults#

infra#

messages#

preproc#

fieldmaps#

utils#

reports#

partials#

stats#

results#

subject_level#

group_level#

utils#

utils#

validators#

pycache#