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

Link to code

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 modulation

Alternatively, 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

Link to code

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

Link to code

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

1

Perrachione TK and Ghosh SS (2013) Optimized design and analysis of sparse-sampling fMRI experiments. Front. Neurosci. 7:55 http://journal.frontiersin.org/Journal/10.3389/fnins.2013.00055/abstract

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 the spm_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]