Home · Quickstart · User Guide and Examples · Interfaces Index · Developers · About · Nipy

# 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 string

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

> bids_condition_columna 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 string

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

> bids_condition_columna 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 string

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

> bids_condition_columna 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_clusteran 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]