spectralbrain.io.tractseg#

Import TractSeg outputs for spectral shape analysis.

TractSeg writes one binary NIfTI mask per white-matter bundle into a bundle_segmentations/ directory (72 bundles in the standard atlas, e.g. CST_left.nii.gz, AF_left.nii.gz). This module turns those masks into the geometric objects SpectralBrain operates on:

  • output="pointcloud" → a BrainPointCloud of the mask’s world-space voxel coordinates (ready for point-cloud Laplacian spectral analysis).

  • output="mesh" → a BrainMesh isosurface (marching cubes on the binary mask), ready for .decompose() and the mesh descriptors.

Both carry the bundle name and source path in their metadata.

Examples

>>> bundles = load_tractseg("/data/sub-01/tractseg_output", output="mesh")
>>> cst = bundles["CST_left"]
>>> decomp = cst.decompose(k=80)
>>> hks = sb.compute_hks(decomp, t_values=[1, 10, 100])

>>> # A single bundle across a cohort, as point clouds:
>>> files = discover_tractseg_subjects("/data/derivatives/tractseg", "CST_left")
>>> clouds = {sid: load_tractseg_bundle(p) for sid, p in files.items()}

Functions

discover_tractseg_bundles(tractseg_dir, *[, ...])

Find bundle-segmentation masks in one subject's TractSeg output.

discover_tractseg_subjects(root, bundle, *)

Find one bundle's mask across subjects in a derivatives tree.

load_tractseg(tractseg_dir, *[, bundles, ...])

Load all (or selected) bundles from one subject's TractSeg output.

load_tractseg_bundle(mask_path, *[, output, ...])

Load one TractSeg bundle mask as a point cloud or isosurface mesh.
spectralbrain.io.tractseg.discover_tractseg_bundles(tractseg_dir, *, bundles=None, subdir='bundle_segmentations')[source]#

Find bundle-segmentation masks in one subject’s TractSeg output.

Parameters:

  • tractseg_dir (PathLike) – TractSeg output directory for a subject.

  • bundles (list of str, optional) – Restrict to these bundle names (without extension, e.g. "CST_left"). Defaults to every *.nii.gz mask found.

  • subdir (str, optional) – Subdirectory holding the masks (default "bundle_segmentations"). Pass None to search tractseg_dir directly.

Returns:

dict of {bundle_name (Path})

Return type:

dict[str, Path]

spectralbrain.io.tractseg.discover_tractseg_subjects(root, bundle, *, pattern='sub-{sub}/tractseg_output', subdir='bundle_segmentations', subjects=None)[source]#

Find one bundle’s mask across subjects in a derivatives tree.

Parameters:

  • root (PathLike) – Derivatives root containing per-subject TractSeg outputs.

  • bundle (str) – Bundle name (e.g. "CST_left").

  • pattern (str) – Per-subject TractSeg directory relative to root, with a {sub} placeholder (bare label).

  • subdir (str, optional) – Mask subdirectory within each subject’s TractSeg output.

  • subjects (list of str, optional) – Restrict to these subjects.

Returns:

dict of {subject_id (Path}) – One bundle mask per subject.

Return type:

dict[str, Path]

spectralbrain.io.tractseg.load_tractseg(tractseg_dir, *, bundles=None, output='pointcloud', subdir='bundle_segmentations', **kwargs)[source]#

Load all (or selected) bundles from one subject’s TractSeg output.

Parameters:

  • tractseg_dir (PathLike) – TractSeg output directory for a subject.

  • bundles (list of str, optional) – Restrict to these bundle names. Defaults to all masks found.

  • output ("pointcloud" or "mesh") – Geometric representation per bundle.

  • subdir (str, optional) – Mask subdirectory (default "bundle_segmentations").

  • **kwargs – Forwarded to load_tractseg_bundle() (level, jitter, step_size, …).

Returns:

dict of {bundle_name (BrainPointCloud or BrainMesh}) – Bundles that fail to load (e.g. empty masks) are logged and skipped.

Return type:

dict[str, Any]

spectralbrain.io.tractseg.load_tractseg_bundle(mask_path, *, output='pointcloud', level=0.5, jitter=False, jitter_scale=0.25, seed=None, step_size=1)[source]#

Load one TractSeg bundle mask as a point cloud or isosurface mesh.

Parameters:

  • mask_path (PathLike) – A binary (or probabilistic) bundle mask NIfTI.

  • output ("pointcloud" or "mesh") – "pointcloud" returns a BrainPointCloud of the mask’s world-space voxel coordinates; "mesh" returns a BrainMesh isosurface via marching cubes.

  • level (float) – Threshold separating inside/outside the bundle (default 0.5; appropriate for binary masks and TractSeg probability maps).

  • jitter (bool) – Point-cloud only — optional sub-voxel jitter to break the regular grid (helps point-cloud Laplacian estimation).

  • jitter_scale (float) – Point-cloud only — optional sub-voxel jitter to break the regular grid (helps point-cloud Laplacian estimation).

  • seed (int | None) – Point-cloud only — optional sub-voxel jitter to break the regular grid (helps point-cloud Laplacian estimation).

  • step_size (int) – Mesh only — marching-cubes step (larger = coarser/faster).

Returns:

BrainPointCloud or BrainMesh – With metadata["bundle"] and metadata["source"] set.

Return type:

Any