neuralset.extractors.neuro.FmriExtractor

class neuralset.extractors.neuro.FmriExtractor(*, event_types: Literal['Fmri'] = 'Fmri', aggregation: Literal['single', 'sum', 'mean', 'first', 'middle', 'last', 'cat', 'stack', 'trigger'] = 'single', allow_missing: bool = False, frequency: Literal['native'] | float = 'native', offset: float = 0.0, projection: BaseFmriProjector | None = None, cleaning: FmriCleaner | None = FmriCleaner(standardize='zscore_sample', detrend=True, high_pass=None, low_pass=None, filter=None, ensure_finite=True), padding: int | Literal['auto'] | None = None, from_space: str | None = None, from_preproc: str | tuple[str, ...] | None = None, fwhm: float | None = None, infra: MapInfra = MapInfra(folder=None, cluster=None, logs='{folder}/logs/{user}/%j', job_name=None, timeout_min=120, nodes=1, tasks_per_node=1, cpus_per_task=10, gpus_per_node=None, mem_gb=None, max_pickle_size_gb=None, slurm_constraint=None, slurm_partition=None, slurm_account=None, slurm_qos=None, slurm_use_srun=False, slurm_additional_parameters=None, conda_env=None, workdir=None, permissions=511, version='2', keep_in_ram=True, max_jobs=128, min_samples_per_job=1, forbid_single_item_computation=False, mode='cached'))[source][source]

fMRI feature extraction with optional projection, signal cleaning, and caching to a NumPy memmap.

Input: a volumetric image of shape [x, y, z, time] or a surface image of shape [n_vertices, time].

Preprocessing pipeline (each step is optional):

  1. Spatial smoothing (fwhm): If active, smooths the image with an isotropic Gaussian kernel.

  2. Spatial projection (projection): If active, projects the data to an array [n_features, time]. There are three projection types: SurfaceProjector (-> [n_vertices, time]), MaskProjector (-> [n_voxels, time]), and AtlasProjector (-> [n_parcels, time]).

  3. Signal cleaning (cleaning): If active, cleans the data using nilearn.signal.clean.

  4. Temporal resampling (frequency): If active, resamples the data to the target frequency, using np.interp.

Parameters:

  • offset (float) – Seconds to shift TRs forward to align delayed BOLD response.

  • projection (BaseFmriProjector | None) –

    Spatial projection config — one of:

    • SurfaceProjector(mesh="fsaverage5")

    • MaskProjector(mask="mni152_gm", resolution=2)

    • AtlasProjector(atlas="schaefer_2018", atlas_kwargs={"n_rois": 400})

    • None — keep raw volumetric / surface data

  • cleaning (FmriCleaner | None) – Signal cleaning config, passed to nilearn.signal.clean. None skips all cleaning.

  • frequency ("native" | float) – Target sampling frequency.

  • padding (int | "auto" | None) – Pad 1-D+T data to a uniform voxel count across subjects.

  • from_space (str | "auto" | None) – Input space to load. None (default) passes through when only one space is present, raises when multiple are found. "auto" uses a projection-aware heuristic. An explicit string selects that space.

  • from_preproc (str | tuple[str, ...] | None) – Filter events by preprocessing pipeline.

  • fwhm (float | None) – Full width at half maximum (in mm) for isotropic spatial smoothing via nilearn.image.smooth_img. Applied after masking and before projection. None skips smoothing.