nipype.interfaces.spm.model module

The spm module provides basic functions for interfacing with matlab and spm to access spm tools.

EstimateContrast

Link to code

Bases: SPMCommand

Use spm_contrasts to estimate contrasts of interest

Examples

>>> import nipype.interfaces.spm as spm
>>> est = spm.EstimateContrast()
>>> est.inputs.spm_mat_file = 'SPM.mat'
>>> cont1 = ('Task>Baseline','T', ['Task-Odd','Task-Even'],[0.5,0.5])
>>> cont2 = ('Task-Odd>Task-Even','T', ['Task-Odd','Task-Even'],[1,-1])
>>> contrasts = [cont1,cont2]
>>> est.inputs.contrasts = contrasts
>>> est.run() 
beta_imagesa list of items which are a pathlike object or string representing an existing file

Parameter estimates of the design matrix.

contrastsa list of items which are a tuple of the form: (a string, ‘T’, a list of items which are a string, a list of items which are a float) or a tuple of the form: (a string, ‘T’, a list of items which are a string, a list of items which are a float, a list of items which are a float) or a tuple of the form: (a string, ‘F’, a list of items which are a tuple of the form: (a string, ‘T’, a list of items which are a string, a list of items which are a float) or a tuple of the form: (a string, ‘T’, a list of items which are a string, a list of items which are a float, a list of items which are a float))
List of contrasts with each contrast being a list of the form:

[(‘name’, ‘stat’, [condition list], [weight list], [session list])] If session list is None or not provided, all sessions are used. For F contrasts, the condition list should contain previously defined T-contrasts.

residual_imagea pathlike object or string representing an existing file

Mean-squared image of the residuals.

spm_mat_filea pathlike object or string representing an existing file

Absolute path to SPM.mat.

group_contrasta boolean

Higher level contrast. Mutually exclusive with inputs: use_derivs.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

use_derivsa boolean

Use derivatives for estimation. Mutually exclusive with inputs: group_contrast.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

con_imagesa list of items which are a pathlike object or string representing an existing file

Contrast images from a t-contrast.

ess_imagesa list of items which are a pathlike object or string representing an existing file

Contrast images from an F-contrast.

spmF_imagesa list of items which are a pathlike object or string representing an existing file

Stat images from an F-contrast.

spmT_imagesa list of items which are a pathlike object or string representing an existing file

Stat images from a t-contrast.

spm_mat_filea pathlike object or string representing an existing file

Updated SPM mat file.

EstimateModel

Link to code

Bases: SPMCommand

Use spm_spm to estimate the parameters of a model

http://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf#page=69

Examples

>>> est = EstimateModel()
>>> est.inputs.spm_mat_file = 'SPM.mat'
>>> est.inputs.estimation_method = {'Classical': 1}
>>> est.run() 
estimation_methoda dictionary with keys which are ‘Classical’ or ‘Bayesian2’ or ‘Bayesian’ and with values which are any value

Dictionary of either Classical: 1, Bayesian: 1, or Bayesian2: 1 (dict).

spm_mat_filea pathlike object or string representing an existing file

Absolute path to SPM.mat.

flagsa dictionary with keys which are any value and with values which are any value

Additional arguments.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

write_residualsa boolean

Write individual residual images.

ARcoefa list of items which are a pathlike object or string representing an existing file

Images of the AR coefficient.

Cbetasa list of items which are a pathlike object or string representing an existing file

Images of the parameter posteriors.

RPVimagea pathlike object or string representing an existing file

Resels per voxel image.

SDbetasa list of items which are a pathlike object or string representing an existing file

Images of the standard deviation of parameter posteriors.

SDerrora list of items which are a pathlike object or string representing an existing file

Images of the standard deviation of the error.

beta_imagesa list of items which are a pathlike object or string representing an existing file

Design parameter estimates.

labelsa pathlike object or string representing an existing file

Label file.

mask_imagea pathlike object or string representing an existing file

Binary mask to constrain estimation.

residual_imagea pathlike object or string representing an existing file

Mean-squared image of the residuals.

residual_imagesa list of items which are a pathlike object or string representing an existing file

Individual residual images (requires write_residuals.

spm_mat_filea pathlike object or string representing an existing file

Updated SPM mat file.

FactorialDesign

Link to code

Bases: SPMCommand

Base class for factorial designs

http://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf#page=77

covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘interaction’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, interaction, centering}.

explicit_mask_filea pathlike object or string representing a file

Use an implicit mask file to threshold.

global_calc_meana boolean

Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omita boolean

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_valuesa list of items which are a float

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization1 or 2 or 3

Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scalinga boolean

Do not perform grand mean scaling.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

threshold_mask_absolutea float

Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_nonea boolean

Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relativea float

Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_thresholda boolean

Use implicit mask NaNs or zeros to threshold.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.

Level1Design

Link to code

Bases: SPMCommand

Generate an SPM design matrix

http://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf#page=59

Examples

>>> level1design = Level1Design()
>>> level1design.inputs.timing_units = 'secs'
>>> level1design.inputs.interscan_interval = 2.5
>>> level1design.inputs.bases = {'hrf':{'derivs': [0,0]}}
>>> level1design.inputs.session_info = 'session_info.npz'
>>> level1design.inputs.flags = {'mthresh': 0.4}
>>> level1design.run() 
basesa dictionary with keys which are ‘hrf’ or ‘fourier’ or ‘fourier_han’ or ‘gamma’ or ‘fir’ and with values which are any value

Dictionary names of the basis function to parameters:

  • hrf

    • derivs – (2-element list) Model HRF Derivatives. No derivatives: [0,0], Time derivatives : [1,0], Time and Dispersion derivatives: [1,1]

  • fourier, fourier_han, gamma, or fir:

    • length – (int) Post-stimulus window length (in seconds)

    • order – (int) Number of basis functions

interscan_intervala float

Interscan interval in secs.

session_infoany value

Session specific information generated by modelgen.SpecifyModel.

timing_units‘secs’ or ‘scans’

Units for specification of onsets.

factor_infoa list of items which are a dictionary with keys which are ‘name’ or ‘levels’ and with values which are any value

Factor specific information file (opt).

flagsa dictionary with keys which are any value and with values which are any value

Additional arguments to the job, e.g., a common SPM operation is to modify the default masking threshold (mthresh).

global_intensity_normalization‘none’ or ‘scaling’

Global intensity normalization - scaling or none.

mask_imagea pathlike object or string representing an existing file

Image for explicitly masking the analysis.

mask_threshold‘-Inf’ or a float

Thresholding for the mask. (Nipype default value: -Inf)

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

microtime_onseta float

The onset/time-bin in seconds for alignment (opt).

microtime_resolutionan integer

Number of time-bins per scan in secs (opt).

model_serial_correlations‘AR(1)’ or ‘FAST’ or ‘none’

Model serial correlations AR(1), FAST or none. FAST is available in SPM12.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

volterra_expansion_order1 or 2

Model interactions - no:1, yes:2.

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.

MultipleRegressionDesign

Link to code

Bases: FactorialDesign

Create SPM design for multiple regression

Examples

>>> mreg = MultipleRegressionDesign()
>>> mreg.inputs.in_files = ['cont1.nii','cont2.nii']
>>> mreg.run() 
in_filesa list of at least 2 items which are a pathlike object or string representing an existing file

List of files.

covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘interaction’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, interaction, centering}.

explicit_mask_filea pathlike object or string representing a file

Use an implicit mask file to threshold.

global_calc_meana boolean

Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omita boolean

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_valuesa list of items which are a float

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization1 or 2 or 3

Global normalization None-1, Proportional-2, ANCOVA-3.

include_intercepta boolean

Include intercept in design. (Nipype default value: True)

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scalinga boolean

Do not perform grand mean scaling.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

threshold_mask_absolutea float

Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_nonea boolean

Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relativea float

Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_thresholda boolean

Use implicit mask NaNs or zeros to threshold.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

user_covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, centering}.

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.

OneSampleTTestDesign

Link to code

Bases: FactorialDesign

Create SPM design for one sample t-test

Examples

>>> ttest = OneSampleTTestDesign()
>>> ttest.inputs.in_files = ['cont1.nii', 'cont2.nii']
>>> ttest.run() 
in_filesa list of at least 2 items which are a pathlike object or string representing an existing file

Input files.

covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘interaction’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, interaction, centering}.

explicit_mask_filea pathlike object or string representing a file

Use an implicit mask file to threshold.

global_calc_meana boolean

Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omita boolean

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_valuesa list of items which are a float

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization1 or 2 or 3

Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scalinga boolean

Do not perform grand mean scaling.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

threshold_mask_absolutea float

Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_nonea boolean

Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relativea float

Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_thresholda boolean

Use implicit mask NaNs or zeros to threshold.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.

PairedTTestDesign

Link to code

Bases: FactorialDesign

Create SPM design for paired t-test

Examples

>>> pttest = PairedTTestDesign()
>>> pttest.inputs.paired_files = [['cont1.nii','cont1a.nii'],['cont2.nii','cont2a.nii']]
>>> pttest.run() 
paired_filesa list of at least 2 items which are a list of from 2 to 2 items which are a pathlike object or string representing an existing file

List of paired files.

ancovaa boolean

Specify ancova-by-factor regressors.

covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘interaction’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, interaction, centering}.

explicit_mask_filea pathlike object or string representing a file

Use an implicit mask file to threshold.

global_calc_meana boolean

Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omita boolean

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_valuesa list of items which are a float

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization1 or 2 or 3

Global normalization None-1, Proportional-2, ANCOVA-3.

grand_mean_scalinga boolean

Perform grand mean scaling.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scalinga boolean

Do not perform grand mean scaling.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

threshold_mask_absolutea float

Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_nonea boolean

Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relativea float

Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_thresholda boolean

Use implicit mask NaNs or zeros to threshold.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.

Threshold

Link to code

Bases: SPMCommand

Topological FDR thresholding based on cluster extent/size. Smoothness is estimated from GLM residuals but is assumed to be the same for all of the voxels.

Examples

>>> thresh = Threshold()
>>> thresh.inputs.spm_mat_file = 'SPM.mat'
>>> thresh.inputs.stat_image = 'spmT_0001.img'
>>> thresh.inputs.contrast_index = 1
>>> thresh.inputs.extent_fdr_p_threshold = 0.05
>>> thresh.run() 
contrast_indexan integer

Which contrast in the SPM.mat to use.

spm_mat_filea pathlike object or string representing an existing file

Absolute path to SPM.mat.

stat_imagea pathlike object or string representing an existing file

Stat image.

extent_fdr_p_thresholda float

P threshold on FDR corrected cluster size probabilities. (Nipype default value: 0.05)

extent_thresholdan integer

Minimum cluster size in voxels. (Nipype default value: 0)

force_activationa boolean

In case no clusters survive the topological inference step this will pick a culster with the highes sum of t-values. Use with care. (Nipype default value: False)

height_thresholda float

Value for initial thresholding (defining clusters). (Nipype default value: 0.05)

height_threshold_type‘p-value’ or ‘stat’

Is the cluster forming threshold a stat value or p-value?. (Nipype default value: p-value)

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

use_fwe_correctiona boolean

Whether to use FWE (Bonferroni) correction for initial threshold (height_threshold_type has to be set to p-value). (Nipype default value: True)

use_mcra boolean

Run m-code using SPM MCR.

use_topo_fdra boolean

Whether to use FDR over cluster extent probabilities. (Nipype default value: True)

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

activation_forced : a boolean cluster_forming_thr : a float n_clusters : an integer pre_topo_fdr_map : a pathlike object or string representing an existing file pre_topo_n_clusters : an integer thresholded_map : a pathlike object or string representing an existing file

Threshold.aggregate_outputs(runtime=None)

Collate expected outputs and apply output traits validation.

ThresholdStatistics

Link to code

Bases: SPMCommand

Given height and cluster size threshold calculate theoretical probabilities concerning false positives

Examples

>>> thresh = ThresholdStatistics()
>>> thresh.inputs.spm_mat_file = 'SPM.mat'
>>> thresh.inputs.stat_image = 'spmT_0001.img'
>>> thresh.inputs.contrast_index = 1
>>> thresh.inputs.height_threshold = 4.56
>>> thresh.run() 
contrast_indexan integer

Which contrast in the SPM.mat to use.

height_thresholda float

Stat value for initial thresholding (defining clusters).

spm_mat_filea pathlike object or string representing an existing file

Absolute path to SPM.mat.

stat_imagea pathlike object or string representing an existing file

Stat image.

extent_thresholdan integer

Minimum cluster size in voxels. (Nipype default value: 0)

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

clusterwise_P_FDR : a float clusterwise_P_RF : a float voxelwise_P_Bonf : a float voxelwise_P_FDR : a float voxelwise_P_RF : a float voxelwise_P_uncor : a float

ThresholdStatistics.aggregate_outputs(runtime=None, needed_outputs=None)

Collate expected outputs and apply output traits validation.

TwoSampleTTestDesign

Link to code

Bases: FactorialDesign

Create SPM design for two sample t-test

Examples

>>> ttest = TwoSampleTTestDesign()
>>> ttest.inputs.group1_files = ['cont1.nii', 'cont2.nii']
>>> ttest.inputs.group2_files = ['cont1a.nii', 'cont2a.nii']
>>> ttest.run() 
group1_filesa list of at least 2 items which are a pathlike object or string representing an existing file

Group 1 input files.

group2_filesa list of at least 2 items which are a pathlike object or string representing an existing file

Group 2 input files.

covariatesa list of items which are a dictionary with keys which are ‘vector’ or ‘name’ or ‘interaction’ or ‘centering’ and with values which are any value

Covariate dictionary {vector, name, interaction, centering}.

dependenta boolean

Are the measurements dependent between levels.

explicit_mask_filea pathlike object or string representing a file

Use an implicit mask file to threshold.

global_calc_meana boolean

Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omita boolean

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_valuesa list of items which are a float

Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization1 or 2 or 3

Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scalinga boolean

Do not perform grand mean scaling.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

spm_mat_dira pathlike object or string representing an existing directory

Directory to store SPM.mat file (opt).

threshold_mask_absolutea float

Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_nonea boolean

Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relativea float

Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

unequal_variancea boolean

Are the variances equal or unequal between groups.

use_implicit_thresholda boolean

Use implicit mask NaNs or zeros to threshold.

use_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

spm_mat_filea pathlike object or string representing an existing file

SPM mat file.