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