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]
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.
bids_amplitude_column : a unicode string
Column of the file passed to bids_event_file according to which to assign amplitudes to events.
bids_condition_column : a unicode 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.
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]
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.
bids_amplitude_column : a unicode string
Column of the file passed to bids_event_file according to which to assign amplitudes to events.
bids_condition_column : a unicode 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.
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]  # doctest: +SKIP

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
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.
bids_amplitude_column : a unicode string
Column of the file passed to bids_event_file according to which to assign amplitudes to events.
bids_condition_column : a unicode 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 : a long integer >= 1
Number of scan volumes in a cluster. (Nipype default value: 1)
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]