Developers documentation

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) – TODO: add checks on newSuffix to make sure it only contains [a-zA-Z0-9]
filter (structure) – structure to decide which files to include. Default: struct([]) for no filter
force (boolean) – 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 (boolean) – defaults to true
force (boolean) – defaults to true

workflows 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 also: bidsCreateRoi, plotRoiTimeCourse(), getEventSpecificationRoiGlm()

workflows 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.

workflows 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 ((boolean)) – 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:

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

OR

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.

workflows 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 (boolean) – 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 functionalQA 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

batches

saveMatlabBatch(matlabbatch, batchType, opt, subLabel)

#ok<INUSL>

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:

(structure) The matlabbatch ready to run the spm job

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:

(structure)

setBatchPrintFigure(matlabbatch, opt, figureName)

template to creae new setBatch functions

USAGE:

matlabbatch = setBatchPrintFigure(matlabbatch, figureName)

Parameters:

matlabbatch
figureName (string)

Returns:

matlabbatch:

(structure) The matlabbatch ready to run the spm job

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 also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:: (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

batches 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:

(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:

(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:

(structure)

batches 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:

(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:

(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:

(structure)

setBatchFactorialDesignImplicitMasking(factorialDesign)

USAGE:

factorialDesign = setBatchFactorialDesignImplicitMasking(factorialDesign)

setBatchFatorialDesignGlobalCalcAndNorm(factorialDesign)

USAGE:

factorialDesign = setBatchFatorialDesignGlobalCalcAndNorm(factorialDesign)

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:

(structure)

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

Returns:

matlabbatch:

(structure)

setBatchSubjectLevelContrasts(matlabbatch, opt, subLabel, nodeName)

set batch for run and subject level contrasts

USAGE:

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

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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

Returns:

matlabbatch:

(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:

(structure)

setBatchTwoSampleTTest(varargin)

Sets up a group level GLM specification for a 2 sample T test

USAGE:

matlabbatch = setBatchTwoSampleTTest(matlabbatch, opt, nodeName)

Parameters:

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

Returns:

matlabbatch:

(cell) The matlabbatch ready to run the spm job

batches 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:

(structure) The matlabbatch ready to run the spm job

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:

(structure) The matlabbatch ready to run the spm job

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 also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:

(structure) The matlabbatch ready to run the spm job

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 also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:

(structure) The matlabbatch ready to run the spm job

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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.

https://github.com/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:

(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:

(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:

(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 also: bids.layout, getData().

Parameters:

opt (structure) – Options chosen for the analysis. See checkOptions.
subLabel (char) – subject label
action (char) – realign, realignReslice, realignUnwarp, 'reslice'

Returns:

matlabbatch:

(structure)
voxDim:

(array)
srcMetadata:

(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:

(cell) The matlabbatch ready to run the spm job

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:

(structure) The matlabbatch ready to run the spm job

setBatchSTC(varargin)

Creates batch for slice timing correction

USAGE:

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

Parameters:: BIDS (structure) – dataset layout.

See also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:

(structure) The matlabbatch ready to run the spm job

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 also: bids.layout, getData().

Parameters:

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:: (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 also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:

(structure) The matlabbatch ready to run the spm job

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:

(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:

(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 also: bids.layout, getData().

Parameters:

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

Returns:

matlabbatch:

(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 ; default is : fullfile(opt.dataDir, '..', 'derivatives', 'bidspm')
indexDependencies (logical) – Use ``’index_dependencies’, true` in bids.layout.

Returns:

opt:

(structure)
BIDS:

(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:: (structure) Options chosen for the analysis. See checkOptions().

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/>

EXAMPLE:

[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)

EXAMPLE:

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.

EXAMPLE:

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:

neuropower

some of the Canlab tools

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)

checkColumnParticipantsTsv(BIDS, columnHdr)

Check that a given column exists in participants.tsv

USAGE:

checkColumnParticipantsTsv(BIDS, columnHdr)

checkFmriprep(BIDS)

only fmriprep version >= 1.2 supported

USAGE:

status = checkFmriprep(BIDS)

Parameters:: BIDS – dataset layout.

See also: bids.layout, getData(). type BIDS: struct

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: struct

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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

Returns:

anatImage:

(string)
anatDataDir:

(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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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

addConfoundsToDesignMatrix(varargin)

Add some typical confounds to the design matrix of bids stat model.

This will update the design matrix of the root node of the model.

USAGE:

bm = addConfoundsToDesignMatrix(bm, 'strategy', strategy);

Parameters:

bm (BidsModel instance or path to a _smdl.json file) – bids stats model.
strategy (struct) –
structure describing the confoudd strategy.

The structure must have the following field:
- strategy: cell array of char with the strategies to apply.
The structure may have the following field:
- motion: motion regressors strategy
- scrub: scrubbing strategy
- wm_csf: white matter and cerebrospinal fluid regressors strategy
- non_steady_state: non steady state regressors strategy
See the nilearn documentation (mentioned above) for more information on the possible values those strategies can take.
updateName (logical) –
Append the name of the root node with a string describing the counfounds added.

rp-{motion}_scrub-{scrub}_tissue-{wm_csf}_nsso-{non_steady_state}

default = false

Return type:

BidsModel instance

Returns:

bids stats model with the confounds added.

EXAMPLE:

strategy.strategies = {'motion', 'wm_csf', 'scrub', 'non_steady_state'};
strategy.motion = 'full';
strategy.scrub = true;
strategy.non_steady_state = true;

bm = addConfoundsToDesignMatrix(path_to_statsmodel_file, 'strategy', strategy);

checkContrast(node, iCon)

Validates contrast specification

put some of that in bids.Model

USAGE:

contrast = checkContrast(node, iCon)

checkGroupBy(node)

Only certain type of GroupBy supported for now for each level

This helps doing some defensive programming

createDefaultStatsModel(BIDS, opt, ignore)

Creates a default model json file for a BIDS dataset

USAGE:

opt = createDefaultStatsModel(BIDS, opt)

Parameters:: BIDS – dataset layout.

See also: bids.layout, getData(). type BIDS: struct or path

Parameters:

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)

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

getDummyContrastFromParentNode(model, node)

USAGGE:

dummyContrastsList = getDummyContrastFromParentNode(model, node)

Parameters:

node (struct)
model (BidsModel object)

getDummyContrastsList(model, node)

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)

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)

Copyright 2022 bidspm developers

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

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:

the option structure with missing values filled in by the defaults.

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:

opt_out = mniToIxi(opt)

Parameters:

foo (structure) – options

Returns:

opt_out:

(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 (boolean) – parameter
install (boolean) – 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:

(boolean)

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 {}
space (cell string) – 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([]), ...
       'ignore', {})

Parameters:

space (cell string) – Defaults to {}
task (char or cell string) – Defaults to {}
ignore (cell string) – can be any of {'contrasts', 'transformations', 'dataset'}

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.

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 than 'bms-posterior' can``’bms-bms’`` be performed one aftr the other set a new model space and perform bayesian model selection on it. 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

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 (boolean) – If set to true errors are converted into warnings
verbose (boolean) – 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:

(boolean)

noSPMmat(varargin)

USAGE:

status = noSPMmat(opt, subLabel, spmMatFile)

Parameters:

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

Returns:

status:

(boolean)

notImplemented(varargin)

Throws a not implemented warning

USAGE:

notImplemented(functionName, msg, opt)

Parameters:

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

Returns:

status:

(boolean)

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure param fmapMetadata: type 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 also: bids.layout, getData().

Parameters:

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

Returns:

vdmFile:

(string)

preproc utils

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 (boolean)
verbose (boolean)

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

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 (boolean)

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 – dataset layout.

See also: bids.layout, getData(). type BIDS: structure

Parameters:

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.

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)

stats 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:

(boolean)

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()

stats 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"
 ]

groupLevelGlmType(opt, nodeName)

stats utils

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)

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

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: https://github.com/jsheunis/fMRwhy/blob/master/fmrwhy/qc/fmrwhy_qc_calculateStats.m

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 (boolean)

Returns:

structure:

(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, group] = setUpWorkflow(opt, workflowName, bidsDir, indexData)

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, default = true) – Use ``’index_dependencies’, true` in bids.layout.

Returns:

BIDS:

(structure) returned by getData
opt:

options checked

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)