← Back to API reference

neuralset.extractors.neuro.FmriExtractor

pydantic model neuralset.extractors.neuro.FmriExtractor[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.

  • query (Query | None) – Per-event predicate selecting which fMRI variant(s) to load, evaluated directly on Fmri event objects. This is a deliberate subset of the pandas QueryEvents dialect: it supports space, preproc, and study string conditions with ==, !=, in, and not in combined with and/or/not. Referenced names are validated at construction, so typos fail fast — including in short-circuited branches. For richer filters, use a QueryEvents transform upstream.

  • from_space – Deprecated compatibility aliases for older configs. Prefer query; legacy selector fields remain in cache UIDs so old configs can keep using their existing cache namespace while they migrate. from_space="auto" additionally re-enables the deprecated projection-aware space selection (SurfaceProjector prefers fsaverage, GlasserProjector prefers fsLR, others prefer MNI); it has no query equivalent and will be removed in a future release.

  • from_preproc – Deprecated compatibility aliases for older configs. Prefer query; legacy selector fields remain in cache UIDs so old configs can keep using their existing cache namespace while they migrate. from_space="auto" additionally re-enables the deprecated projection-aware space selection (SurfaceProjector prefers fsaverage, GlasserProjector prefers fsLR, others prefer MNI); it has no query equivalent and will be removed in a future release.

  • 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.

Fields:
requirements: ClassVar[Any] = ('nilearn',)[source]
field offset: float = 0.0[source]
field event_types: Literal['Fmri'] = 'Fmri'[source]
field projection: BaseFmriProjector | None = None[source]
field cleaning: FmriCleaner | None = FmriCleaner(standardize='zscore_sample', detrend=True, high_pass=None, low_pass=None, filter=None, ensure_finite=True)[source]
field frequency: Literal['native'] | float = 'native'[source]
field padding: int | Literal['auto'] | None = None[source]
field query: Annotated[str, AfterValidator(func=validate_query)] | None = None[source]
field from_space: str | None = None[source]
field from_preproc: str | tuple[str, ...] | None = None[source]
field fwhm: float | None = None[source]
field infra: MapInfra = MapInfra(timeout_min=120, cpus_per_task=10, version='2')[source]
prepare(obj: DataFrame | Sequence[Event] | Sequence[Segment]) → None[source][source]

Pre-compute and cache extractor data for a collection of events.

This method triggers _get_data on every matching event so that expensive computation (e.g. model inference) is done once and cached. It then calls the extractor on a single event to populate the output shape, which is needed when allow_missing=True.

Call prepare before using the extractor in a dataloader.

Parameters:

obj (DataFrame or sequence of Event or sequence of Segment) – The structure containing the events. When calling prepare on several objects, prefer passing a list of events or segments over a DataFrame to avoid redundant conversion overhead.

← Back to API reference