nipype.interfaces.spm.model module¶

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

EstimateContrast¶

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

beta_images (a list of items which are a pathlike object or string representing an existing file) – Parameter estimates of the design matrix.

contrasts (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) 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_image (a pathlike object or string representing an existing file) – Mean-squared image of the residuals.

spm_mat_file (a pathlike object or string representing an existing file) – Absolute path to SPM.mat.

Optional Inputs

group_contrast (a boolean) – Higher level contrast. Mutually exclusive with inputs: use_derivs.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

use_derivs (a boolean) – Use derivatives for estimation. Mutually exclusive with inputs: group_contrast.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

con_images (a list of items which are a pathlike object or string representing an existing file) – Contrast images from a t-contrast.

ess_images (a list of items which are a pathlike object or string representing an existing file) – Contrast images from an F-contrast.

spmF_images (a list of items which are a pathlike object or string representing an existing file) – Stat images from an F-contrast.

spmT_images (a list of items which are a pathlike object or string representing an existing file) – Stat images from a t-contrast.

spm_mat_file (a 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() 
Mandatory Inputs

estimation_method (a 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_file (a pathlike object or string representing an existing file) – Absolute path to SPM.mat.

Optional Inputs

flags (a dictionary with keys which are any value and with values which are any value) – Additional arguments.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

write_residuals (a boolean) – Write individual residual images.

Outputs

ARcoef (a list of items which are a pathlike object or string representing an existing file) – Images of the AR coefficient.

Cbetas (a list of items which are a pathlike object or string representing an existing file) – Images of the parameter posteriors.

RPVimage (a pathlike object or string representing an existing file) – Resels per voxel image.

SDbetas (a list of items which are a pathlike object or string representing an existing file) – Images of the standard deviation of parameter posteriors.

SDerror (a list of items which are a pathlike object or string representing an existing file) – Images of the standard deviation of the error.

beta_images (a list of items which are a pathlike object or string representing an existing file) – Design parameter estimates.

labels (a pathlike object or string representing an existing file) – Label file.

mask_image (a pathlike object or string representing an existing file) – Binary mask to constrain estimation.

residual_image (a pathlike object or string representing an existing file) – Mean-squared image of the residuals.

residual_images (a list of items which are a pathlike object or string representing an existing file) – Individual residual images (requires write_residuals.

spm_mat_file (a 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

Optional Inputs

covariates (a 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_file (a pathlike object or string representing a file) – Use an implicit mask file to threshold.

global_calc_mean (a boolean) – Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omit (a boolean) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_values (a list of items which are a float) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization (1 or 2 or 3) – Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scaling (a boolean) – Do not perform grand mean scaling.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

threshold_mask_absolute (a float) – Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_none (a boolean) – Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relative (a float) – Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_threshold (a boolean) – Use implicit mask NaNs or zeros to threshold.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

spm_mat_file (a 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() 
Mandatory Inputs

bases (a 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_interval (a float) – Interscan interval in secs.

session_info (any value) – Session specific information generated by modelgen.SpecifyModel.

timing_units (‘secs’ or ‘scans’) – Units for specification of onsets.

Optional Inputs

factor_info (a 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).

flags (a 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_image (a 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_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

microtime_onset (a float) – The onset/time-bin in seconds for alignment (opt).

microtime_resolution (an 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.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

volterra_expansion_order (1 or 2) – Model interactions - no:1, yes:2.

Outputs

spm_mat_file (a 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() 
Mandatory Inputs

in_files (a list of at least 2 items which are a pathlike object or string representing an existing file) – List of files.

Optional Inputs

covariates (a 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_file (a pathlike object or string representing a file) – Use an implicit mask file to threshold.

global_calc_mean (a boolean) – Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omit (a boolean) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_values (a list of items which are a float) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization (1 or 2 or 3) – Global normalization None-1, Proportional-2, ANCOVA-3.

include_intercept (a boolean) – Include intercept in design. (Nipype default value: True)

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scaling (a boolean) – Do not perform grand mean scaling.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

threshold_mask_absolute (a float) – Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_none (a boolean) – Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relative (a float) – Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_threshold (a boolean) – Use implicit mask NaNs or zeros to threshold.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

user_covariates (a 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}.

Outputs

spm_mat_file (a 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() 
Mandatory Inputs

in_files (a list of at least 2 items which are a pathlike object or string representing an existing file) – Input files.

Optional Inputs

covariates (a 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_file (a pathlike object or string representing a file) – Use an implicit mask file to threshold.

global_calc_mean (a boolean) – Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omit (a boolean) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_values (a list of items which are a float) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization (1 or 2 or 3) – Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scaling (a boolean) – Do not perform grand mean scaling.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

threshold_mask_absolute (a float) – Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_none (a boolean) – Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relative (a float) – Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_threshold (a boolean) – Use implicit mask NaNs or zeros to threshold.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

spm_mat_file (a 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() 
Mandatory Inputs

paired_files (a 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.

Optional Inputs

ancova (a boolean) – Specify ancova-by-factor regressors.

covariates (a 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_file (a pathlike object or string representing a file) – Use an implicit mask file to threshold.

global_calc_mean (a boolean) – Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omit (a boolean) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_values (a list of items which are a float) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization (1 or 2 or 3) – Global normalization None-1, Proportional-2, ANCOVA-3.

grand_mean_scaling (a boolean) – Perform grand mean scaling.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scaling (a boolean) – Do not perform grand mean scaling.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

threshold_mask_absolute (a float) – Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_none (a boolean) – Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relative (a float) – Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

use_implicit_threshold (a boolean) – Use implicit mask NaNs or zeros to threshold.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

spm_mat_file (a 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() 
Mandatory Inputs

contrast_index (an integer) – Which contrast in the SPM.mat to use.

spm_mat_file (a pathlike object or string representing an existing file) – Absolute path to SPM.mat.

stat_image (a pathlike object or string representing an existing file) – Stat image.

Optional Inputs

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

extent_threshold (an integer) – Minimum cluster size in voxels. (Nipype default value: 0)

force_activation (a 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_threshold (a 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_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

use_fwe_correction (a 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_mcr (a boolean) – Run m-code using SPM MCR.

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

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

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

contrast_index (an integer) – Which contrast in the SPM.mat to use.

height_threshold (a float) – Stat value for initial thresholding (defining clusters).

spm_mat_file (a pathlike object or string representing an existing file) – Absolute path to SPM.mat.

stat_image (a pathlike object or string representing an existing file) – Stat image.

Optional Inputs

extent_threshold (an integer) – Minimum cluster size in voxels. (Nipype default value: 0)

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

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

group1_files (a list of at least 2 items which are a pathlike object or string representing an existing file) – Group 1 input files.

group2_files (a list of at least 2 items which are a pathlike object or string representing an existing file) – Group 2 input files.

Optional Inputs

covariates (a 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}.

dependent (a boolean) – Are the measurements dependent between levels.

explicit_mask_file (a pathlike object or string representing a file) – Use an implicit mask file to threshold.

global_calc_mean (a boolean) – Use mean for global calculation. Mutually exclusive with inputs: global_calc_omit, global_calc_values.

global_calc_omit (a boolean) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_values.

global_calc_values (a list of items which are a float) – Omit global calculation. Mutually exclusive with inputs: global_calc_mean, global_calc_omit.

global_normalization (1 or 2 or 3) – Global normalization None-1, Proportional-2, ANCOVA-3.

matlab_cmd (a string) – Matlab command to use.

mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

no_grand_mean_scaling (a boolean) – Do not perform grand mean scaling.

paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

spm_mat_dir (a pathlike object or string representing an existing directory) – Directory to store SPM.mat file (opt).

threshold_mask_absolute (a float) – Use an absolute threshold. Mutually exclusive with inputs: threshold_mask_none, threshold_mask_relative.

threshold_mask_none (a boolean) – Do not use threshold masking. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_relative.

threshold_mask_relative (a float) – Threshold using a proportion of the global value. Mutually exclusive with inputs: threshold_mask_absolute, threshold_mask_none.

unequal_variance (a boolean) – Are the variances equal or unequal between groups.

use_implicit_threshold (a boolean) – Use implicit mask NaNs or zeros to threshold.

use_mcr (a boolean) – Run m-code using SPM MCR.

use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs

spm_mat_file (a pathlike object or string representing an existing file) – SPM mat file.

Release	Devel
1.6.0	1.6.0
Download	Github

Table of Contents

Versions

Links

nipype.interfaces.spm.model module¶

EstimateContrast¶

EstimateModel¶

FactorialDesign¶

Level1Design¶

MultipleRegressionDesign¶

OneSampleTTestDesign¶

PairedTTestDesign¶

Threshold¶

ThresholdStatistics¶

TwoSampleTTestDesign¶