release v0.1.0 thecppspmpipelinedevteam

CPP SPMRelease v0.1.0

the CPP SPM pipeline dev team

Sep 13, 2021

CONTENT

1 Set up 11.1 Configuration of the pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Pipeline defaults 52.1 checkOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 spm_my_defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Demos 9

4 Workflows 114.1 Slice Time Correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2 Spatial Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3 Smoothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.4 Subject level analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.5 Group level analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.6 Compute results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.7 Region of interest analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.8 Other . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.9 Helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 SPM batches 19

6 Quality control workflows 33

7 Function description 357.1 Subject level model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.2 Group level model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427.3 fieldmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437.4 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

8 Boilerplate methods section 518.1 Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518.2 fMRI data analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518.3 Group level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

9 Manual coregistration 53

10 Docker 5510.1 Build docker image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5510.2 Run docker image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

i

11 Contributing 5711.1 Function templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

12 Assumptions 61

13 Indices and tables 63

MATLAB Module Index 65

Index 67

ii

CHAPTER

ONE

SET UP

1.1 Configuration of the pipeline

1.1.1 Options

Most of the options you have chosen for your analysis will be set in a variable opt an Octave/Matlab structure.

The content of that structure can be defined:

• “at run” time in a script or a function (that we often label getOption)

• in a separate json file that can be loaded with loadAndCheckOptions().

You can find examples of both in the demos folder. You can also find a template function for getOption in the src/templates folder.

Required options

Set the task to analyze in the BIDS data set opt.taskName = 'auditory'

Selecting groups and subjects

Set the group of subjects to analyze:

opt.groups = {'control', 'blind'};

If there are no groups (i.e subjects names are of the form sub-01 for example) or if you want to run all subjects of allgroups then use:

opt.groups = {''};opt.subjects = {[]};

If you have 2 groups (cont and cat for example) the following will run cont01, cont02, cat03, cat04:

opt.groups = {'cont', 'cat'};opt.subjects = {[1 2], [3 4]};

If you have more than 2 groups but want to only run the subjects of 2 groups then you can use:

opt.groups = {'cont', 'cat'};opt.subjects = {[], []};

1

CPP SPM, Release v0.1.0

You can also directly specify the subject label for the participants you want to run:

opt.groups = {''};opt.subjects = {'01', 'cont01', 'cat02', 'ctrl02', 'blind01'};

1.1.2 BIDS model JSON files

This files allow you to specify the GLM to run and which contrasts to run. It follows the BIDS statistical modelextension and as implemented by fitlins

The model json file that describes:

• out to prepare the regressors for the GLM: Transformation

• the design matrix: X

• the contrasts to compute: contrasts

It also allows to specify those for different levels of the analysis:

• run

• session

• subject

• dataset

An example of json file could look something like that:

{"Name": "Basic","Description": "","Input": {

"task": "motionloc"},"Steps": [

{"Level": "subject","AutoContrasts": ["stim_type.motion", "stim_type.static"],"Contrasts": [

{"Name": "motion_vs_static","ConditionList": ["stim_type.motion", "stim_type.static"],"weights": [1, -1],"type": "t"

}]

},{

"Level": "dataset","AutoContrasts": [

"stim_type.motion","stim_type.static","motion_vs_static"

]}

(continues on next page)

2 Chapter 1. Set up

https://fitlins.readthedocs.io/en/latest/model.html


(continued from previous page)

]}

In brief this means:

• at the subject level automatically compute the t contrast against baseline for the condition motion and staticand compute the t-contrats for motion VS static with these given weights.

• at the level of the data set (so RFX) do the t contrast of the motion, static, motion VS static.

We are currently using this to run different subject level GLM models for our univariate and multivariate analysis wherein the first one we compute a con image that averages the beta image of all the runs where as in the latter case we getone con image for each run.

1.1. Configuration of the pipeline 3


4 Chapter 1. Set up

CHAPTER

TWO

PIPELINE DEFAULTS

Defaults of the pipeline.

2.1 checkOptions

src.defaults.checkOptions(opt)Check the option inputs and add any missing field with some defaults

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

USAGE:

opt = checkOptions(opt)

Parameters opt (structure) – structure or json filename containing the options.

Returns

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

REQUIRED FIELDS:

• opt.taskName

• opt.dataDir

IMPORTANT OPTIONS (with their defaults):

• opt.groups = {''} - group of subjects to analyze

• opt.subjects = {[]} - suject to run in each group space where we conduct the analysis

• opt.derivativesDir = '' - directory where the raw and derivatives are located. SeesetDerivativesDir() for more information.

• opt.space = 'MNI' - Space where we conduct the analysis

• opt.realign.useUnwarp = true

• opt.useFieldmaps = true - when set to true the preprocessing pipeline will look for the voxel dis-placement maps (created by bidsCreateVDM()) and will use them for realign and unwarp.

• opt.model.file = '' - path to the BIDS model file that contains the model to speficy and the contraststo compute.

5


OTHER OPTIONS (with their defaults):

• opt.zeropad = 2 - number of zeros used for padding subject numbers, in case subjects should befetched by their number 1 and not their label O1'.

• opt.query - a structure used to specify other options to only run analysis on certain files.struct('dir', 'AP', 'acq' '3p00mm'). See bids.query to see how to specify.

• opt.anatReference.type = 'T1w' - type of the anatomical reference

• opt.anatReference.session = '' - session label of the anatomical reference

• opt.skullstrip.threshold = 0.75 - Threshold used for the skull stripping. Any voxel withp(grayMatter) + p(whiteMatter) + p(CSF) > threshold will be included in the mask.

• opt.funcVoxelDims = [] - Voxel dimensions to use for resampling of functional data at normal-ization.

• opt.stc.skip = false - boolean flag to skip slice time correction or not.

• opt.stc.referenceSlice = [] - reference slice for the slice timing correction. If left emtpy themid-volume acquisition time point will be selected at run time.

• opt.stc.sliceOrder = [] - To be used if SPM can’t extract slice info. NOT RECOMMENDED,if you know the order in which slices were acquired, you should be able to recompute slice timing andadd it to the json files in your BIDS data set.

• opt.glm.roibased.do

• opt.QA.func.carpetPlot = true to plot carpet plot when running functionaQA

• opt.QA.func contains a lot of options used by spmup_first_level_qa in functionaQA

• opt.QA.func.MotionParameters = 'on'

• opt.QA.func.FramewiseDisplacement = 'on'

• opt.QA.func.Voltera = 'on'

• opt.QA.func.Globals = 'on'

• opt.QA.func.Movie = 'on' ; set it to off to skip generating movies of the time series

• opt.QA.func.Basics = 'on'

• opt.QA.glm.do = true - If set to true the residual images of a GLM at the subject levels will beused to estimate if there is any remaining structure in the GLM residuals (the power spec-tra are not flat) that could indicate the subject level results are likely confounded (seeplot_power_spectra_of_GLM_residuals and Accurate autocorrelation modeling substantiallyimproves fMRI reliability for more info.

(C) Copyright 2019 CPP_SPM developers

6 Chapter 2. Pipeline defaults

https://www.nature.com/articles/s41467-019-09230-w.pdf

https://www.nature.com/articles/s41467-019-09230-w.pdf


2.2 spm_my_defaults

Some more SPM options can be set in the spm_my_defaults.m.

2.2.1 auto-correlation modelisation

Use of FAST and not AR1 for auto-correlation modelisation.

Using FAST does not seem to affect results on time series with “normal” TRs but improves results when using se-quences: it is therefore used by default in this pipeline.

> Olszowy, W., Aston, J., Rua, C. et al. Accurate autocorrelation modeling > substantially improves fMRI reliability.Nat Commun 10, 1220 (2019). > https://doi.org/10.1038/s41467-019-09230-w

src.defaults.spm_my_defaults()Short description of what the function does goes here.

USAGE:

[argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])

This is where we set the defautls we want to use. These will overide 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 makethe script simpler.


2.2. spm_my_defaults 7

https://doi.org/10.1038/s41467-019-09230-w


8 Chapter 2. Pipeline defaults

CHAPTER

THREE

DEMOS

demos/face_repetitionlesion_detectionMoAEopenneurovismotion

9


10 Chapter 3. Demos

CHAPTER

FOUR

WORKFLOWS

List of the different workflows of the pipeline.

Each has to be run for each task independently. All parameters should be changed in the opt structure.

See the set up section.

src.workflows.bidsCopyRawFolder(opt, deleteZippedNii, modalitiesToCopy, unZip)Copies the folders from the raw folder to the derivatives folder, and will copy the dataset description and taskjson files to the derivatives directory.

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

USAGE:

bidsCopyRawFolder([opt,] ...[deleteZippedNii = true,] ...[modalitiesToCopy = {'anat', 'func', 'fmap'}])

Parameters

• opt (structure) – structure or json filename containing the options. See checkOptions()and loadAndCheckOptions().

• deleteZippedNii (boolean) – will delete the original zipped .gz if set to true

• modalitiesToCopy (cell) – for example {'anat', 'func', 'fmap'}

• unZip (boolean) –


src.workflows.bidsResliceTpmToFunc(opt)Reslices the tissue probability map (TPMs) from the segmentation to the mean functional.

USAGE:

bidsResliceTpmToFunc([opt])

Parameters opt (structure) – structure or json filename containing the options. SeecheckOptions() and loadAndCheckOptions().

11


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

It is necessary to run this workflow before running the functionalQA pipeline as the computation of the tSNRby spmup requires the TPMs to have the same dimension as the functional.


4.1 Slice Time Correction

src.workflows.bidsSTC(opt)Performs the slie timing correction of the functional data.

USAGE:

bidsSTC([opt])


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

The fields of the opt structure related to STC can still be used to do some slice timing correction even if noinformation can be found in the BIDS data set.

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

If no slice timing information is available from the file metadata or from the opt strcuture this step will beskipped.

See also getSliceOrder().

See the documentation for more information about slice timing correction.


More info available on this page of the SPM wikibook.

Some comments from here on STC, when it should be applied

At what point in the processing stream should you use it?

This is the great open question about slice timing, and it’s not super-answerable. Both SPM and AFNI recommend youdo it before doing realignment/motion correction, but it’s not entirely clear why. The issue is this:

If you do slice timing correction before realignment, you might look down your non-realigned time course for a givenvoxel on the border of gray matter and CSF, say, and see one TR where the head moved and the voxel sampled fromCSF instead of gray. This would results in an interpolation error for that voxel, as it would attempt to interpolate partof that big giant signal into the previous voxel. On the other hand, if you do realignment before slice timing correction,you might shift a voxel or a set of voxels onto a different slice, and then you’d apply the wrong amount of slice timingcorrection to them when you corrected - you’d be shifting the signal as if it had come from slice 20, say, when it actuallycame from slice 19, and shouldn’t be shifted as much.

There’s no way to avoid all the error (short of doing a four-dimensional realignment process combining spatial andtemporal correction - Remi’s note: fMRIprep does it), but I believe the current thinking is that doing slice timing firstminimizes your possible error. The set of voxels subject to such an interpolation error is small, and the interpolation

12 Chapter 4. Workflows

https://en.wikibooks.org/wiki/SPM/Slice_Timing

http://mindhive.mit.edu/node/109


into another TR will also be small and will only affect a few TRs in the time course. By contrast, if one realigns first,many voxels in a slice could be affected at once, and their whole time courses will be affected. I think that’s why itmakes sense to do slice timing first. That said, here’s some articles from the SPM e-mail list that comment helpfully onthis subject both ways, and there are even more if you do a search for “slice timing AND before” in the archives of thelist.

4.2 Spatial Preprocessing

Perform spatial preprocessing by running bidsSpatialPrepro

src.workflows.bidsSpatialPrepro(opt)Performs spatial preprocessing of the functional and structural data.

USAGE:

bidsSpatialPrepro([opt])


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

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

If you do not want to:

• to perform realign AND unwarp, make sure you set opt.realign.useUnwarp to true.

• normalize the data to MNI space, make sure you set opt.space to MNI.

If you want to:

• use another type of anatomical data than T1w as a reference or want to specify which anatomical session isto be used as a reference, you can set this in opt.anatReference:

opt.anatReference.type = 'T1w';opt.anatReference.session = 1;


src.workflows.bidsRealignReslice(opt)Realigns and reslices the functional data of a given task.

USAGE:

bidsRealignReslice(opt)


Assumes that bidsSTC() has already been run.


4.2. Spatial Preprocessing 13


src.workflows.bidsRealignUnwarp(opt)Realigns and unwarps the functional data of a given task.

USAGE:

bidsRealignReslice(opt)


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.


4.3 Smoothing

Perform smoothing of the functional data by running bidsSmoothing

src.workflows.bidsSmoothing(funcFWHM, opt)This performs smoothing to the functional data using a full width half maximum smoothing kernel of size“mm_smoothing”.

USAGE:

bidsSmoothing(funcFWHM, [opt])

Parameters

• funcFWHM (scalar) – How much smoothing was applied to the functional data in the pre-processing (Gaussian kernel size).



4.4 Subject level analysis

Perform the subject level analysis by running the ffx script: bidsFFX.

This will run twice, once for model specification and another time for model estimation. See the function for moredetails.

This will take each condition present in the events.tsv file of each run and convolve it with a canonical HRF. It willalso add the 6 realignment parameters of every run as confound regressors.

src.workflows.bidsFFX(action, opt, funcFWHM)

• builds the subject level fMRI model and estimates it.

OR



• compute the contrasts at the subject level.

USAGE:

bidsFFX(action, funcFWHM, [opt])

Parameters

• action (string) – Action to be conducted:specifyAndEstimate or contrasts.



• specifyAndEstimate for fMRI design + estimate and

• contrasts to estimate contrasts.

For unsmoothed data funcFWHM = 0, for smoothed data funcFWHM = ... mm. In this way we can make mul-tiple ffx for different smoothing degrees.


4.5 Group level analysis

Perform the group level analysis by running the RFX script: bidsRFX.

src.workflows.bidsRFX(action, opt, funcFWHM, conFWHM)

• smooths all contrast images created at the subject level

OR

• creates a mean structural image and mean mask over the sample,

• specifies and estimates the group level model,

• computes the group level contrasts.

USAGE:

bidsRFX(action, [opt,] [funcFWHM = 0,] [conFWHM = 0])

Parameters

• action (string) – Action to be conducted: smoothContrasts or RFX



• conFWHM (scalar) – How much smoothing will be applied to the contrast images (Gaussiankernel size).

• case smoothContrasts: smooth con images

4.5. Group level analysis 15


• case RFX: Mean Struct, MeanMask, Factorial design specification and estimation, Contrast estimation


4.6 Compute results

src.workflows.bidsResults(opt, funcFWHM, conFWHM)Computes the results for a series of contrast that can be specified at the run, subject or dataset step level (seecontrast specification following the BIDS stats model specification).

USAGE:

bidsResults([opt], funcFWHM, conFWHM)

Parameters



• conFWHM (scalar) – How much smoothing will be applied to the contrast images (Gaussiankernel size).

TODO

move ps file rename NIDM file if it does not exist create the default “result” field from the BIDSmodel file


src.workflows.bidsConcatBetaTmaps(opt, funcFWHM, deleteIndBeta, deleteIndTmaps)Make 4D images of beta and t-maps for the MVPA.

concatBetaImgTmaps(funcFWHM, opt, [deleteIndBeta = true,] [deleteIndTmaps = true])

Parameters

• opt (structure) – options structure

• funcFWHM ((boolean)) – smoothing (FWHM) applied to the the normalized EPI

• deleteIndBeta – decide to delete beta-maps

• deleteIndTmaps – decide to delete t-maps

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 namedsub-subLabel_task-taskName_space-space_labelfold.tsv.




4.7 Region of interest analysis

src.workflows.bidsRoiBasedGLM(opt)Will run a GLM within a ROI using MarsBar.

Will compute the percent signal change and the time course of the events or blocks of contrast specified in theBIDS model.


src.workflows.bidsCreateROI(opt)


4.8 Other

src.workflows.bidsCreateVDM(opt)Creates the voxel displacement maps from the fieldmaps of a BIDS dataset.

USAGE:

bidsCreateVDM([opt])


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


src.workflows.bidsResliceTpmToFunc(opt)Reslices the tissue probability map (TPMs) from the segmentation to the mean functional.

USAGE:

bidsResliceTpmToFunc([opt])


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

It is necessary to run this workflow before running the functionalQA pipeline as the computation of the tSNRby spmup requires the TPMs to have the same dimension as the functional.


src.workflows.bidsSegmentSkullStrip(opt)Segments and skullstrips the anatomical image.

USAGE:

bidsSegmentSkullStrip([opt])

4.7. Region of interest analysis 17




4.9 Helper functions

To be used if you want to create a new workflow.

src.workflows.setUpWorkflow(opt, workflowName)Calls some common functions to: - check the configuraton, - remove some old files from an eventual previouscrash - loads the layout of the BIDS dataset - tries to open a graphic window

USAGE:

[BIDS, opt, group] =setUpWorkflow(opt, workflowName)

Parameters

• opt (structure) – structure or json filename containing the options. See checkOptionsand loadAndCheckOptions.

• workflowName (string) – name that will be printed on screen

Returns

• BIDS (structure) returned by getData

• opt options checked

• group


src.workflows.saveAndRunWorkflow(matlabbatch, batchName, opt, subLabel)Saves the SPM matlabbatch and runs it

USAGE:

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

Parameters

• matlabbatch (structure) – list of SPM batches

• batchName (string) – name of the batch

• opt (structure) – structure or json filename containing the options. See checkOptionsand loadAndCheckOptions.

• subID (string) – subject ID



CHAPTER

FIVE

SPM BATCHES

List of functions to set SPM batches.

src.batches.setBatch3Dto4D(matlabbatch, 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 (string) – 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


src.batches.setBatchComputeVDM(matlabbatch, fmapType, refImage)Short description of what the function does goes here.

USAGE:

19


matlabbatch = setBatchComputeVDM(matlabbatch, fmapType, refImage)

Parameters


• fmapType –

• refImage – Reference image

Returns


matlabbatch = setBatchComputeVDM(type)

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


src.batches.setBatchContrasts(matlabbatch, spmMatFile, consess)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchContrasts(matlabbatch, spmMatFile, consess)

Parameters


• spmMatFile (string) –

• consess (cell) –

Returns

• matlabbatch (structure)


src.batches.setBatchCoregistrationFmap(matlabbatch, BIDS, opt, subLabel)Set the batch for the coregistration of field maps

USAGE:

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

Parameters

• BIDS (structure) – BIDS layout returned by getData.


• subLabel (string) –

Returns


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

20 Chapter 5. SPM batches



src.batches.setBatchCoregistrationFuncToAnat(matlabbatch, BIDS, opt, subLabel)Set the batch for corregistering the functional images to the anatomical image

USAGE:

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

Parameters




• subLabel (string) – subject ID

Returns



src.batches.setBatchCoregistration(matlabbatch, ref, src, other)Set the batch for coregistering the source images into the reference image

USAGE:

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

Parameters


• ref (string) – Reference image

• src (string) – Source image

• other (cell string) – ?

Returns


matlabbatch = setBatchCoregistrationGeneral(matlabbatch, ref, src, other)


src.batches.setBatchCreateVDMs(matlabbatch, BIDS, opt, subID)Short description of what the function does goes here.

USAGE:

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

Parameters



21




Returns


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


src.batches.setBatchEstimateModel(matlabbatch, opt, grpLvlCon)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchEstimateModel(matlabbatch, grpLvlCon)

Parameters


• grpLvlCon –

Returns



src.batches.setBatchFactorialDesign(matlabbatch, opt, funcFWHM, conFWHM)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchFactorialDesign(matlabbatch, opt, funcFWHM, conFWHM)

Parameters


• opt (structure) –

• funcFWHM –

• conFWHM –

Returns



src.batches.setBatchGroupLevelContrasts(matlabbatch, grpLvlCon, rfxDir)




src.batches.setBatchImageCalculation(varargin)Set a batch for a image calculation

USAGE:

matlabbatch = setBatchImageCalculation(matlabbatch, input, output, outDir,␣→˓expression)

Parameters


• input (cell) – list of images

• output (string) – name of the output file

• outDir (string) – output directory

• expression (string) – 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


src.batches.setBatchLesionAbnormalitiesDetection(matlabbatch, opt, images)Creates a batch to detect lesion abnormalities

USAGE:

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

Parameters matlabbatch (structure) – list of SPM batches

Returns



src.batches.setBatchLesionOverlapMap(matlabbatch, BIDS, opt, subLabel)Creates a batch for the lesion overlap map

USAGE:

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


Returns


23



src.batches.setBatchLesionSegmentation(matlabbatch, BIDS, opt, subLabel)Creates a batch to segment the anatomical image for lesion detection

USAGE:

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


Returns



src.batches.setBatchMeanAnatAndMask(matlabbatch, opt, funcFWHM, outputDir)Creates batxh to create mean anatomical image and a group mask

USAGE:

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

Parameters


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

• funcFWHM –

• outputDir (tring) –

Returns



src.batches.setBatchNormalizationSpatialPrepro(matlabbatch, opt, voxDim)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchNormalizationSpatialPrepro(matlabbatch, opt, voxDim)

Parameters


• opt (array) –

• voxDim –

Returns





src.batches.setBatchNormalize(matlabbatch, deformField, voxDim, imgToResample)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchNormalize(matlabbatch [, deformField] [, voxDim] [,␣→˓imgToResample])

Parameters


• deformField –

• voxDim –

• voxDim –

• imgToResample –

• imgToResample –

Returns



src.batches.setBatchPrintFigure(matlabbatch, figureName)template to creae new setBatch functions

USAGE:

matlabbatch = setBatchPrintFigure(matlabbatch, figureName)

Parameters

• matlabbatch –

• figureName (string) –

Returns



src.batches.setBatchRealign(varargin)Set the batch for realign / realign and reslice / realign and unwarp

USAGE:

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

Parameters

• matlabbatch (structure) – SPM batch

25



• action (string) – realign, realignReslice, realignUnwarp


• subLabel (string) – subject label

Returns

• matlabbatch (structure) (dimension)

• voxDim (array) (dimension)

TODO:

make which image is resliced more consistent 'which = []'


src.batches.setBatchReslice(matlabbatch, referenceImg, sourceImages, interp)Set the batch for reslicing source images to the reference image resolution

USAGE:

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

Parameters


• referenceImg (string or cellstring) – Reference image

• sourceImages (string or cellstring) – Source images

Returns



src.batches.setBatchResults(matlabbatch, result)Outputs the typical matlabbatch to compute the results for a given contrast

USAGE:

matlabbatch = setBatchResults(matlabbatch, opt, iStep, iCon, results)

Parameters


• results –

Returns





src.batches.setBatchSaveCoregistrationMatrix(matlabbatch, BIDS, opt, subLabel)Short description of what the function does goes here.

USAGE:

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

Parameters



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


Returns

• matlabbatch


src.batches.setBatchSegmentation(matlabbatch, opt, imageToSegment)Creates a batch to segment the anatomical image

USAGE:

matlabbatch = setBatchSegmentation(matlabbatch, opt)

Parameters



Returns

matlabbatch (structure)


src.batches.setBatchSelectAnat(matlabbatch, BIDS, opt, subLabel)Creates a batch to set an anatomical image

USAGE:

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

Parameters




• subLabel (string) – subject label

Returns

27


matlabbatch (structure)

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

• image type = opt.anatReference.type (default = T1w)

• session to select the anat from = opt.anatReference.session (default = 1)

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


src.batches.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




• subLabel (string) – subject ID

Returns


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 byrelying 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 strippingmask.


src.batches.setBatchSmoothConImages(matlabbatch, opt, funcFWHM, conFWHM)Creates a batch to smooth all the con images of all subjects

USAGE:

matlabbatch = setBatchSmoothConImages(matlabbatch, group, opt, funcFWHM, conFWHM)

Parameters

• matlabbatch –

• group –

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

• funcFWHM –



• conFWHM –

Returns

• matlabbatch


src.batches.setBatchSmoothingFunc(matlabbatch, BIDS, opt, subID, funcFWHM)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchSmoothingFunc(matlabbatch, BIDS, opt, subID, funcFWHM)

Parameters



• opt (string) – Options chosen for the analysis. See checkOptions().

• subID –

• funcFWHM –

Returns



src.batches.setBatchSmoothing(matlabbatch, images, FWHM, prefix)Small wrapper to create smoothing batch

USAGE:

matlabbatch = setBatchSmoothing(matlabbatch, images, FWHM, prefix)

Parameters


• images –

• funcFWHM –

• prefix –

Returns



src.batches.setBatchSTC(varargin)Creates batch for slice timing correction

USAGE:

29


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

Parameters




Returns


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

In the case the slice timing information was not specified in the json FILES in the BIDS data set (e.g it couldn’tbe extracted from the trento old scanner), then add this information manually in opt.sliceOrder field.

If this is empty the slice timing correction will not be performed

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


src.batches.setBatchSubjectLevelContrasts(matlabbatch, opt, subLabel, funcFWHM)Short description of what the function does goes here.

USAGE:

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

Parameters




• funcFWHM –

Returns

• matlabbatch


src.batches.setBatchSubjectLevelGLMSpec(varargin)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchSubjectLevelGLMSpec(matlabbatch, BIDS, opt, subLabel,␣→˓funcFWHM)

Parameters




• BIDS (structure) –



• funcFWHM (float) –

Returns

• argout1 (structure) (matlabbatch)


src.batches.setBatchSubjectLevelResults(varargin)Short description of what the function does goes here.

USAGE:

matlabbatch = setBatchSubjectLevelResults(matlabbatch, opt, subID, funcFWHM, iStep,␣→˓iCon)

Parameters




• funcFWHM (float) –

• iStep (positive integer) –

• iCon (positive integer) –

Returns



31

CHAPTER

SIX

QUALITY CONTROL WORKFLOWS

Manual coregistration

src.QA.anatomicalQA(opt)Computes several metrics for anatomical image.

USAGE:

anatomicalQA(opt)

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


src.QA.functionalQA(opt)For functional data, QA consists in getting temporal SNR and then check for motion - here we also computeadditional regressors to account for motion.

USAGE:

functionalQA(opt)


ASSUMPTIONS:

The previous step must have already been run:

• the functional images have been realigned and resliced using etiher bidsSpatialPrepro(),bidsRealignUnwarp(), bidsRealignReslice()

• the quality analysis of the anatomical data has been done with anatomicalQA()

• the tissue probability maps have been generated in the “native” space of each subject (usingbidsSpatialPrepro() or bidsSegmentSkullStrip()) and have been resliced to the dimension of thefunctional with bidsResliceTpmToFunc()


33


34 Chapter 6. Quality control workflows

CHAPTER

SEVEN

FUNCTION DESCRIPTION

List of functions in the src folder.

src.getAnatFilename(BIDS, subLabel, opt)Get the filename and the directory of an anat file for a given session and run. Unzips the file if necessary.

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

USAGE:

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

Parameters


• subLabel –

• subLabel – string

• opt – structure

Returns

• anatImage (string)

• anatDataDir (string)


src.getBoldFilename(varargin)Get the filename and the directory of a bold file for a given session / run.

Unzips the file if necessary.

USAGE:

[boldFileName, subFuncDataDir] = getBoldFilename(BIDS, subID, sessionID, runID, opt)

Parameters

• BIDS (structure) – returned by bids.layout when exploring a BIDS data set.

• subID (string) – label of the subject ; in BIDS lingo that means that for a file namesub-02_task-foo_bold.nii the subID will be the string 02

• sessionID (string) – session label (for ses-001, the label will be 001)

35


• runID (string) – run index label (for run-001, the label will be 001)

• opt (structure) – Mostly used to find the task name.

Returns

• boldFileName (string)

• subFuncDataDir (string)


src.getData(opt, BIDSdir, type)Reads the specified BIDS data set and updates the list of subjects to analyze.

USAGE:

[BIDS, opt] = getData(opt, [BIDSdir], [type = 'bold'])

Parameters


• BIDSdir (string) – the directory where the data is ; default is : fullfile(opt.dataDir,'..', 'derivatives', 'cpp_spm')

• type (string) – the data type you want to get the metadata of; supported: 'bold' (default)and T1w

Returns

• opt (structure)

• BIDS (structure)


src.getFuncVoxelDims(opt, subFuncDataDir, prefix, fileName)Short description of what the function does goes here.

USAGE:

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

Parameters


• subFuncDataDir –

• prefix –

• fileName –

Returns

• voxDim

• opt


36 Chapter 7. Function description


src.getInfo(BIDS, subLabel, opt, info, varargin)Wrapper function to fetch specific info in a BIDS structure returned by spm_bids.

USAGE:

varargout = getInfo(BIDS, subLabel, opt, info, varargin)

If info = sessions, this returns name of the sessions and their number:

[sessions, nbSessions] = getInfo(BIDS, subID, opt, 'sessions')

If info = runs, this returns name of the runs and their number for a specified session:

[runs, nbRuns] = getInfo(BIDS, subLabel, opt, 'runs', sessionID)

If info = filename, this returns the name of the file for a specified session and run:

filenames = getInfo(BIDS, subLabel, opt, 'filename', sessionID, runID, type)

Parameters

• BIDS (structure) – returned by bids.layout when exploring a BIDS data set.

• subLabel (string) – label of the subject ; in BIDS lingo that means that for a file namesub-02_task-foo_bold.nii the subID will be the string 02

• opt (structure) – Used to find the task name and to pass extra query options.

• info (string) – sessions, runs, filename.

• sessionLabel (string) – session label (for ses-001, the label will be 001)

• runIdx (string) – run index label (for run-001, the label will be 001)

• type (string) – datatype (bold, events, physio)


src.getMeanFuncFilename(BIDS, subLabel, opt)Get the filename and the directory of an mean functional file.

USAGE:

[meanImage, meanFuncDir] = getMeanFuncFilename(BIDS, subLabel, opt)

Parameters




Returns

• meanImage (string)

• meanFuncDir (string)


37


src.getPrefix(step, opt, funcFWHM)Generates prefix to append to file name to look for

USAGE:

[prefix, motionRegressorPrefix] = getPrefix(step, opt, funcFWHM)

Parameters

• step (string) –


• funcFWHM (scalar) –

Returns

• prefix

• motionRegressorPrefix


src.getRealignParamFile(fullpathBoldFileName, prefix)Short description of what the function does goes here.

USAGE:


Parameters

• argin1 (type) – (dimension) obligatory argument. Lorem ipsum dolor sit amet, consecteturadipiscing elit. Ut congue nec est ac lacinia.

• argin2 (string) – optional argument and its default value. And some of the options canbe shown in litteral like this or that.

• argin3 – (dimension) optional argument

Returns

• argout1 (type) (dimension)



src.getSliceOrder(opt, verbose)Get the slice order information from the BIDS metadata or from the opt structure.

USAGE:

sliceOrder = getSliceOrder(opt, [verbose = false])

Parameters


• verbose (boolean) –

Returns



• sliceOrder a vector of the time when each slice was acquired in in a volume or indi-cating the order of acquisition of the slices.

In the case the slice timing information was not specified in the json files in the BIDS data set thengetSliceOrder will try to read the opt structure for any relevant information. If this comes out empty thenslice timing correction will be skipped.

See also: bidsSTC


src.setDerivativesDir(opt)Sets the derivatives folder and the directory where to save the SPM jobs. The actual creation of the directory isdone by createDerivativeDir(opt).

USAGE:

opt = setDerivativesDir(opt)


Returns

• opt structure or json filename containing the options. See checkOptions() andloadAndCheckOptions().

Examples:

opt.dataDir = '/home/remi/data';opt.taskName = 'testTask';opt = setDerivativesDir(opt);

disp(opt.derivativesDir)'/home/remi/data/../derivatives/cpp_spm'

disp(opt.opt.jobsDir)'/home/remi/data/../derivatives/cpp_spm/JOBS/testTask

opt.dataDir = '/home/remi/data';opt.dataDir = '/home/remi/otherFolder';opt.taskName = 'testTask';opt = setDerivativesDir(opt);

disp(opt.derivativesDir)'/home/remi/otherFolder/derivatives/cpp_spm'

opt.dataDir = '/home/remi/data';opt.dataDir = '/home/remi/derivatives/preprocessing';opt.taskName = 'testTask';opt = setDerivativesDir(opt);

disp(opt.derivativesDir)'/home/remi/otherFolder/derivatives/preprocessing'


39


src.unzipImgAndReturnsFullpathName(fullpathImgName)Unzips an image if necessary

USAGE:

unzippedFullpathImgName = unzipImgAndReturnsFullpathName(fullpathImgName)

Parameters fullpathImgName (string) –

Returns

• unzippedFullpathImgName (string)

TODO:

• make it work on several images


7.1 Subject level model

src.subject_level.convertOnsetTsvToMat(opt, tsvFile)Converts an events.tsv file to an onset file suitable for SPM subject level analysis.

The function extracts from the events.tsv file the trials (with type, onsets, and durations) of th conditions ofinterest as requested in the model.json. It then stores them in a .mat file that can be fed directly in an SPM GLMbatch.

USAGE:

fullpathOnsetFileName = convertOnsetTsvToMat(opt, tsvFile)

Parameters


• tsvFile (string) –

Returns

fullpathOnsetFileName (string) name of the output .mat file.


src.subject_level.createAndReturnOnsetFile(opt, subID, tsvFile, funcFWHM)Creates an _onset.mat in the subject level GLM folder.

For a given _events.tsv file and _model.json, it creates a _onset.mat file that can directly be used for theGLM specification of a subject level model.

The file is moved directly into the folder of the GLM.

USAGE:

onsetFileName = createAndReturnOnsetFile(opt, subID, tsvFile, funcFWHM)

Parameters




• subID (string) –

• tsvFile (string) – fullpath name of the tsv file.

• funcFWHM (float) – size of the FWHM gaussian kernel used to the subject level GLM.Necessary for the GLM directory.

Returns

onsetFileName (string) fullpath name of the file created.


src.subject_level.deleteResidualImages(ffxDir)USAGE:

deleteResidualImages(ffxDir)

Parameters ffxDir (string) –


src.subject_level.getBoldFilenameForFFX(varargin)Gets the filename for this bold run for this task for the FFX setup and check that the file with the right prefix exist

USAGE:

[boldFileName, prefix] = getBoldFilenameForFFX(BIDS, opt, subID, funcFWHM, iSes,␣→˓iRun)

Parameters




• funcFWHM (scalar) –

• iSes (integer) –

• iRun (integer) –

Returns

• boldFileName (string)

• prefix (srting)


src.subject_level.getFFXdir(subLabel, funcFWFM, opt)Sets the name the FFX directory and creates it if it does not exist

USAGE:

ffxDir = getFFXdir(subLabel, funcFWFM, opt)

7.1. Subject level model 41


Parameters


• funcFWFM (scalar) –

• opt –

• opt – structure

Returns

• ffxDir (string)


src.subject_level.specifyContrasts(ffxDir, taskName, opt)Specifies the first level contrasts

USAGE:

contrasts = specifyContrasts(ffxDir, taskName, opt)

Parameters

• ffxDir –

• taskName –

• opt –

Returns

• contrasts (type) (dimension)

To know the names of the columns of the design matrix, type : strvcat(SPM.xX.name)

EXAMPLE Sn(1) ins 1 Sn(1) ins 2 Sn(1) T1 Sn(1) T2 Sn(1) R1 Sn(1) R2 Sn(1) R3 Sn(1) R4 Sn(1) R5 Sn(1)R6


7.2 Group level model

src.group_level.getGrpLevelContrastToCompute(opt)Returns the autocontrast part of the dataset step of the BIDS model

USAGE:

function [grpLvlCon, iStep] = getGrpLevelContrastToCompute(opt)


Returns

• grpLvlCon

• iStep




src.group_level.getRFXdir(opt, funcFWHM, conFWHM)Sets the name the group level analysis directory and creates it if it does not exist

USAGE:

rfxDir = getRFXdir(opt, funcFWHM, conFWHM, contrastName)

Parameters


• funcFWHM (scalar) – How much smoothing was applied to the functional data in the pre-processing.

• conFWHM (scalar) – How much smoothing will be applied to the contrast images.

• contrastName (string) –

Returns

rfxDir (string) Fullpath of the group level directory


7.3 fieldmaps

src.fieldmaps.getBlipDirection(metadata)Gets the total read out time of a sequence.

USAGE:

blipDir = getBlipDirection(metadata)

Parameters metadata (strcuture) – image metadata

Returns

• blipDir

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


src.fieldmaps.getMetadataFromIntendedForFunc(BIDS, fmapMetadata)Gets metadata of the associated bold file: - finds the bold file a fmap is intended for, - parse its filename, - get itsmetadata.

USAGE:

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

Parameters

• BIDS (structure) – BIDS layout returned by getData().

• fmapMetadata (structure) –

Returns

totalReadoutTime (type) (dimension)

7.3. fieldmaps 43


blipDir (type) (dimension)

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


src.fieldmaps.getTotalReadoutTime(metadata)Gets the total read out time of a sequence.

USAGE:

totalReadoutTime = getTotalReadoutTime(metadata)

Parameters metadata (strcuture) – image metadata

Returns

• totalReadoutTime (float) in millisecond

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


src.fieldmaps.getVdmFile(BIDS, opt, boldFilename)returns the voxel displacement map associated with a given bold file

USAGE:

vdmFile = getVdmFile(BIDS, opt, boldFilename)

Parameters


• opt (string) – Options chosen for the analysis. See checkOptions().

• boldFilename –

Returns

• vdmFile (string)


7.4 Utilities

Utility functions

src.utils.checkDependencies()Checks that that the right dependencies are installeda and loads the spm defaults.

USAGE:

checkDependencies()




src.utils.cleanCrash()Removes any files left over from a previous unfinished run of the pipeline, like any *.png imgages

USAGE:

cleanCrash()


src.utils.createDataDictionary(subFuncDataDir, fileName, nbColums)Short description of what the function does goes here.

USAGE:

[createDataDictionary(subFuncDataDir, fileName, nbColums)

Parameters

• subFuncDataDir (type) – Full path of the directory where the functional file is.

• fileName (string) – Name of the boldfile.

• nbColums (integer) – Number of extra columns to add as censoring regressors.


src.utils.createDerivativeDir(opt)Creates the derivative folder if it does not exist.

USAGE:

opt = createDerivativeDir(opt)



src.utils.createGlmDirName(opt, FWHM)


src.utils.getEnvInfo()Gets information about the environement and operating system to help generate data descriptors for the deriva-tives.

USAGE:

[OS, GeneratedBy] = getEnvInfo()

Returns

OS (structure) (dimension)

GeneratedBy (structure) (dimension)


7.4. Utilities 45


src.utils.getSubjectList(BIDS, opt)Returns the subjects to analyze in opt.subjects

USAGE:

opt = getSubjectList(BIDS, opt)

Parameters


• BIDSdir (string) – the directory where the data is ; default is : fullfile(opt.dataDir,'..', 'derivatives', 'cpp_spm')

Returns

• opt (structure)

To set set the groups of subjects to analyze:

opt.groups = {'control', 'blind'};

If there are no groups (i.e subjects names are of the form sub-01 for example) or if you want to run all subjectsof all groups then use:

opt.groups = {''};opt.subjects = {[]};

If you have more than 2 groups but want to only run the subjects of 2 groups then you can use:

opt.groups = {'cont', 'cat'};opt.subjects = {[], []};

You can also directly specify the subject label for the participants you want to run:

opt.groups = {''};opt.subjects = {'01', 'cont01', 'cat02', 'ctrl02', 'blind01'};


src.utils.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)


src.utils.isOctave()Returns true if the environment is Octave.

USAGE:



retval = isOctave()

Returns

retval (boolean)

(C) Copyright 2020 Agah Karakuzu (C) Copyright 2020 CPP_SPM developers

src.utils.loadAndCheckOptions(optionJsonFile)Loads the json file provided describing the options of an analysis. It then checks its content and fills any missingfields with the defaults.

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

USAGE:

opt = loadAndCheckOptions(optionJsonFile)

Parameters optionJsonFile (string) – Fullpath to the json file describing the options of an anal-ysis. It can also be an opt structure containing the options.

Returns

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


src.utils.manageWorkersPool(action, opt)Check matlab version and opens pool of workers for parallel work.

USAGE:

manageWorkersPool(action, opt)

Parameters

• action (string) – 'open' or 'close'


Requires to set some options:

opt.parallelize.do = true;opt.parallelize.nbWorkers = 3;opt.parallelize.killOnExit = true;


src.utils.printBatchName(batchName)


src.utils.printCredits()TODO: use the .zenodo.json to load contributors


7.4. Utilities 47


src.utils.printProcessingRun(groupName, iSub, subID, iSes, iRun)


src.utils.printProcessingSubject(iSub, subLabel)


src.utils.printWorklowName(workflowName)


src.utils.removeSpmPrefix(image, prefix)


src.utils.rmTrialTypeStr(conName)


src.utils.saveMatlabBatch(matlabbatch, batchType, opt, subID)Also save some basic environnment info.

USAGE:

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

Parameters


• batchType (string) –




src.utils.saveOptions(opt)Short description of what the function does goes here.

USAGE:




src.utils.setFields(structure, fieldsToSet, overwrite)Recursively loop through the fields of a target structure and sets the values as defined in the structurefieldsToSet 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 (string) –

• overwrite (boolean) –

Returns

• structure (structure)


src.utils.setGraphicWindow()Short description of what the function does goes here.

USAGE:


Parameters




Returns




src.utils.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 errorif 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 thanat run time.

USAGE:

files = validationInputFile(dir, fileName[, prefix])

Parameters

• dir (string) – Directory where the search will be conducted.

• fileName (string) – file name pattern. Can be a regular expression except for the starting^ and ending $. For example: 'sub-.*_ses-.*_task-.*_bold.nii'.

7.4. Utilities 49


• prefix (string) – prefix to be added to the filename pattern. This can also be a regularexpression (ish). For example ,f looking for the files that start with c1 or c2 or c3, the prefixcan be c[123].

Returns

files (string array) returns the fullpath file list of all the files matching the required pat-tern.

See also: spm_select.

Example: % % tissueProbaMaps = validationInputFile(anatDataDir, anatImage, ‘c[12]’);


src.utils.writeDatasetDescription(opt)



CHAPTER

EIGHT

BOILERPLATE METHODS SECTION

8.1 Preprocessing

The fMRI data were pre-processed and analyzed using statistical parametric mapping (SPM12 – v7487; Wellcome Cen-ter for Neuroimaging, London, UK; www.fil.ion.ucl.ac.uk/spm) running on {octave 4.{??} / matlab 20{XX} (Math-works)}.

The preprocessing of the functional images was performed in the following order: removing of dummy scans, {slicetiming correction}, realignment, normalization to MNI, smoothing.

{XX} dummy scans were removed to allow signal stabilization.

{Slice timing correction was then performed taking the {XX} th slice as a reference (interpolation: sinc interpolation).}

Functional scans from each participant were realigned using the mean image as a reference (SPM 2 passes ; number ofdegrees of freedom: 6 ; cost function: least square) (Friston et al, 1995).

The mean image obtained from realignement was then co-registered to the anatomical T1 image (number of degreesof freedom: 6 ; cost function: normalized mutual information) (Friston et al, 1995). The transformation matrix fromthis coregistration was then applied to all the functional images.

The anatomical T1 image was bias field corrected, segmented and normalized to MNI space (target space resolution:1 mm ; interpolation: 4th degree b-spline) using a unified segmentation. The deformation field obtained from this stepwas then applied to all the functional images (target space resolution equal that used at acquisition ; interpolation: 4thdegree b-spline)

Functional MNI normalized images were then spatially smoothed using a 3D gaussian kernel (FWHM = {XX} mm).

8.2 fMRI data analysis

At the subject level, we performed a mass univariate analysis with a linear regression at each voxel of the brain, usinggeneralized least squares with a global FAST model to account for temporal auto-correlation (Corbin et al, 2018) anda drift fit with discrete cosine transform basis (128 seconds cut-off). Image intensity scaling was done run-wide beforestatistical modeling such that the mean image will have mean intracerebral intensity of 100.

We modeled the fMRI experiment in an event related design with regressors entered into the run-specific design matrixafter convolving the onsets of each event with a canonical hemodynamic response function (HRF).

Nuisance covariates included the 6 realignment parameters to account for residual motion artefacts.

Contrast images were computed for the following condition and spatially smoothed using a 3D gaussian kernel (FWHM= {XX} mm).

51


8.3 Group level

WIP

8.4 References

Friston KJ, Ashburner J, Frith CD, Poline J-B, Heather JD & Frackowiak RSJ (1995) Spatial registration and normal-ization of images Hum. Brain Map. 2:165-189

Corbin, N., Todd, N., Friston, K. J. & Callaghan, M. F. Accurate modeling of temporal correlations in rapidly sampledfMRI time series. Hum. Brain Mapp. 39, 3884–3897 (2018).

—

Use the report function to get a print out of the content of a dataset.

src.reports.reportBIDS(opt)Prints out a human readable description of a BIDS data set.

USAGE:

reportBIDS(opt)



src.reports.copyGraphWindownOutput(opt, subID, 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, subID, [action = '',] [imgNb = 1])

Parameters


• subID (string) – Subject label (for example ‘01’).

• action (string) – Name to be given to the figure.

• imgNb (vector of integer) – Image numbers to look for. SPM increments them auto-matically when adding a new figure a folder.

Returns

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


52 Chapter 8. Boilerplate methods section

CHAPTER

NINE

MANUAL COREGISTRATION

Manual coregistration tools

lib.mancoreg.mancoreg(targetimage, sourceimage)This function displays 2 SPM ortho-views of a targetimage and a sourceimage image that can be manuallycoregistered.

USAGE:

mancoreg([targetimage,] [sourceimage])

Parameters

• targetimage (type) – Filename or fullpath of the target image. If none is provided youwill be asked by SPM to select one.

• sourceimage (string) – Filename or fullpath of the source image. If none is provided youwill be asked by SPM to select one.

Manual coregistration tool

The source image (bottom graph) can be manually rotated and translated with 6 slider controls. In the sourcegraph the source image can be exchanged with the target image using a radio button toggle. This is helpful forvisual fine control of the coregistration. The transformation matrix can be applied to a selected set of volumeswith the apply transformation button. If the transformation is to be applied to the original source file thatfile will also need to be selected. If the sourceimage or targetimage are not passed the user will be prompted witha file browser.

The code is loosely based on spm_image() and spm_orthoviews() It requires the m-file with the callbackfunctions for the user controls (mancoregCallbacks()).

lib.mancoreg.mancoregCallbacks(operation)Callback routines for mancoreg(): defines the different actions for the different buttons.

USAGE:

mancoreg_callbacks(operation)

Parameters operation (string) – Can be any of the following: move, toggle_off, toggle_on,reset, apply, plotmat

53


54 Chapter 9. Manual coregistration

CHAPTER

TEN

DOCKER

The recipe to build the docker image is in the Dockerfile

10.1 Build docker image

To build the image with with octave and SPM the Dockerfile just type:

docker build -t cpp_spm:0.0.1 .

This will create an image with the tag name cpp_spm_octave:0.0.1

10.2 Run docker image

The following code would start the docker image and would map 2 folders one for output and one for code you wantto run:

docker run -it --rm \-v [output_folder]:/output \-v [code_folder]:/code cpp_spm:0.0.1

To test it you can copy the MoAEpilot_run.m file in the demos/MoAE folder on your computer and then start runningthe docker and type:

# to change to the code folder inside the container# running the command 'ls' should show MoAEpilot_run.m and the content of# the foldercd demos/MoAE

# To run the batch_download_run scriptoctave --no-gui --eval MoAEpilot_run

55


56 Chapter 10. Docker

CHAPTER

ELEVEN

CONTRIBUTING

How to contribute to this project.

11.1 Function templates

11.1.1 Template proposal

% (C) Copyright 2020 CPP BIDS SPM-pipeline developpers

function [argout1, argout2] = templateFunction(argin1, argin2, argin3)%% Short description of what the function does goes here.%% USAGE::%% [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])%% :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet,% consectetur adipiscing elit. Ut congue nec est ac lacinia.% :type argin1: type% :param argin2: optional argument and its default value. And some of the% options can be shown in litteral like ``this`` or ``that``.% :type argin2: string% :param argin3: (dimension) optional argument%% :returns: - :argout1: (type) (dimension)% - :argout2: (type) (dimension)%% .. todo:%% - item 1% - item 2

% The code goes below

end

src.templates.templateFunction(argin1, argin2, argin3)Short description of what the function does goes here.

57


USAGE:


Parameters




Returns




11.1.2 Google template

See more information there

11.1.3 Example code in the help section

% (C) Copyright 2020 CPP BIDS SPM-pipeline developpers

function templateFunctionExample()% This function illustrates a documentation test defined for MOdox.% Other than that it does absolutely nothinghort description of what% the function does goes here.%% Examples:% a=2;% disp(a)% % Expected output is prefixed by '%||' as in the following line:% %|| 2% %% % The test continues because no interruption through whitespace,% % as the previous line used a '%' comment character;% % thus the 'a' variable is still in the namespace and can be% % accessed.% b=3+a;% disp(a+[3 4])% %|| [5 6]%% % A new test starts here because the previous line was white-space% % only. Thus the 'a' and 'b' variables are not present here anymore.% % The following expression raises an error because the 'b' variable

(continues on next page)

58 Chapter 11. Contributing

https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html


(continued from previous page)

% % is not defined (and does not carry over from the previous test).% % Because the expected output indicates an error as well,% % the test passes% disp(b)% %|| error('Some error')%% % A set of expressions is ignored if there is no expected output% % (that is, no lines starting with '%||').% % Thus, the following expression is not part of any test,% % and therefore does not raise an error.% error('this is never executed)%%% % tests end here because test indentation has ended

% The code goes below

src.templates.templateFunctionExample()This function illustrates a documentation test defined for MOdox. Other than that it does absolutely nothinghortdescription of what the function does goes here.

Examples: a=2; disp(a) % Expected output is prefixed by ‘%||’ as in the following line: %|| 2 % % The test con-tinues because no interruption through whitespace, % as the previous line used a ‘%’ comment character;% thus the ‘a’ variable is still in the namespace and can be % accessed. b=3+a; disp(a+[3 4]) %|| [5 6]

% A new test starts here because the previous line was white-space % only. Thus the ‘a’ and ‘b’ variablesare not present here anymore. % The following expression raises an error because the ‘b’ variable % is notdefined (and does not carry over from the previous test). % Because the expected output indicates an erroras well, % the test passes disp(b) %|| error(‘Some error’)

% A set of expressions is ignored if there is no expected output % (that is, no lines starting with ‘%||’). %Thus, the following expression is not part of any test, % and therefore does not raise an error. error(‘this isnever executed)

% tests end here because test indentation has ended


This pipeline contains a set of functions to run fMRI analysis on a BIDS data set using SPM12.

This can perform:

• slice timing correction,

• spatial preprocessing:

– realignment, coregistration func to anat, anat segmention, normalization to MNI space

– realignm and unwarp, coregistration func to anat, anat segmention

• smoothing,

• Quality analysis:

– for anatomical data

– for functional data

• GLM at the subject level

• GLM at the group level à la SPM (meaning using a summary statistics approach).

11.1. Function templates 59

https://bids.neuroimaging.io/


It can also prepare the data to run an MVPA analysis by running a GLM for each subject on non-normalized imagesand get one beta image for each condition to be used in the MVPA.

60 Chapter 11. Contributing

CHAPTER

TWELVE

ASSUMPTIONS

At the moment this pipeline makes some assumptions:

• it assumes that the dummy scans have been removed from the BIDS data set and it can jump straight into pre-processing,

• it assumes the metadata for a given task are the same as those the first run of the first subject this pipeline is beingrun on,

• it assumes that group are defined in the subject field (eg sub-ctrl01, sub-blind01, . . . ) and not in the partici-pants.tsv file.

61


62 Chapter 12. Assumptions

CHAPTER

THIRTEEN

INDICES AND TABLES

• genindex

• modindex

• search

63


64 Chapter 13. Indices and tables

MATLAB MODULE INDEX

llib.mancoreg, 53

ssrc, 35src.batches, 19src.defaults, 5src.fieldmaps, 43src.group_level, 42src.QA, 33src.reports, 52src.subject_level, 40src.templates, 57src.utils, 44src.workflows, 11

65


66 MATLAB Module Index

INDEX

AanatomicalQA() (in module src.QA), 33

BbidsConcatBetaTmaps() (in module src.workflows), 16bidsCopyRawFolder() (in module src.workflows), 11bidsCreateROI() (in module src.workflows), 17bidsCreateVDM() (in module src.workflows), 17bidsFFX() (in module src.workflows), 14bidsRealignReslice() (in module src.workflows), 13bidsRealignUnwarp() (in module src.workflows), 13bidsResliceTpmToFunc() (in module src.workflows),

11, 17bidsResults() (in module src.workflows), 16bidsRFX() (in module src.workflows), 15bidsRoiBasedGLM() (in module src.workflows), 17bidsSegmentSkullStrip() (in module src.workflows),

17bidsSmoothing() (in module src.workflows), 14bidsSpatialPrepro() (in module src.workflows), 13bidsSTC() (in module src.workflows), 12

CcheckDependencies() (in module src.utils), 44checkOptions() (in module src.defaults), 5cleanCrash() (in module src.utils), 44convertOnsetTsvToMat() (in module

src.subject_level), 40copyGraphWindownOutput() (in module src.reports),

52createAndReturnOnsetFile() (in module

src.subject_level), 40createDataDictionary() (in module src.utils), 45createDerivativeDir() (in module src.utils), 45createGlmDirName() (in module src.utils), 45

DdeleteResidualImages() (in module

src.subject_level), 41

FfunctionalQA() (in module src.QA), 33

GgetAnatFilename() (in module src), 35getBlipDirection() (in module src.fieldmaps), 43getBoldFilename() (in module src), 35getBoldFilenameForFFX() (in module

src.subject_level), 41getData() (in module src), 36getEnvInfo() (in module src.utils), 45getFFXdir() (in module src.subject_level), 41getFuncVoxelDims() (in module src), 36getGrpLevelContrastToCompute() (in module

src.group_level), 42getInfo() (in module src), 36getMeanFuncFilename() (in module src), 37getMetadataFromIntendedForFunc() (in module

src.fieldmaps), 43getPrefix() (in module src), 37getRealignParamFile() (in module src), 38getRFXdir() (in module src.group_level), 43getSliceOrder() (in module src), 38getSubjectList() (in module src.utils), 45getTotalReadoutTime() (in module src.fieldmaps), 44getVdmFile() (in module src.fieldmaps), 44getVersion() (in module src.utils), 46

IisOctave() (in module src.utils), 46

Llib.mancoreg (module), 53loadAndCheckOptions() (in module src.utils), 47

MmanageWorkersPool() (in module src.utils), 47mancoreg() (in module lib.mancoreg), 53mancoregCallbacks() (in module lib.mancoreg), 53

PprintBatchName() (in module src.utils), 47printCredits() (in module src.utils), 47printProcessingRun() (in module src.utils), 47

67


printProcessingSubject() (in module src.utils), 48printWorklowName() (in module src.utils), 48

RremoveSpmPrefix() (in module src.utils), 48reportBIDS() (in module src.reports), 52rmTrialTypeStr() (in module src.utils), 48

SsaveAndRunWorkflow() (in module src.workflows), 18saveMatlabBatch() (in module src.utils), 48saveOptions() (in module src.utils), 48setBatch3Dto4D() (in module src.batches), 19setBatchComputeVDM() (in module src.batches), 19setBatchContrasts() (in module src.batches), 20setBatchCoregistration() (in module src.batches),

21setBatchCoregistrationFmap() (in module

src.batches), 20setBatchCoregistrationFuncToAnat() (in module

src.batches), 21setBatchCreateVDMs() (in module src.batches), 21setBatchEstimateModel() (in module src.batches), 22setBatchFactorialDesign() (in module src.batches),

22setBatchGroupLevelContrasts() (in module

src.batches), 22setBatchImageCalculation() (in module

src.batches), 22setBatchLesionAbnormalitiesDetection() (in

module src.batches), 23setBatchLesionOverlapMap() (in module

src.batches), 23setBatchLesionSegmentation() (in module

src.batches), 24setBatchMeanAnatAndMask() (in module src.batches),

24setBatchNormalizationSpatialPrepro() (in mod-

ule src.batches), 24setBatchNormalize() (in module src.batches), 24setBatchPrintFigure() (in module src.batches), 25setBatchRealign() (in module src.batches), 25setBatchReslice() (in module src.batches), 26setBatchResults() (in module src.batches), 26setBatchSaveCoregistrationMatrix() (in module

src.batches), 26setBatchSegmentation() (in module src.batches), 27setBatchSelectAnat() (in module src.batches), 27setBatchSkullStripping() (in module src.batches),

28setBatchSmoothConImages() (in module src.batches),

28setBatchSmoothing() (in module src.batches), 29setBatchSmoothingFunc() (in module src.batches), 29

setBatchSTC() (in module src.batches), 29setBatchSubjectLevelContrasts() (in module

src.batches), 30setBatchSubjectLevelGLMSpec() (in module

src.batches), 30setBatchSubjectLevelResults() (in module

src.batches), 31setDerivativesDir() (in module src), 39setFields() (in module src.utils), 48setGraphicWindow() (in module src.utils), 49setUpWorkflow() (in module src.workflows), 18specifyContrasts() (in module src.subject_level), 42spm_my_defaults() (in module src.defaults), 7src (module), 35src.batches (module), 19src.defaults (module), 5src.fieldmaps (module), 43src.group_level (module), 42src.QA (module), 33src.reports (module), 52src.subject_level (module), 40src.templates (module), 57src.utils (module), 44src.workflows (module), 11

TtemplateFunction() (in module src.templates), 57templateFunctionExample() (in module

src.templates), 59

UunzipImgAndReturnsFullpathName() (in module

src), 39

VvalidationInputFile() (in module src.utils), 49

WwriteDatasetDescription() (in module src.utils), 50

68 Index

release v0.1.0 thecppspmpipelinedevteam

Documents