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_filea 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_filesa 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_runsa 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_cutoffa 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_infoa 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_repetitiona float

Time between the start of one volume to the start of the next image volume.

bids_amplitude_columna unicode string

Column of the file passed to bids_event_file according to which to assign amplitudes to events.

bids_condition_columna 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_filesa 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_parametersa list of items which are a pathlike object or string representing an existing file

Realignment parameters returned by motion correction algorithm.

session_infoany 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_filea 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_filesa 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_runsa 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_cutoffa 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_infoa 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_repetitiona float

Time between the start of one volume to the start of the next image volume.

bids_amplitude_columna unicode string

Column of the file passed to bids_event_file according to which to assign amplitudes to events.

bids_condition_columna 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_runsa boolean

Concatenate all runs to look like a single session. (Nipype default value: False)

outlier_filesa 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_parametersa list of items which are a pathlike object or string representing an existing file

Realignment parameters returned by motion correction algorithm.

session_infoany 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

bids_event_filea 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_filesa 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_runsa 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_cutoffa 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_infoa 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_acquisitiona float

Time in seconds to acquire a single image volume.

time_repetitiona float

Time between the start of one volume to the start of the next image volume.

bids_amplitude_columna unicode string

Column of the file passed to bids_event_file according to which to assign amplitudes to events.

bids_condition_columna 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_hrfa boolean

Model sparse events with hrf.

outlier_filesa 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_parametersa list of items which are a pathlike object or string representing an existing file

Realignment parameters returned by motion correction algorithm.

save_plota boolean

Save plot of sparse design calculation (requires matplotlib).

scale_regressorsa boolean

Scale regressors by the peak. (Nipype default value: True)

scan_onseta float

Start of scanning relative to onset of run in secs. (Nipype default value: 0.0)

stimuli_as_impulsesa boolean

Treat each stimulus to be impulse-like. (Nipype default value: True)

use_temporal_deriva boolean

Create a temporal derivative in addition to regular regressor. Requires inputs: model_hrf.

volumes_in_clustera long integer >= 1

Number of scan volumes in a cluster. (Nipype default value: 1)

session_infoany value

Session info for level1designs.

sparse_png_filea pathlike object or string representing a file

PNG file showing sparse design.

sparse_svg_filea 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]