laion_fmri.stimuli¶

Access the LAION-fMRI stimulus images and per-stimulus modalities.

Use after the stimuli have been downloaded via laion_fmri.download.download_stimuli() (or laion-fmri download-stimuli).

The Stimuli object is a single entry point for everything that is attached per stimulus image:

stim.metadata – the stimulus index (image_name, dataset, …)
stim.images – the JPEG images themselves
stim.embeddings – pretrained image embeddings (CLIP, DINOv2, …)
stim.segmentations – object-level segmentation masks
stim.captions – human + AI captions (text)

The auxiliary modalities (embeddings, segmentations, captions) are lazy: their files are not opened until you touch them, and they remain optional downloads.

Quick start¶

>>> import laion_fmri
>>> stim = laion_fmri.load_stimuli()
>>> stim.metadata.head()
>>> img  = stim.images.get("shared_12rep_LAION_cluster_1003_i0.jpg")  # PIL.Image
>>> feat = stim.embeddings.get("CLIP", "shared_12rep_LAION_cluster_1003_i0.jpg")
>>> mask = stim.segmentations.get(
...     "shared_12rep_LAION_cluster_1003_i0.jpg", "fingers"
... )

Functions

load_stimuli([data_dir])

Return a Stimuli handle to the local stimuli.

laion_fmri.stimuli.load_stimuli(data_dir: str | Path | None = None) → Stimuli[source]¶

Return a Stimuli handle to the local stimuli.

The naming mirrors laion_fmri.subject.load_subject() – the package-level convention is load_X(...) returning a handle object you then call methods on.

Parameters:: data_dir (str or Path, optional) – Override the configured data directory.
Returns:: A handle to the on-disk HDF5 + metadata CSV.
Return type:: Stimuli
Raises:: FileNotFoundError – If the stimuli haven’t been downloaded yet. Run laion_fmri.download.download_stimuli() first.

Classes

Stimuli([data_dir])

Hub for all per-stimulus data: images, embeddings, segmentations.

class laion_fmri.stimuli.Stimuli(data_dir: str | Path | None = None)[source]¶

Bases: object

Hub for all per-stimulus data: images, embeddings, segmentations.

Opens the stimuli HDF5 file lazily on first image access and keeps the handle open for the lifetime of the instance. Use as a context manager to explicitly release all open handles:

with Stimuli() as stim:
    img = stim.images.get("...")

Parameters:: data_dir (str or Path, optional) – Override the configured data directory. Defaults to laion_fmri.config.get_data_dir().

property captions: laion_fmri.captions.Captions¶

Per-stimulus human + AI captions.

Lazily reads task-images_desc-captions.csv. Raises FileNotFoundError if the captions file is missing (it ships alongside the stimulus images).

close() → None[source]¶: Release every open HDF5 handle (images + lazily-loaded modalities).

property embeddings: laion_fmri.embeddings.Embeddings¶

Pretrained image embeddings.

Loads every model whose HDF5 file is present on disk. If no embedding files are downloaded, accessing this property raises FileNotFoundError with installation guidance.

property images: _StimulusImages¶: Per-image access (raw bytes and decoded PIL).

property metadata: DataFrame¶

Stimulus metadata CSV as a pandas DataFrame.

Columns: image_name, dataset, participant, unique_or_shared, n_reps. Row order matches the stimuli HDF5 index.

property segmentations: laion_fmri.segmentations.Segmentations¶

Object-level segmentation masks (one per detected noun-instance).

Lazily opens task-images_desc-segmentations.h5. Raises FileNotFoundError if not downloaded yet.