laion_fmri.templates

Template-space projection of subject-T1w data.

Wraps two chains so callers reach a supported template through to_template(..., target=...) without touching the external libraries:

  • Surface chain: T1w volume → fsnative surface (nilearn.surface.vol_to_surf) → fsaverage surface (nitransforms.surface.SurfaceResampler). Used for the fsaverage target.

  • Volume chain: T1w volume → MNI305 via nitransforms.linear.Affine reading the recon’s talairach.lta. Used for the MNI305 target.

Functions

surface_to_template(subject, values[, ...])

Resample fsnative-surface input onto a surface template.

to_template(subject, values, target, *[, ...])

Project subject-T1w-space values into a template space.

volume_to_surface(subject, values[, target])

Volume-input → surface-target shortcut around to_template().

volume_to_template(subject, values, target, ...)

Volume-input → volume-target shortcut around to_template().
laion_fmri.templates.surface_to_template(subject, values, target='fsaverage', *, hemi=None, fsaverage_density='fsaverage5', output_dir=None, desc=None, session=None)[source]

Resample fsnative-surface input onto a surface template.

Parameters:

  • subject (Subject)

  • values (ndarray | dict[str, ndarray]) – Per-hemi fsnative-vertex array, or a {"L": ..., "R": ...} dict. With a single array, hemi must specify which hemisphere the array belongs to.

  • target (str) – Surface target (currently only "fsaverage").

  • hemi ("L" | "R" | None) – Required when values is a single array. Ignored when values is a dict.

  • fsaverage_density (str) – "fsaverage5", "fsaverage6", "fsaverage7" / "fsaverage".

  • output_dir – BIDS-writer kwargs; see to_template().

  • desc – BIDS-writer kwargs; see to_template().

  • session – BIDS-writer kwargs; see to_template().

Returns:

Same container type as values.

Return type:

ndarray | dict[str, ndarray]

laion_fmri.templates.to_template(subject, values, target, *, hemi=None, route='auto', surface='white', fsaverage_density='fsaverage5', fslr_density='32k', interpolation='linear', output_dir=None, desc=None, session=None, mask_source='anatomical')[source]

Project subject-T1w-space values into a template space.

Parameters:

  • subject (Subject)

  • values (np.ndarray | str | Path) – 1-D over the brain mask, 2-D (n_trials, n_voxels), or a path to a NIfTI already on the subject’s T1w grid.

  • target (str) – One of the entries in laion_fmri.templates._SUPPORTED_TARGETS.

  • hemi ("L" | "R" | None) – Hemisphere selector for surface targets.

  • route ("auto" | "surface" | "volume") – Currently every supported target has a single route, so "auto" always resolves to that route. The keyword is retained for forward compatibility; passing the wrong route for a target (e.g. route="surface" for "MNI305") raises ValueError.

  • surface (str) – Surface used by the vol→surf sampling step ("white", "pial", or "midthickness").

  • fsaverage_density (str) – "fsaverage5" (10k/hemi), "fsaverage6" (41k), or "fsaverage7" (164k).

  • fslr_density (str) – "32k" or "164k".

  • interpolation (str) – Forwarded to nilearn.surface.vol_to_surf.

  • output_dir (Path | None) – If given, also writes BIDS-conformant files to disk.

  • desc (str | None) – BIDS desc- and ses- tokens for the output filename(s).

  • session (str | None) – BIDS desc- and ses- tokens for the output filename(s).

  • mask_source ("anatomical" (default) | "rsquare") – Which brain mask the input values was produced under; see Subject.get_brain_mask(). Must match the mask source used in the upstream get_betas / get_noise_ceiling call.

Returns:

  • For surface targets (1-D ndarray, 2-D if input was)

  • multi-trial, or a {"L": ..., "R": ...} dict when

  • hemi=None.

  • For volume targets (nibabel.Nifti1Image.)

laion_fmri.templates.volume_to_surface(subject, values, target='fsaverage', **kwargs)[source]

Volume-input → surface-target shortcut around to_template().

Refuses volume targets so the caller’s intent is checked at the call site instead of silently routing somewhere unexpected.

laion_fmri.templates.volume_to_template(subject, values, target, **kwargs)[source]

Volume-input → volume-target shortcut around to_template().