nltools.io¶

Reading experiment files into nltools objects.

nltools I/O utilities.

events_to_dm turns a BIDS events table into boxcar regressors. HDF5 serialization for the data classes lives in nltools.io.h5; users reach it through BrainData.write/Adjacency.write and the constructors.

Functions:

Name	Description
`events_to_dm`	Convert a BIDS events table to boxcar regressors aligned to TRs.

Functions:¶

events_to_dm ¶

events_to_dm(
    events: DataFrame | DataFrame,
    *,
    run_length: int,
    sampling_freq: float,
) -> DataFrame

Convert a BIDS events table to boxcar regressors aligned to TRs.

Uses nilearn.glm.first_level.make_first_level_design_matrix with hrf_model=None to sample events onto the TR grid without HRF convolution — the caller is expected to call DesignMatrix.convolve() explicitly when convolution is desired. Drops nilearn's auto-added constant column; users add the intercept via add_poly(0).

Parameters:

Name	Type	Description	Default
`events`	`DataFrame \| DataFrame`	Events table with BIDS columns `onset`, `duration`, `trial_type` (required); `modulation` is passed through if present.	required
`run_length`	`int`	Number of TRs the run contains.	required
`sampling_freq`	`float`	Sampling frequency in Hz (= 1/TR).	required

Returns:

Type	Description
`DataFrame`	One column per unique `trial_type`, values in {0, modulation} indicating where each condition is active.

Examples:

import polars as pl
from nltools.io import events_to_dm

events = pl.DataFrame(
    {"onset": [0.0, 10.0], "duration": [5.0, 5.0], "trial_type": ["a", "b"]}
)
regressors = events_to_dm(events, run_length=20, sampling_freq=0.5)