nipype.algorithms.modelgen module¶
The modelgen module provides classes for specifying designs for individual subject analysis of task-based fMRI experiments. In particular it also includes algorithms for generating regressors for sparse and sparse-clustered acquisition experiments.
SpecifyModel¶
Bases: BaseInterface
Makes a model specification compatible with spm/fsl designers.
The subject_info field should contain paradigm information in the form of a Bunch or a list of Bunch. The Bunch should contain the following information:
[Mandatory] conditions : list of names onsets : lists of onsets corresponding to each condition durations : lists of durations corresponding to each condition. Should be left to a single 0 if all events are being modelled as impulses. [Optional] regressor_names : list of str list of names corresponding to each column. Should be None if automatically assigned. regressors : list of lists values for each regressor - must correspond to the number of volumes in the functional run amplitudes : lists of amplitudes for each event. This will be ignored by SPM's Level1Design. The following two (tmod, pmod) will be ignored by any Level1Design class other than SPM: tmod : lists of conditions that should be temporally modulated. Should default to None if not being used. pmod : list of Bunch corresponding to conditions - name : name of parametric modulator - param : values of the modulator - poly : degree of modulationAlternatively, you can provide information through event files.
The event files have to be in 1, 2 or 3 column format with the columns corresponding to Onsets, Durations and Amplitudes and they have to have the name event_name.runXXX… e.g.: Words.run001.txt. The event_name part will be used to create the condition names.
Examples
>>> from nipype.algorithms import modelgen >>> from nipype.interfaces.base import Bunch >>> s = modelgen.SpecifyModel() >>> s.inputs.input_units = 'secs' >>> s.inputs.functional_runs = ['functional2.nii', 'functional3.nii'] >>> s.inputs.time_repetition = 6 >>> s.inputs.high_pass_filter_cutoff = 128. >>> evs_run2 = Bunch(conditions=['cond1'], onsets=[[2, 50, 100, 180]], durations=[[1]]) >>> evs_run3 = Bunch(conditions=['cond1'], onsets=[[30, 40, 100, 150]], durations=[[1]]) >>> s.inputs.subject_info = [evs_run2, evs_run3]>>> # Using pmod >>> evs_run2 = Bunch(conditions=['cond1', 'cond2'], onsets=[[2, 50], [100, 180]], durations=[[0], [0]], pmod=[Bunch(name=['amp'], poly=[2], param=[[1, 2]]), None]) >>> evs_run3 = Bunch(conditions=['cond1', 'cond2'], onsets=[[20, 120], [80, 160]], durations=[[0], [0]], pmod=[Bunch(name=['amp'], poly=[2], param=[[1, 2]]), None]) >>> s.inputs.subject_info = [evs_run2, evs_run3]
- Mandatory Inputs:
bids_event_file (a list of items which are a pathlike object or string representing an existing file) – TSV event file containing common BIDS fields: onset,`duration`, and categorization and amplitude columns. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.event_files (a list of items which are a list of items which are a pathlike object or string representing an existing file) – List of event description files 1, 2 or 3 column format corresponding to onsets, durations and amplitudes. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.functional_runs (a list of items which are a list of items which are a pathlike object or string representing an existing file or a pathlike object or string representing an existing file) – Data files for model. List of 4D files or list of list of 3D files per session.
high_pass_filter_cutoff (a float) – High-pass filter cutoff in secs.
input_units (‘secs’ or ‘scans’) – Units of event onsets and durations (secs or scans). Output units are always in secs.
subject_info (a list of items which are a Bunch or None) – Bunch or List(Bunch) subject-specific condition information. see SpecifyModel or for details. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.time_repetition (a float) – Time between the start of one volume to the start of the next image volume.
- Optional Inputs:
bids_amplitude_column (a string) – Column of the file passed to
bids_event_file
according to which to assign amplitudes to events.bids_condition_column (a string) – Column of the file passed to
bids_event_file
to the unique values of which events will be assignedto regressors. (Nipype default value:trial_type
)outlier_files (a list of items which are a pathlike object or string representing an existing file) – Files containing scan outlier indices that should be tossed.
parameter_source (‘SPM’ or ‘FSL’ or ‘AFNI’ or ‘FSFAST’ or ‘NIPY’) – Source of motion parameters. (Nipype default value:
SPM
)realignment_parameters (a list of items which are a pathlike object or string representing an existing file) – Realignment parameters returned by motion correction algorithm.
- Outputs:
session_info (any value) – Session info for level1designs.
SpecifySPMModel¶
Bases: SpecifyModel
Add SPM specific options to SpecifyModel
Adds:
concatenate_runs
output_units
Examples
>>> from nipype.algorithms import modelgen >>> from nipype.interfaces.base import Bunch >>> s = modelgen.SpecifySPMModel() >>> s.inputs.input_units = 'secs' >>> s.inputs.output_units = 'scans' >>> s.inputs.high_pass_filter_cutoff = 128. >>> s.inputs.functional_runs = ['functional2.nii', 'functional3.nii'] >>> s.inputs.time_repetition = 6 >>> s.inputs.concatenate_runs = True >>> evs_run2 = Bunch(conditions=['cond1'], onsets=[[2, 50, 100, 180]], durations=[[1]]) >>> evs_run3 = Bunch(conditions=['cond1'], onsets=[[30, 40, 100, 150]], durations=[[1]]) >>> s.inputs.subject_info = [evs_run2, evs_run3]
- Mandatory Inputs:
bids_event_file (a list of items which are a pathlike object or string representing an existing file) – TSV event file containing common BIDS fields: onset,`duration`, and categorization and amplitude columns. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.event_files (a list of items which are a list of items which are a pathlike object or string representing an existing file) – List of event description files 1, 2 or 3 column format corresponding to onsets, durations and amplitudes. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.functional_runs (a list of items which are a list of items which are a pathlike object or string representing an existing file or a pathlike object or string representing an existing file) – Data files for model. List of 4D files or list of list of 3D files per session.
high_pass_filter_cutoff (a float) – High-pass filter cutoff in secs.
input_units (‘secs’ or ‘scans’) – Units of event onsets and durations (secs or scans). Output units are always in secs.
subject_info (a list of items which are a Bunch or None) – Bunch or List(Bunch) subject-specific condition information. see SpecifyModel or for details. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.time_repetition (a float) – Time between the start of one volume to the start of the next image volume.
- Optional Inputs:
bids_amplitude_column (a string) – Column of the file passed to
bids_event_file
according to which to assign amplitudes to events.bids_condition_column (a string) – Column of the file passed to
bids_event_file
to the unique values of which events will be assignedto regressors. (Nipype default value:trial_type
)concatenate_runs (a boolean) – Concatenate all runs to look like a single session. (Nipype default value:
False
)outlier_files (a list of items which are a pathlike object or string representing an existing file) – Files containing scan outlier indices that should be tossed.
output_units (‘secs’ or ‘scans’) – Units of design event onsets and durations (secs or scans). (Nipype default value:
secs
)parameter_source (‘SPM’ or ‘FSL’ or ‘AFNI’ or ‘FSFAST’ or ‘NIPY’) – Source of motion parameters. (Nipype default value:
SPM
)realignment_parameters (a list of items which are a pathlike object or string representing an existing file) – Realignment parameters returned by motion correction algorithm.
- Outputs:
session_info (any value) – Session info for level1designs.
SpecifySparseModel¶
Bases: SpecifyModel
Specify a sparse model that is compatible with SPM/FSL designers [1].
Examples
>>> from nipype.algorithms import modelgen >>> from nipype.interfaces.base import Bunch >>> s = modelgen.SpecifySparseModel() >>> s.inputs.input_units = 'secs' >>> s.inputs.functional_runs = ['functional2.nii', 'functional3.nii'] >>> s.inputs.time_repetition = 6 >>> s.inputs.time_acquisition = 2 >>> s.inputs.high_pass_filter_cutoff = 128. >>> s.inputs.model_hrf = True >>> evs_run2 = Bunch(conditions=['cond1'], onsets=[[2, 50, 100, 180]], ... durations=[[1]]) >>> evs_run3 = Bunch(conditions=['cond1'], onsets=[[30, 40, 100, 150]], ... durations=[[1]]) >>> s.inputs.subject_info = [evs_run2, evs_run3]References
- Mandatory Inputs:
bids_event_file (a list of items which are a pathlike object or string representing an existing file) – TSV event file containing common BIDS fields: onset,`duration`, and categorization and amplitude columns. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.event_files (a list of items which are a list of items which are a pathlike object or string representing an existing file) – List of event description files 1, 2 or 3 column format corresponding to onsets, durations and amplitudes. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.functional_runs (a list of items which are a list of items which are a pathlike object or string representing an existing file or a pathlike object or string representing an existing file) – Data files for model. List of 4D files or list of list of 3D files per session.
high_pass_filter_cutoff (a float) – High-pass filter cutoff in secs.
input_units (‘secs’ or ‘scans’) – Units of event onsets and durations (secs or scans). Output units are always in secs.
subject_info (a list of items which are a Bunch or None) – Bunch or List(Bunch) subject-specific condition information. see SpecifyModel or for details. Mutually exclusive with inputs:
subject_info
,event_files
,bids_event_file
.time_acquisition (a float) – Time in seconds to acquire a single image volume.
time_repetition (a float) – Time between the start of one volume to the start of the next image volume.
- Optional Inputs:
bids_amplitude_column (a string) – Column of the file passed to
bids_event_file
according to which to assign amplitudes to events.bids_condition_column (a string) – Column of the file passed to
bids_event_file
to the unique values of which events will be assignedto regressors. (Nipype default value:trial_type
)model_hrf (a boolean) – Model sparse events with hrf.
outlier_files (a list of items which are a pathlike object or string representing an existing file) – Files containing scan outlier indices that should be tossed.
parameter_source (‘SPM’ or ‘FSL’ or ‘AFNI’ or ‘FSFAST’ or ‘NIPY’) – Source of motion parameters. (Nipype default value:
SPM
)realignment_parameters (a list of items which are a pathlike object or string representing an existing file) – Realignment parameters returned by motion correction algorithm.
save_plot (a boolean) – Save plot of sparse design calculation (requires matplotlib).
scale_regressors (a boolean) – Scale regressors by the peak. (Nipype default value:
True
)scan_onset (a float) – Start of scanning relative to onset of run in secs. (Nipype default value:
0.0
)stimuli_as_impulses (a boolean) – Treat each stimulus to be impulse-like. (Nipype default value:
True
)use_temporal_deriv (a boolean) – Create a temporal derivative in addition to regular regressor. Requires inputs:
model_hrf
.volumes_in_cluster (an integer >= 1) – Number of scan volumes in a cluster. (Nipype default value:
1
)- Outputs:
session_info (any value) – Session info for level1designs.
sparse_png_file (a pathlike object or string representing a file) – PNG file showing sparse design.
sparse_svg_file (a pathlike object or string representing a file) – SVG file showing sparse design.
- nipype.algorithms.modelgen.bids_gen_info(bids_event_files, condition_column='', amplitude_column=None, time_repetition=False)¶
Generate a subject_info structure from a list of BIDS .tsv event files.
- Parameters:
bids_event_files (list of str) – Filenames of BIDS .tsv event files containing columns including: ‘onset’, ‘duration’, and ‘trial_type’ or the condition_column value.
condition_column (str) – Column of files in bids_event_files based on the values of which events will be sorted into different regressors
amplitude_column (str) – Column of files in bids_event_files based on the values of which to apply amplitudes to events. If unspecified, all events will be represented with an amplitude of 1.
- Returns:
subject_info
- Return type:
list of Bunch
- nipype.algorithms.modelgen.gen_info(run_event_files)¶
Generate subject_info structure from a list of event files.
- nipype.algorithms.modelgen.orth(x_in, y_in)¶
Orthogonalize y_in with respect to x_in.
>>> orth_expected = np.array([1.7142857142857144, 0.42857142857142883, -0.85714285714285676]) >>> err = np.abs(np.array(orth([1, 2, 3],[4, 5, 6]) - orth_expected)) >>> all(err < np.finfo(float).eps) True
- nipype.algorithms.modelgen.scale_timings(timelist, input_units, output_units, time_repetition)¶
Scale timings given input and output units (scans/secs).
- Parameters:
timelist (list of times to scale)
input_units (‘secs’ or ‘scans’)
output_units (Ibid.)
time_repetition (float in seconds)
- nipype.algorithms.modelgen.spm_hrf(RT, P=None, fMRI_T=16)¶
python implementation of spm_hrf
See
spm_hrf
for implementation details:% RT - scan repeat time % p - parameters of the response function (two gamma % functions) % defaults (seconds) % p(0) - delay of response (relative to onset) 6 % p(1) - delay of undershoot (relative to onset) 16 % p(2) - dispersion of response 1 % p(3) - dispersion of undershoot 1 % p(4) - ratio of response to undershoot 6 % p(5) - onset (seconds) 0 % p(6) - length of kernel (seconds) 32 % % hrf - hemodynamic response function % p - parameters of the response function
The following code using
scipy.stats.distributions.gamma
doesn’t return the same result as thespm_Gpdf
function:hrf = gamma.pdf(u, p[0]/p[2], scale=dt/p[2]) - gamma.pdf(u, p[1]/p[3], scale=dt/p[3])/p[4]
Example
>>> print(spm_hrf(2)) [ 0.00000000e+00 8.65660810e-02 3.74888236e-01 3.84923382e-01 2.16117316e-01 7.68695653e-02 1.62017720e-03 -3.06078117e-02 -3.73060781e-02 -3.08373716e-02 -2.05161334e-02 -1.16441637e-02 -5.82063147e-03 -2.61854250e-03 -1.07732374e-03 -4.10443522e-04 -1.46257507e-04]