Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.glm.first_level.make_first_level_design_matrix

nilearn.glm.first_level.make_first_level_design_matrix(frame_times, events=None, hrf_model='glover', drift_model='cosine', high_pass=0.01, drift_order=1, fir_delays=None, add_regs=None, add_reg_names=None, min_onset=-24, oversampling=50)[source]

Generate a design matrix from the input parameters.

Parameters:
frame_timesarray of shape (n_frames,)

The timing of acquisition of the scans in seconds.

eventspandas.DataFrame instance or None, default=None

Events data that describes the experimental paradigm. The DataFrame instance might have these keys:

  • 'onset': REQUIRED

    Column to specify the start time of each events in seconds. An error is raised if this key is missing.

  • 'duration': REQUIRED

    Column to specify the duration of each events in seconds.

    Warning

    Events with a duration of 0 seconds will be modelled using a ‘delta function’.

  • 'trial_type': OPTIONAL

    Column to specify per-event experimental conditions identifier. If missing each event are labelled ‘dummy’ and considered to form a unique condition.

  • 'modulation': OPTIONAL

    Column to specify the amplitude of each events. If missing the default is set to ones(n_events).

An experimental paradigm is valid if it has an 'onset' key and a 'duration' key. If these keys are missing an error will be raised. For the others keys a warning will be displayed. Particular attention should be given to the 'trial_type' key which defines the different conditions in the experimental paradigm.

hrf_modelstr, function, list of functions, or None

This parameter defines the HRF model to be used. It can be a string if you are passing the name of a model implemented in Nilearn. Valid names are:

It can also be a custom model. In this case, a function should be provided for each regressor. Each function should behave as the other models implemented within Nilearn. That is, it should take both t_r and oversampling as inputs and return a sample numpy array of appropriate shape.

Note

It is expected that "spm" standard and "glover" models would not yield large differences in most cases.

Note

In case of "glover" and "spm" models, the derived regressors are orthogonalized with respect to the main one.

drift_model{‘cosine’, ‘polynomial’, None}, default=’cosine’

Specifies the desired drift model.

high_passfloat, default=0.01

High-pass frequency in case of a cosine model (in Hz).

drift_orderint, default=1

Order of the drift model (in case it is polynomial).

fir_delaysarray of shape(n_onsets), list or None, default=None

Will be set to [0] if None is passed. In case of FIR design, yields the array of delays used in the FIR model (in scans).

add_regsarray of shape(n_frames, n_add_reg) or pandas DataFrame or None, default=None

additional user-supplied regressors, e.g. data driven noise regressors or seed based regressors.

add_reg_nameslist of (n_add_reg,) str, or None, default=None

If None, while add_regs was provided, these will be termed ‘reg_i’, i = 0..n_add_reg - 1 If add_regs is a DataFrame, the corresponding column names are used and add_reg_names is ignored.

min_onsetfloat, default=-24

Minimal onset relative to frame_times[0] (in seconds) events that start before frame_times[0] + min_onset are not considered.

oversamplingint, default=50

Oversampling factor used in temporal convolutions.

Returns:
design_matrixDataFrame instance,

holding the computed design matrix, the index being the frames_times and each column a regressor.

Examples using nilearn.glm.first_level.make_first_level_design_matrix

Default Mode Network extraction of ADHD dataset

Default Mode Network extraction of ADHD dataset

Single-subject data (two runs) in native space

Single-subject data (two runs) in native space

Examples of design matrices

Examples of design matrices