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_model
str
, 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:
“spm”: This is the HRF model used in SPM. See
nilearn.glm.first_level.spm_hrf
.“spm + derivative”: SPM model plus its time derivative. This gives 2 regressors. See
nilearn.glm.first_level.spm_hrf
, andnilearn.glm.first_level.spm_time_derivative
.“spm + derivative + dispersion”: Idem, plus dispersion derivative. This gives 3 regressors. See
nilearn.glm.first_level.spm_hrf
,nilearn.glm.first_level.spm_time_derivative
, andnilearn.glm.first_level.spm_dispersion_derivative
.“glover”: This corresponds to the Glover HRF. See
nilearn.glm.first_level.glover_hrf
.“glover + derivative”: The Glover HRF + time derivative. This gives 2 regressors. See
nilearn.glm.first_level.glover_hrf
, andnilearn.glm.first_level.glover_time_derivative
.“glover”+ derivative + dispersion”: Idem, plus dispersion derivative. This gives 3 regressors. See
nilearn.glm.first_level.glover_hrf
,nilearn.glm.first_level.glover_time_derivative
, andnilearn.glm.first_level.glover_dispersion_derivative
.“fir”: Finite impulse response basis. This is a set of delayed dirac models.
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
Single-subject data (two runs) in native space
Example of surface-based first-level analysis
Surface-based dataset first and second level analysis of a dataset