laion_fmri.io

Low-level file loaders for laion_fmri.

Functions

load_freesurfer_label(path)	Load a FreeSurfer .label file's vertex indices.
load_gifti_mask(path)	Load a .func.gii surface mask as a 1-D boolean array.
load_nifti_4d(path, voxel_mask[, streaming])	Load a 4-D NIfTI's values within a voxel mask.
load_nifti_data(path, mask_path)	Load a 3-D NIfTI's values within a brain mask.
load_nifti_mask(path)	Load a NIfTI mask as a flat 1-D boolean array.
load_nifti_with_affine(path)	Load a NIfTI's data and 4×4 affine.
load_tsv(path)	Load a TSV file as a pandas DataFrame.

laion_fmri.io.load_freesurfer_label(path)

Load a FreeSurfer .label file’s vertex indices.

Parameters:

path (str or Path)

Returns:

Shape (n_label_vertices,), dtype int.

Return type:

np.ndarray

laion_fmri.io.load_gifti_mask(path)

Load a .func.gii surface mask as a 1-D boolean array.

Parameters:

path (str or Path)

Returns:

Shape (n_vertices,), dtype bool.

Return type:

np.ndarray

laion_fmri.io.load_nifti_4d(path, voxel_mask, streaming=False)

Load a 4-D NIfTI’s values within a voxel mask.

Returns each volume as a row of voxel values.

Parameters:

• path (str or Path)

• voxel_mask (np.ndarray) – 1-D bool array of length X*Y*Z. Build with load_nifti_mask for a brain-only mask, or combine brain + ROI + NC once on the caller side so the streaming path can apply the combination inline.

• streaming (bool) – If False (default), materialize the full 4-D array up front, then mask per volume. Decompresses any .nii.gz once; peak memory is the full 4-D file (~12 GB for a real session) plus the masked output. If True, stream the file volume-by-volume: for .nii.gz a custom gzip pipe is used so each volume is read sequentially without re-decompression, keeping peak memory at one volume plus the masked output. For raw .nii nibabel’s per-volume slicing is used (cheap, no streaming needed).

Returns:

Shape (n_volumes, n_mask_voxels), dtype float32, C-contiguous so row indexing is cheap.

Return type:

np.ndarray

laion_fmri.io.load_nifti_data(path, mask_path)

Load a 3-D NIfTI’s values within a brain mask.

Parameters:

• path (str or Path)

• mask_path (str or Path)

Returns:

Shape (n_brain_voxels,), dtype float32.

Return type:

np.ndarray

laion_fmri.io.load_nifti_mask(path)

Load a NIfTI mask as a flat 1-D boolean array.

Voxels with NaN are treated as out-of-mask. This matters when the source NIfTI is a stat map (e.g. the R^2 file the rsquare-derived brain mask is built from): GLMsingle writes NaN at voxels where the model couldn’t fit, and np.nan.astype(bool) is True – without this guard, those failed-fit voxels would leak into every downstream voxel-axis accessor.

Parameters:

path (str or Path)

Returns:

Shape (n_total_voxels,), dtype bool.

Return type:

np.ndarray

laion_fmri.io.load_nifti_with_affine(path)

Load a NIfTI’s data and 4×4 affine.

Parameters:

path (str or Path)

Return type:

tuple[np.ndarray, np.ndarray]

laion_fmri.io.load_tsv(path)

Load a TSV file as a pandas DataFrame.

Parameters:

path (str or Path)

Return type:

pd.DataFrame