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.

eventsDataFrame instance, optional
Events data that describes the experimental paradigm.
The DataFrame instance might have these keys:
‘onset’: column to specify the start time of each events in

seconds. An error is raised if this key is missing.

‘trial_type’: column to specify per-event experimental conditions

identifier. If missing each event are labelled ‘dummy’ and considered to form a unique condition.

‘duration’: column to specify the duration of each events in

seconds. If missing the duration of each events is set to zero.

‘modulation’: 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) or list, default=[0]

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

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

add_reg_nameslist of (n_add_reg,) strings, optional

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

Example of surface-based first-level analysis

Example of surface-based first-level analysis

Surface-based dataset first and second level analysis of a dataset

Surface-based dataset first and second level analysis of a dataset