spectralbrain.io.export#

Export spectral decompositions, meshes, scalar maps, and connectomes.

All export functions accept the canonical type aliases from spectralbrain.runtime and write to standard neuroimaging or geometry formats. The primary cache format is HDF5 (via h5py).

Functions

`load_hdf5`(path)	Load a SpectralBrain HDF5 cache file.
`save_connectome`(path, matrix, *[, labels])	Save a connectome matrix to .tsv (BIDS-compatible).
`save_gifti_func`(path, scalars)	Save a scalar map or descriptor matrix as .func.gii.
`save_hdf5`(path, *[, eigenvalues, ...])	Save spectral decomposition and descriptors to HDF5.
`save_mesh`(path, vertices, faces)	Save a mesh to .ply, .obj, .stl, .vtk, or .vtp.
`save_npz`(path, **arrays)	Save named arrays to a compressed .npz archive.

spectralbrain.io.export.load_hdf5(path)[source]#

Load a SpectralBrain HDF5 cache file.

Parameters:: path (PathLike)
Returns:: dict – Keys mirror what was passed to save_hdf5().
Return type:: dict[str, Any]

spectralbrain.io.export.save_connectome(path, matrix, *, labels=None)[source]#

Save a connectome matrix to .tsv (BIDS-compatible).

Parameters:

path (PathLike) – Output .tsv.
matrix (ndarray, shape (R, R))
labels (list of str, optional) – Region names for the header row/column.

Returns:

Path

Return type:

Path

spectralbrain.io.export.save_gifti_func(path, scalars)[source]#

Save a scalar map or descriptor matrix as .func.gii.

Parameters:

path (PathLike) – Output .func.gii.
scalars (ndarray, shape (N,) or (N, T)) – Scalar overlay(s).

Returns:

Path

Return type:

Path

spectralbrain.io.export.save_hdf5(path, *, eigenvalues=None, eigenvectors=None, vertices=None, faces=None, descriptors=None, metadata=None, compression='gzip', compression_opts=4)[source]#

Save spectral decomposition and descriptors to HDF5.

This is the primary caching mechanism. A full eigendecomposition for a 160 k-vertex cortical surface (~300 eigenpairs) takes minutes; saving to HDF5 allows instant reload.

Parameters:

path (PathLike) – Output .h5 file.
eigenvalues (ndarray, shape (k,), optional)
eigenvectors (ndarray, shape (N, k), optional)
vertices (ndarray, shape (N, 3), optional)
faces (ndarray, shape (F, 3), optional)
descriptors (dict of {str: ndarray}, optional) – Named descriptor arrays (e.g. {"hks": hks_matrix}).
metadata (dict, optional) – Scalar metadata stored as HDF5 attributes (version, atlas, subject ID, structure name, backend used, …).
compression (str) – HDF5 compression filter.
compression_opts (int) – Compression level (1–9).

Returns:

Path – The written file path.

Return type:

Path

Examples

>>> sb.io.export.save_hdf5(
...     "sub-01_lh_white_spectral.h5",
...     eigenvalues=evals,
...     eigenvectors=evecs,
...     vertices=verts,
...     faces=faces,
...     descriptors={"hks": hks, "wks": wks},
...     metadata={"subject": "sub-01", "hemi": "lh",
...               "n_eigenvalues": 100},
... )

spectralbrain.io.export.save_mesh(path, vertices, faces)[source]#

Save a mesh to .ply, .obj, .stl, .vtk, or .vtp.

Backed by PyVista (a core dependency), so every listed format works with a default install and the geometry round-trips with spectralbrain.io.load_mesh().

Parameters:

path (PathLike) – Output file — format inferred from extension.
vertices (ndarray, shape (N, 3))
faces (ndarray, shape (F, 3))

Returns:

Path

Return type:

Path

spectralbrain.io.export.save_npz(path, **arrays)[source]#

Save named arrays to a compressed .npz archive.

Parameters:

path (PathLike) – Output .npz.
**arrays – Keyword → ndarray pairs.

Returns:

Path

Return type:

Path