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() # doctest: +SKIP
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 unicode string, ‘T’, a list of items which are a unicode string, a list of items which are a float) or a tuple of the form: (a unicode string, ‘T’, a list of items which are a unicode string, a list of items which are a float, a list of items which are a float) or a tuple of the form: (a unicode string, ‘F’, a list of items which are a tuple of the form: (a unicode string, ‘T’, a list of items which are a unicode string, a list of items which are a float) or a tuple of the form: (a unicode string, ‘T’, a list of items which are a unicode 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.
group_contrast : a boolean
Higher level contrast. Mutually exclusive with inputs: use_derivs.
matlab_cmd : a unicode 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)
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() # doctest: +SKIP
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.
flags : a dictionary with keys which are any value and with values which are any value
Additional arguments.
matlab_cmd : a unicode 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.
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

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 unicode 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)
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() # doctest: +SKIP
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.
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 unicode 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 (int or long)
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.
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() # doctest: +SKIP
in_files : a list of at least 2 items which are a pathlike object or string representing an existing file
List of files.
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 unicode 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}.
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() # doctest: +SKIP
in_files : a list of at least 2 items which are a pathlike object or string representing an existing file
Input files.
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 unicode 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)
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() # doctest: +SKIP
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.
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 unicode 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)
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() # doctest: +SKIP
contrast_index : an integer (int or long)
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.
extent_fdr_p_threshold : a float
P threshold on FDR corrected cluster size probabilities. (Nipype default value: 0.05)
extent_threshold : an integer (int or long)
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 unicode 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)

activation_forced : a boolean cluster_forming_thr : a float n_clusters : an integer (int or long) pre_topo_fdr_map : a pathlike object or string representing an existing file pre_topo_n_clusters : an integer (int or long) 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() # doctest: +SKIP
contrast_index : an integer (int or long)
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.
extent_threshold : an integer (int or long)
Minimum cluster size in voxels. (Nipype default value: 0)
matlab_cmd : a unicode 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)

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() # doctest: +SKIP
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.
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 unicode 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)
spm_mat_file : a pathlike object or string representing an existing file
SPM mat file.