synthbold.io

Reusable utilities to handle common tensor validation and manipulation tasks.

synthbold.io.load_nifti(fname: str | Path) → tuple[ndarray, ndarray, Nifti1Header]

Load a NifTI file and return it as a Nifti1Image.

Parameters:

fname – Path to the NifTI file.

Returns:

Tuple of the data array, affine matrix, and header.

Raises:

TypeError – If the loaded file is not a Nifti1Image.

synthbold.io.load_zarr(fname: str | Path) → tuple[ndarray, dict[str, Any]]

Load map data from ZARR format.

Parameters:

fname – Path to the ZARR file.

Returns:

Tuple of the data array and attributes.

Raises:

ValueError – If the ZARR group contains more than one array.

synthbold.io.save_batch(fields: Mapping[str, ndarray | Tensor], dirname: str | Path, fmt: str, suffix: str = '', attrs: dict[str, Any] | None = None) → None

Saves each field in fields to <dirname>/<field><suffix>.<fmt>.

Parameters:

  • fields – Mapping of field name to data array, e.g. a NamedTuple’s _asdict().

  • dirname – Directory to save each field’s file into.

  • fmt – File format, either "zarr" or "nii".

  • suffix – Suffix inserted between each field name and its extension.

  • attrs – Attributes to save alongside ZARR arrays. Ignored for NIfTI.

Raises:

ValueError – If fmt is not "zarr" or "nii".

synthbold.io.save_mesh(fname: str | Path, data: ndarray | Tensor) → None

Creates a mesh from a binary array using the marching cubes algorithm and saves the mesh to disk in FreeSurfer binary format.

Parameters:

  • fname – File name for saving mesh file in FreeSurfer format.

  • data – Data array to save.

Raises:

ValueError – If data is not a NumPy array (after tensor conversion), or if it is not 3-dimensional.

synthbold.io.save_nifti(fname: str | Path, data: ndarray | Tensor, affine: ndarray | None = None, header: Nifti1Header | None = None, permute: bool = False, niivue: bool = False) → None

Save a NumPy array to a NIfTI file. If permute is True, the first and last axes of data are swapped. This is useful when the data has shape (N, X, Y, Z) but needs to be saved as (X, Y, Z, N) to store 3D volumes as a time series.

Parameters:

  • fname – File name for saving the NIfTI file.

  • data – Data array to save.

  • affine – Affine matrix for the NIfTI file.

  • header – Header for the NIfTI file.

  • permute – Whether to permute the axes of the data.

  • niivue – Whether to convert the data for fast visualization with Niivue.

Raises:

TypeError – If data is not a NumPy array (after tensor conversion).

Notes

For fast visualization with Niivue, the flag converts the numpy array to integer format and scales the data to maximum integer range.

synthbold.io.save_zarr(fname: str | Path, data: ndarray | Tensor, attrs: dict[str, Any]) → None

Save data to disk in ZARR format.

Parameters:

  • fname – File name for saving the ZARR file.

  • data – Data array to save.

  • attrs – Attributes to save with the data.

Raises:

TypeError – If the created ZARR object is not a zarr.Array.

synthbold.io.zarr_attributes(cls_name: str, device: device, seed: int | None) → dict[str, Any]

Build common metadata attributes for ZARR storage.

Parameters:

  • cls_name – Name of the generating class, stored under "generator".

  • device – PyTorch device the data was generated on.

  • seed – Random seed used for generation, if any.

Returns:

Dict of metadata suitable for passing as attrs to save_zarr.