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.first_level_from_bids¶

nilearn.glm.first_level.first_level_from_bids(dataset_path, task_label, space_label=None, sub_labels=None, img_filters=None, t_r=None, slice_time_ref=0.0, hrf_model='glover', drift_model='cosine', high_pass=0.01, drift_order=1, fir_delays=None, min_onset=-24, mask_img=None, target_affine=None, target_shape=None, smoothing_fwhm=None, memory=None, memory_level=1, standardize=False, signal_scaling=0, noise_model='ar1', verbose=0, n_jobs=1, minimize_memory=True, derivatives_folder='derivatives', **kwargs)[source]¶

Create FirstLevelModel objects and fit arguments from a BIDS dataset.

If t_r is None, this function will attempt to load it from a bold.json. If slice_time_ref is None, this function will attempt to infer it from a bold.json. Otherwise, t_r and slice_time_ref are taken as given, but a warning may be raised if they are not consistent with the bold.json.

All parameters not described here are passed to FirstLevelModel.

The subject label of the model will be determined directly from the BIDS dataset.

Parameters:

dataset_pathstr or pathlib.Path

Directory of the highest level folder of the BIDS dataset. Should contain subject folders and a derivatives folder.

task_labelstr

Task_label as specified in the file names like _task-<task_label>_.

space_labelstr or None, default=None

Specifies the space label of the preprocessed bold.nii images. As they are specified in the file names like _space-<space_label>_.

sub_labelslist of str, default=None

Specifies the subset of subject labels to model. If None, will model all subjects in the dataset.

Added in version 0.10.1.

img_filterslist of tuple (str, str), default=None

Filters are of the form (field, label). Only one filter per field allowed. A file that does not match a filter will be discarded. Possible filters are 'acq', 'ce', 'dir', 'rec', 'run', 'echo', 'res', 'den', and 'desc'. Filter examples would be ('desc', 'preproc'), ('dir', 'pa') and ('run', '10').

slice_time_reffloat between 0.0 and 1.0, default= 0.0

This parameter indicates the time of the reference slice used in the slice timing preprocessing step of the experimental runs. It is expressed as a fraction of the t_r (time repetition), so it can have values between 0. and 1.

Deprecated since version 0.10.1: The default= 0 for slice_time_ref will be deprecated. The default value will change to None in 0.12.

derivatives_folderstr, default= "derivatives".

derivatives and app folder path containing preprocessed files. Like "derivatives/FMRIPREP".

kwargsdict

Keyword arguments to be passed to functions called within this function.

Kwargs prefixed with confounds_ will be passed to load_confounds. This allows first_level_from_bids to return a specific set of confounds by relying on confound loading strategies defined in load_confounds. If no kwargs are passed, first_level_from_bids will return all the confounds available in the confounds TSV files.

Added in version 0.10.3.

Returns:

modelslist of FirstLevelModel objects: Each FirstLevelModel object corresponds to a subject. All runs from different sessions are considered together for the same subject to run a fixed effects analysis on them.
models_run_imgslist of list of Niimg-like objects,: Items for the FirstLevelModel fit function of their respective model.
models_eventslist of list of pandas DataFrames,: Items for the FirstLevelModel fit function of their respective model.
models_confoundslist of list of pandas DataFrames or None,: Items for the FirstLevelModel fit function of their respective model.

Examples

If you want to only load the rotation and translation motion parameters confounds:

models, imgs, events, confounds = first_level_from_bids(
    dataset_path=path_to_a_bids_dataset,
    task_label="TaskName",
    space_label="MNI",
    img_filters=[("desc", "preproc")],
    confounds_strategy=("motion"),
    confounds_motion="basic",
)

If you want to load the motion parameters confounds with their derivatives:

models, imgs, events, confounds = first_level_from_bids(
    dataset_path=path_to_a_bids_dataset,
    task_label="TaskName",
    space_label="MNI",
    img_filters=[("desc", "preproc")],
    confounds_strategy=("motion"),
    confounds_motion="derivatives",
)

If you additionally want to load the confounds with CSF and white matter signal:

models, imgs, events, confounds = first_level_from_bids(
    dataset_path=path_to_a_bids_dataset,
    task_label="TaskName",
    space_label="MNI",
    img_filters=[("desc", "preproc")],
    confounds_strategy=("motion", "wm_csf"),
    confounds_motion="derivatives",
    confounds_wm_csf="basic",
)

If you also want to scrub high-motion timepoints:

models, imgs, events, confounds = first_level_from_bids(
    dataset_path=path_to_a_bids_dataset,
    task_label="TaskName",
    space_label="MNI",
    img_filters=[("desc", "preproc")],
    confounds_strategy=("motion", "wm_csf", "scrub"),
    confounds_motion="derivatives",
    confounds_wm_csf="basic",
    confounds_scrub=1,
    confounds_fd_threshold=0.2,
    confounds_std_dvars_threshold=0,
)

Please refer to the documentation of load_confounds for more details on the confounds loading strategies.

Examples using `nilearn.glm.first_level.first_level_from_bids`¶

First level analysis of a complete BIDS dataset from openneuro

BIDS dataset first and second level analysis

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

Beta-Series Modeling for Task-Based Functional Connectivity and Decoding

nilearn.glm.first_level.first_level_from_bids¶

Examples using nilearn.glm.first_level.first_level_from_bids¶

Examples using `nilearn.glm.first_level.first_level_from_bids`¶