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=[0], min_onset=-24, mask_img=None, target_affine=None, target_shape=None, smoothing_fwhm=None, memory=Memory(location=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.

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, optional: 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, optional: Specifies the subset of subject labels to model. If ‘None’, will model all subjects in the dataset.

New in version 0.10.1.
img_filterslist of tuple (str, str), optional: 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”.
All other parameters correspond to a `FirstLevelModel` object, which
contains their documentation.
The subject label of the model will be determined directly
from the :term:`BIDS` dataset.
kwargs: :obj:`dict`: New in version 0.10.3.
Keyword arguments to be passed to functions called within this function.
Kwargs prefixed with ``confound_``
will be passed to :func:`~nilearn.interfaces.fmriprep.load_confounds`.
This allows ``first_level_from_bids`` to return
a specific set of confounds by relying on confound loading strategies
defined in :func:`~nilearn.interfaces.fmriprep.load_confounds`.
If no kwargs are passed, ``first_level_from_bids`` will return
all the confounds available in the confounds TSV files.

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