From f224ad1cbcb056a599830fbf50117ea90873a4be Mon Sep 17 00:00:00 2001 From: mattcieslak Date: Tue, 17 Nov 2026 12:52:51 -0500 Subject: [PATCH 1/5] Add PTT transitions, SIFT2 launches, branch arbors and transitions I/O - run() and the CLI gain a --ptt preset plus explicit --step, --stop-mass, --fod-thresh, --fod-power, --curv-sigma and --probe-radius; --sift2 calibrates seed launches; --arbor writes per-bundle branch arbors; and save_transitions persists transition probabilities ("odx", "nifti" or "both"). - transitions.py saves and loads transition probabilities as ODX or 4-D NIfTI and computes marginal transition metrics (CoDI, CoAsy). - branches.py extracts branch-arbor ridges and reactive-flux streamlines, writes them as TRX, and exports and renders TRXViz projects. - solve_series/_solve take an on_step callback run after each iteration. --- src/mpat/__init__.py | 73 ++- src/mpat/afq.py | 88 ++- src/mpat/branches.py | 1195 ++++++++++++++++++++++++++++++++++ src/mpat/chain.py | 43 ++ src/mpat/cli.py | 23 +- src/mpat/fields.py | 31 +- src/mpat/kernel.py | 4 + src/mpat/quantify.py | 8 +- src/mpat/solve.py | 12 +- src/mpat/transitions.py | 846 ++++++++++++++++++++++++ tests/test_transitions_io.py | 146 +++++ 11 files changed, 2442 insertions(+), 27 deletions(-) create mode 100644 src/mpat/branches.py create mode 100644 src/mpat/transitions.py create mode 100644 tests/test_transitions_io.py diff --git a/src/mpat/__init__.py b/src/mpat/__init__.py index ec16619..92f7c2c 100644 --- a/src/mpat/__init__.py +++ b/src/mpat/__init__.py @@ -12,7 +12,25 @@ mpat.run(afq, n_proc=8, max_mem="16GB") # -> /mpat/ mpat.view(f"{output_dir}/mpat", bundles=["LeftArcuate"]) # in a notebook """ +import os + +os.environ.setdefault("NUMBA_THREADING_LAYER", "workqueue") +os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE") + from .afq import run +from .branches import ( + BranchArbor, + BranchCurve, + FluxTractogram, + extract_branch_arbor, + extract_flux_streamlines, + render_trxviz, + write_arbor, + write_arbors, + write_isosurface_gifti, + write_trx, + write_trxviz_project, +) from .chain import Chain, ChainConfig from .connectome import ConnectomeResult, build_connectome from .core import bundle_core @@ -21,6 +39,13 @@ from .geometry import class_chord_lengths from .quantify import BundleQuantification, afd_tract_metrics, quantify_bundle, sift2_optimize_launches from .solve import prepare_launches, segment_bundles, solve_bundle_cascade +from .transitions import ( + load_transitions_nifti, + load_transitions_odx, + marginal_transition_metrics, + save_transitions_nifti, + save_transitions_odx, +) from .viewer import save_html @@ -31,9 +56,45 @@ def view(*args, **kwargs): return _view(*args, **kwargs) -__all__ = ["BundleFields", "BundleQuantification", "Chain", "ChainConfig", "ConnectomeResult", - "DirectedFixelChain", "afd_tract_metrics", "build_connectome", "bundle_core", - "class_chord_lengths", "endpoint_patches", "fixel_streamlines", "flux_orientation", - "prepare_launches", "quantify_bundle", "restrict_endpoints", "run", "save_html", - "segment_bundles", "segment_lobes", "sift2_optimize_launches", "solve_bundle_cascade", - "view", "write_fixel_directory"] +__all__ = [ + "BranchArbor", + "BranchCurve", + "BundleFields", + "BundleQuantification", + "Chain", + "ChainConfig", + "ConnectomeResult", + "DirectedFixelChain", + "FluxTractogram", + "afd_tract_metrics", + "build_connectome", + "bundle_core", + "class_chord_lengths", + "endpoint_patches", + "extract_branch_arbor", + "extract_flux_streamlines", + "fixel_streamlines", + "flux_orientation", + "load_transitions_nifti", + "load_transitions_odx", + "marginal_transition_metrics", + "prepare_launches", + "quantify_bundle", + "render_trxviz", + "restrict_endpoints", + "run", + "save_html", + "save_transitions_nifti", + "save_transitions_odx", + "segment_bundles", + "segment_lobes", + "sift2_optimize_launches", + "solve_bundle_cascade", + "view", + "write_arbor", + "write_arbors", + "write_fixel_directory", + "write_isosurface_gifti", + "write_trx", + "write_trxviz_project", +] diff --git a/src/mpat/afq.py b/src/mpat/afq.py index 7fcec4b..c6d10b0 100644 --- a/src/mpat/afq.py +++ b/src/mpat/afq.py @@ -58,7 +58,7 @@ def tissue_labels(sh_img, pve_img, brain_mask_img=None): (treated as CSF, never entered), labelled 5 in dseg, and logged. Returns transient, absorbing class (0 outside, 1 GM, 2 CSF, 3 edge), dseg (1 WM, 2 GM, 3 CSF, 4 edge, 5 isolated WM).""" - from skimage.segmentation import find_boundaries + from scipy import ndimage as ndi mask = np.any(np.asarray(sh_img.dataobj) != 0, axis=-1) if brain_mask_img is not None: @@ -66,8 +66,6 @@ def tissue_labels(sh_img, pve_img, brain_mask_img=None): csf, gm, wm = np.moveaxis(_on_grid(pve_img, sh_img), -1, 0) # holes inside the fODF region (voxels whose fit is all zero) each get a rim of "edge", # where walkers end validly: a few are harmless, many cut every bundle short - from scipy import ndimage as ndi - holes = int((ndi.binary_fill_holes(mask) & ~mask).sum()) if holes > HOLE_WARN * mask.sum(): log.warning("%d voxels (%.1f%% of the fODF region) inside it have an all-zero fODF; each hole is " @@ -76,7 +74,12 @@ def tissue_labels(sh_img, pve_img, brain_mask_img=None): holes, 100 * holes / mask.sum()) elif holes: log.info("%d voxels inside the fODF region have an all-zero fODF", holes) - edge = find_boundaries(mask, mode="inner") & mask + try: + from skimage.segmentation import find_boundaries + + edge = find_boundaries(mask, mode="inner") & mask + except ImportError: + edge = mask & ~ndi.binary_erosion(mask, border_value=1) transient = mask & ~edge & (wm > WM_THRESHOLD) absorb = np.zeros(mask.shape, np.int8) absorb[mask & ~transient & (gm >= csf)] = 1 @@ -598,7 +601,9 @@ def _bytes(x): def run(afq, n_proc, max_mem="auto", bundles=None, moments=False, tol=1e-6, angle=35.0, double_odf=True, cores=True, viz=True, synthseg_thalamus=True, max_length=250.0, viz_rois=False, no_midline=(), midline_tol=None, out_dir=None, verbose=False, fornix=True, flux=False, - fixels=False): + fixels=False, ptt=False, step=1.0, stop_mass=None, fod_thresh=None, fod_power=None, + curv_sigma=None, probe_radius=None, sift2=False, arbor=False, arbor_branches=5, + save_transitions=False): """Segment pyAFQ's bundles with MPAT. afq ``ParticipantAFQ`` or ``GroupAFQ`` (every participant in turn) @@ -645,13 +650,34 @@ def run(afq, n_proc, max_mem="auto", bundles=None, moments=False, tol=1e-6, angl extra solve), the bundle's share of them (_share) and its share of the solved bundles' streamlines (_share_of_bundles). For fixel-based analysis without tractography. + ptt use Parallel Transport Tractography (PTT) defaults (fod_thresh=0.08, + fod_power=1.5, curv_sigma=18.0, probe_radius=0.5, stop_mass=1e-4) unless + explicitly overridden. + step hop length in voxels (of the smallest voxel side; default 1.0). + stop_mass MITTENS stopping regularizer tau (default 1e-4 if ptt else 0.0). + fod_thresh relative fODF floor (default 0.08 if ptt else 0.05). + fod_power fODF sharpening exponent p (default 1.5 if ptt else 1.0). + curv_sigma PTT parallel-transport curvature & co-circularity sigma in degrees (default + 18.0 if ptt else 0.0; 0 = flat cone). + probe_radius PTT cylindrical probe radius in voxels (default 0.5 if ptt else 0.0). + sift2 calibrate seed launch weights globally with path-consistent SIFT2 + (mpat.quantify.sift2_optimize_launches) before bundle segmentation. + arbor also extract and write 3-D multi-branch cross-section ridge arbors + (_bundle-_desc-arbor.{trx,json,tsv}) for each bundle. + arbor_branches maximum cortical endpoint branches per side for arbor extraction (default 5). + save_transitions persist transition probabilities: False/None (default), "odx" (or True) + for _desc-transitions_dwimap.odx, "nifti" for 4-D NIfTI + codi/coasy maps, + or "both". Returns {bundle: BundleResult} (a dict per participant for a GroupAFQ).""" import numba if hasattr(afq, "pAFQ_list"): kw = dict(cores=cores, viz=viz, synthseg_thalamus=synthseg_thalamus, max_length=max_length, viz_rois=viz_rois, no_midline=no_midline, midline_tol=midline_tol, - verbose=verbose, fornix=fornix, flux=flux, fixels=fixels) + verbose=verbose, fornix=fornix, flux=flux, fixels=fixels, ptt=ptt, step=step, + stop_mass=stop_mass, fod_thresh=fod_thresh, fod_power=fod_power, + curv_sigma=curv_sigma, probe_radius=probe_radius, sift2=sift2, arbor=arbor, + arbor_branches=arbor_branches, save_transitions=save_transitions) return {f"sub-{s}_ses-{t}": run(p, n_proc, max_mem, bundles, moments, tol, angle, double_odf, **kw, out_dir=out_dir and str(Path(out_dir) / f"sub-{s}" / f"ses-{t}")) for s, t, p in zip(afq.valid_sub_list, afq.valid_ses_list, afq.pAFQ_list)} @@ -677,7 +703,17 @@ def specs(): # (the solve keeps what it needs, so the ROIs can go) yield from roi_specs(afq, sh_img, transient, stem, bundles, thal, no_midline, midline_tol, fornix) - cfg = ChainConfig(angle=angle, double_odf=double_odf, moments=moments) + cfg = ChainConfig( + angle=angle, + step=step, + double_odf=double_odf, + moments=moments, + stop_mass=(1e-4 if ptt else 0.0) if stop_mass is None else float(stop_mass), + fod_thresh=(0.08 if ptt else 0.05) if fod_thresh is None else float(fod_thresh), + fod_power=(1.5 if ptt else 1.0) if fod_power is None else float(fod_power), + curv_sigma=(18.0 if ptt else 0.0) if curv_sigma is None else float(curv_sigma), + probe_radius=(0.5 if ptt else 0.0) if probe_radius is None else float(probe_radius), + ) with clock("fODF load"): sh = np.asarray(sh_img.dataobj, np.float32) with clock("chain build / cache"): @@ -686,9 +722,11 @@ def specs(): with clock("pyAFQ inputs"): seeds = np.argwhere((_on_grid(nib.load(afq.export("wm_gm_interface")), sh_img, 0) > 0) & transient) t_ol = time.perf_counter() + surv_state = None if max_length and max_length > 0: t1_ = time.time() kill, surv, T = overlength_states(chain, max_length, sh_img.header.get_zooms()[:3]) + surv_state = surv vox = surv.reshape(-1, chain.nb) nib.save(nib.Nifti1Image(chain.to_volume(vox.max(1)), sh_img.affine), f"{stem}_desc-overlength_map.nii.gz") chain.kill = kill if kill.any() else None @@ -714,15 +752,45 @@ def trapped(what, names, vol): budget = _budget(max_mem, chain, launches) from .fixels import segment_lobes - from .quantify import quantify_bundle + from .quantify import quantify_bundle, sift2_optimize_launches t_ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1 sh_rows = sh[tuple(t_ijk.T)] with clock("whole-brain reference & lobes"): lobes = segment_lobes(sh_rows, chain.geo) + if sift2 and not moments: + vox_vol = float(np.abs(np.linalg.det(sh_img.affine[:3, :3]))) + launches, s2_info = sift2_optimize_launches( + chain, launches, sh_rows, lobes=lobes, tol=max(tol, 1e-5), vox_vol_mm3=vox_vol + ) + log.info( + "SIFT2 launch optimization: fixel AFD R^2 %.3f -> %.3f (r=%.3f)", + s2_info["initial_fit"]["r2"], + s2_info["final_fit"]["r2"], + s2_info["final_fit"]["pearson_r"], + ) whole = segment_bundles(chain, [dict(name="whole brain")], launches, tol=tol, max_mem=budget, on_trapped=trapped)["whole brain"] + if save_transitions: + st_mode = "odx" if save_transitions is True else str(save_transitions).strip().lower() + with clock("save transitions"): + if st_mode in ("odx", "both"): + odx_out = f"{stem}_desc-transitions_dwimap.odx" + chain.save_odx( + odx_out, + affine=sh_img.affine, + sh_rows=sh_rows, + lobes=lobes, + launches=launches, + whole_dc=whole.density_class, + surv=surv_state, + ) + log.info("transitions ODX written to %s", odx_out) + if st_mode in ("nifti", "both"): + nii_paths = chain.save_nifti(stem, affine=sh_img.affine) + log.info("transitions NIfTI written to %s", nii_paths["transitions"]) + def write(res): name = re.sub(r"[^A-Za-z0-9]", "", res.name) b = f"{stem}_bundle-{name}" @@ -804,6 +872,10 @@ def write(res): from .core import write_cores with clock("cores"): write_cores(out) + if arbor: + from .branches import write_arbors + with clock("arbors"): + write_arbors(out, max_end_branches=int(arbor_branches), max_lateral_offshoots=int(arbor_branches) + 1) t_viz = time.perf_counter() if viz: try: diff --git a/src/mpat/branches.py b/src/mpat/branches.py new file mode 100644 index 0000000..eecd884 --- /dev/null +++ b/src/mpat/branches.py @@ -0,0 +1,1195 @@ +"""3-D branching arbors, deterministic reactive-flux flow lines (.trx), and iso-surfaces (.surf.gii). + +Why 2-D Maximum Intensity Projections (MIPs) of ``voxel_afd_t`` reveal sub-bundles and offshoots +that a single 1-D centerline (``bundle_core``) misses: +1. A white-matter pathway (such as ``ARC_L``, ``CST_L``, or ``CGC_R``) has a collimated deep trunk + that bifurcates into multiple cortical gyral patches and secondary laminar offshoots. +2. Unlike noisy Monte Carlo streamlines, MPAT's 26-neighbour reactive edge flux ``flux26(u, n)`` + defines a smooth, deterministic, bundle-conditioned 3-D vector field: + J_b(u) = sum_{n=0}^{25} F_b(u, n) * (o_n * zooms / ||o_n * zooms||) + whose integral curves (RK4 streamlines) follow the exact trunk, bifurcations, and offshoots + with zero sampling jitter. + +This module extracts three 3-D geometric representations for interactive visualization in TRXViz: +- ``extract_branch_arbor``: Multi-branch generalization of ``bundle_core`` that connects every + cortical endpoint patch and lateral cross-section density sub-peak smoothly into the main trunk. +- ``extract_flux_streamlines``: Deterministic RK4 flow lines of ``J_b(x)`` stratified across the + bundle's trunk, primary branches, and peripheral offshoots, carrying per-vertex (DPV) and + per-streamline (DPS) scalars and TRX groups. +- ``write_trx`` & ``write_isosurface_gifti``: Direct exporters to ``.trx`` and ``.surf.gii``. +""" +from __future__ import annotations + +import json +import zipfile +from dataclasses import dataclass, field +from typing import Dict, List, Optional, Tuple + +import nibabel as nib +import numpy as np +from scipy import ndimage as ndi +from scipy.sparse import csgraph + +from .core import OFFS, _anchor, _graph, _resample, bundle_core, split_ends +from .fields import endpoint_patches +from .geometry import OFFSETS + + +@dataclass +class BranchCurve: + """A single 3-D branch curve in the bundle's branching arbor.""" + branch_id: int + name: str + kind: str # "trunk", "start_branch", "end_branch", "lateral_offshoot" + xyz: np.ndarray # (N, 3) RAS+ world coordinates (mm) + afd: np.ndarray # (N,) sampled AFD density along the branch + q_harmonic: np.ndarray # (N,) harmonic coordinate in [0, 1] + coherence: np.ndarray # (N,) directional flux coherence in [0, 1] + k_eff: np.ndarray # (N,) effective branching degree in [1, 26] + share: float # relative weight / endpoint share of this branch + length_mm: float + + +@dataclass +class BranchArbor: + """Complete 3-D branching tree (trunk + cortical fan branches + lateral offshoots).""" + bundle_name: str + trunk: BranchCurve + branches: List[BranchCurve] = field(default_factory=list) + + +@dataclass +class FluxTractogram: + """Deterministic 3-D reactive-flux flow lines with DPV, DPS, and TRX groups.""" + streamlines: List[np.ndarray] # list of (N_i, 3) float32 RAS+ world coords + dpv: Dict[str, List[np.ndarray]] # per-vertex scalar arrays matching streamlines + dps: Dict[str, np.ndarray] # per-streamline scalar arrays (N_streamlines,) + groups: Dict[str, np.ndarray] # group_name -> uint32 streamline indices + affine: np.ndarray # (4, 4) voxel-to-RASMM affine + dimensions: Tuple[int, int, int] # (nx, ny, nz) + + +def _sample_trilinear(vol: np.ndarray, ijk: np.ndarray) -> np.ndarray: + """Sample a 3-D volume at fractional voxel coordinates ``ijk`` ((N, 3)).""" + return ndi.map_coordinates(np.asarray(vol, dtype=np.float64), ijk.T, order=1, mode="nearest") + + +def extract_branch_arbor( + afd_vol: np.ndarray, + endpoints_vol: np.ndarray, + affine: np.ndarray, + q_vol: Optional[np.ndarray] = None, + coherence_vol: Optional[np.ndarray] = None, + keff_vol: Optional[np.ndarray] = None, + start_mask: Optional[np.ndarray] = None, + end_mask: Optional[np.ndarray] = None, + bundle_name: str = "bundle", + max_end_branches: int = 6, + max_lateral_offshoots: int = 8, + min_branch_sep_mm: float = 7.0, + n_trunk_nodes: int = 100, + n_branch_nodes: int = 60, + smooth_vox: float = 1.3, +) -> BranchArbor: + """Extract the 3-D multi-branch ridge arbor of a bundle. + + 1. Solves the 2-pass cross-section ridge core (``bundle_core``) to get the primary trunk + and the cross-section normalized ridge graph ``G2`` where following any local ridge + incurred near-zero cost per mm. + 2. Segments the start and end endpoint distributions into distinct cortical patches + (``endpoint_patches`` + local maxima separated by >= ``min_branch_sep_mm``) and traces + each cortical patch along ``G2`` into the main trunk. + 3. Finds secondary 3-D local maxima of the AFD field that lie at least ``min_branch_sep_mm`` + away from the existing trunk/branches (capturing laminar offshoots and sub-fascicles + visible in the MIP) and traces their ridge paths back into the trunk. + """ + d = np.clip(np.nan_to_num(np.asarray(afd_vol, float)), 0.0, None) + ep = np.clip(np.nan_to_num(np.asarray(endpoints_vol, float)), 0.0, None) + if d.max() <= 0: + raise ValueError("Empty AFD/density volume") + + dn = d / d.max() + vox_mm = float(np.abs(np.linalg.det(affine[:3, :3])) ** (1.0 / 3.0)) + inv_aff = np.linalg.inv(affine) + + # 1. Main trunk via bundle_core + core = bundle_core( + d, affine, ep, start=start_mask, end=end_mask, n_nodes=n_trunk_nodes, smooth=smooth_vox + ) + + S_roi, E_roi, _ = split_ends(ep, affine, start_mask, end_mask) + keep = dn > 1e-5 + lab, _ = ndi.label(keep, np.ones((3, 3, 3))) + core_lab = lab[np.unravel_index(np.argmax(dn), dn.shape)] + keep = lab == core_lab + bod = keep & (dn >= 5e-3) + + s_vox = _anchor(ep, S_roi, bod, "centroid") + e_vox = _anchor(ep, E_roi, bod, "centroid") + + cost1 = np.where(keep, -np.log(np.where(keep, np.maximum(dn, 1e-12), 1.0)), 0.0) + G1, idx, lin = _graph(cost1, keep, vox_mm) + src = np.array([lin[tuple(s_vox)]]) + dst = np.array([lin[tuple(e_vox)]]) + + # Pass 1 path & cross-section ridge normalization + dist_s, pred_s, _ = csgraph.dijkstra(G1, indices=src, min_only=True, return_predecessors=True) + t_end = dst[0] + p0 = [t_end] + while pred_s[p0[-1]] >= 0: + p0.append(pred_s[p0[-1]]) + p0 = np.array(p0[::-1]) + + dist_cs, _, owner = csgraph.dijkstra(G1, indices=p0, min_only=True, return_predecessors=True) + dv = d[tuple(idx.T)] + ok = np.isfinite(dist_cs) + mx = np.zeros(len(idx)) + np.maximum.at(mx, owner[ok], dv[ok]) + rel = np.zeros(len(idx)) + rel[ok] = dv[ok] / np.maximum(mx[owner[ok]], 1e-300) + + # Slight penalty off the trunk so secondary branches merge smoothly into the trunk ridge + cost2 = np.zeros(d.shape) + cost2[tuple(idx.T)] = np.where(ok, -np.log(np.maximum(rel, 1e-6)), 50.0) + G2, idx2, lin2 = _graph(cost2, keep, vox_mm) + + # Reconstruct trunk voxel indices in G2 + dist_trunk, pred_trunk, _ = csgraph.dijkstra( + G2, indices=np.array([lin2[tuple(s_vox)]]), min_only=True, return_predecessors=True + ) + p_trunk = [lin2[tuple(e_vox)]] + while pred_trunk[p_trunk[-1]] >= 0: + p_trunk.append(pred_trunk[p_trunk[-1]]) + p_trunk = np.array(p_trunk[::-1]) + + # Multi-source Dijkstra from the entire trunk on G2: any branch target voxel can trace its + # minimum-ridge-cost path straight into the nearest point on the trunk! + dist_to_trunk, pred_to_trunk, trunk_owner = csgraph.dijkstra( + G2, indices=p_trunk, min_only=True, return_predecessors=True + ) + + def _make_branch_curve(xyz_pts: np.ndarray, bid: int, name: str, kind: str, share: float) -> BranchCurve: + ijk_pts = nib.affines.apply_affine(inv_aff, xyz_pts) + afd_s = _sample_trilinear(d, ijk_pts) + q_s = ( + _sample_trilinear(q_vol, ijk_pts) + if q_vol is not None + else np.linspace(0.0, 1.0, len(xyz_pts)) + ) + coh_s = ( + _sample_trilinear(coherence_vol, ijk_pts) + if coherence_vol is not None + else np.full(len(xyz_pts), 0.7) + ) + keff_s = ( + _sample_trilinear(keff_vol, ijk_pts) + if keff_vol is not None + else np.full(len(xyz_pts), 6.0) + ) + # Orient curve from smaller q_harmonic to larger q_harmonic + if q_s[0] > q_s[-1]: + xyz_pts = xyz_pts[::-1].copy() + afd_s = afd_s[::-1].copy() + q_s = q_s[::-1].copy() + coh_s = coh_s[::-1].copy() + keff_s = keff_s[::-1].copy() + seg_len = float(np.linalg.norm(np.diff(xyz_pts, axis=0), axis=1).sum()) + return BranchCurve( + branch_id=bid, + name=name, + kind=kind, + xyz=xyz_pts, + afd=afd_s, + q_harmonic=q_s, + coherence=coh_s, + k_eff=keff_s, + share=float(share), + length_mm=seg_len, + ) + + trunk_curve = _make_branch_curve(core.xyz, 0, f"{bundle_name}_Trunk", "trunk", 1.0) + branches: List[BranchCurve] = [trunk_curve] + covered_xyz = [core.xyz] + + def _is_well_separated(cand_xyz: np.ndarray, min_dist: float) -> bool: + all_cov = np.vstack(covered_xyz) + dists = np.linalg.norm(all_cov - cand_xyz[None, :], axis=1) + return float(dists.min()) >= min_dist + + def _trace_voxel_to_trunk(target_ijk: np.ndarray, n_pts: int) -> Optional[np.ndarray]: + u = int(lin2[tuple(target_ijk)]) + if u < 0 or not np.isfinite(dist_to_trunk[u]): + return None + path_nodes = [u] + while pred_to_trunk[path_nodes[-1]] >= 0: + path_nodes.append(int(pred_to_trunk[path_nodes[-1]])) + # Also include 4 nodes along the trunk from the junction for a seamless visual Y-junction + junc = path_nodes[-1] + pos_in_trunk = np.flatnonzero(p_trunk == junc) + if len(pos_in_trunk) > 0: + ti = int(pos_in_trunk[0]) + center_ti = len(p_trunk) // 2 + step_dir = 1 if ti < center_ti else -1 + for k in range(1, 6): + tk = ti + k * step_dir + if 0 <= tk < len(p_trunk): + path_nodes.append(int(p_trunk[tk])) + if len(path_nodes) < 4: + return None + vox_coords = idx2[np.array(path_nodes)].astype(float) + xyz_raw = nib.affines.apply_affine(affine, vox_coords) + if smooth_vox and len(xyz_raw) > 3: + xyz_raw = ndi.gaussian_filter1d(xyz_raw, smooth_vox, axis=0, mode="nearest") + return _resample(xyz_raw, n_pts) + + # 2. Cortical fan branches at Start and End ROIs + cand_vox = np.argwhere(bod) + bid_counter = 1 + for side_mask, side_kind, side_prefix in ( + (S_roi, "start_branch", "StartFan"), + (E_roi, "end_branch", "EndFan"), + ): + ep_side = np.where(side_mask, ep, 0.0) + if ep_side.sum() <= 0: + continue + labels, shares = endpoint_patches(ep_side, sigma_vox=1.8, min_share=0.03, prominence=0.15) + # Also add local maxima of smoothed endpoint density so multi-gyral fans are captured + blur_ep = ndi.gaussian_filter(ep_side, 1.5) + local_max = (blur_ep == ndi.maximum_filter(blur_ep, size=5)) & (blur_ep > 0.05 * blur_ep.max()) + peak_ijks = np.argwhere(local_max) + peak_vals = blur_ep[tuple(peak_ijks.T)] if len(peak_ijks) else np.array([]) + order = np.argsort(-peak_vals) + + anchors_ijk = [] + anchor_shares = [] + for p_idx in range(1, len(shares) + 1): + patch_mask = labels == p_idx + a_ijk = _anchor(ep_side, patch_mask, bod, "mode") + anchors_ijk.append(a_ijk) + anchor_shares.append(shares[p_idx - 1]) + for oi in order: + p_ijk = peak_ijks[oi] + nearest_bod = cand_vox[np.argmin(((cand_vox - p_ijk) ** 2).sum(1))] + anchors_ijk.append(nearest_bod) + anchor_shares.append(float(peak_vals[oi] / max(blur_ep.sum(), 1e-12))) + + added_side = 0 + for a_ijk, sh in zip(anchors_ijk, anchor_shares): + if added_side >= max_end_branches: + break + a_xyz = nib.affines.apply_affine(affine, a_ijk.astype(float)) + if not _is_well_separated(a_xyz, min_branch_sep_mm): + continue + curve_xyz = _trace_voxel_to_trunk(a_ijk, n_branch_nodes) + if curve_xyz is None: + continue + b_curve = _make_branch_curve( + curve_xyz, bid_counter, f"{bundle_name}_{side_prefix}_{added_side + 1}", side_kind, sh + ) + if b_curve.length_mm >= min_branch_sep_mm: + branches.append(b_curve) + covered_xyz.append(curve_xyz) + bid_counter += 1 + added_side += 1 + + # 3. Secondary lateral offshoots (3-D ridges of AFD density away from covered branches) + blur_d = ndi.gaussian_filter(dn, 1.2) + loc_peaks = ( + (blur_d == ndi.maximum_filter(blur_d, size=5)) + & keep + & (blur_d >= 0.025) + ) + pk_ijks = np.argwhere(loc_peaks) + if len(pk_ijks) > 0: + pk_scores = blur_d[tuple(pk_ijks.T)] + for oi in np.argsort(-pk_scores): + if len([b for b in branches if b.kind == "lateral_offshoot"]) >= max_lateral_offshoots: + break + p_ijk = pk_ijks[oi] + p_xyz = nib.affines.apply_affine(affine, p_ijk.astype(float)) + if not _is_well_separated(p_xyz, min_branch_sep_mm * 1.15): + continue + curve_xyz = _trace_voxel_to_trunk(p_ijk, n_branch_nodes) + if curve_xyz is None: + continue + off_idx = len([b for b in branches if b.kind == "lateral_offshoot"]) + 1 + b_curve = _make_branch_curve( + curve_xyz, + bid_counter, + f"{bundle_name}_Offshoot_{off_idx}", + "lateral_offshoot", + float(pk_scores[oi]), + ) + if b_curve.length_mm >= min_branch_sep_mm: + branches.append(b_curve) + covered_xyz.append(curve_xyz) + bid_counter += 1 + + return BranchArbor(bundle_name=bundle_name, trunk=trunk_curve, branches=branches) + + +def extract_flux_streamlines( + chain: object, + flux26: np.ndarray, + afd_vol: np.ndarray, + affine: np.ndarray, + q_vol: Optional[np.ndarray] = None, + coherence_vol: Optional[np.ndarray] = None, + keff_vol: Optional[np.ndarray] = None, + sift2_afd_vol: Optional[np.ndarray] = None, + arbor: Optional[BranchArbor] = None, + n_streamlines: int = 800, + step_mm: float = 0.85, + max_steps: int = 260, + min_length_mm: float = 18.0, + afd_mass_fraction: float = 0.96, +) -> FluxTractogram: + """Integrate deterministic 3-D flow lines through the bundle's reactive flux field J_b(x). + + Every streamline is a smooth RK4 integral curve of the exact Markov reactive flux vector + field (with zero Monte Carlo sampling noise), stratified across the dense trunk, primary + cortical branches, and fine peripheral offshoots. + """ + shape = chain.shape + zooms = np.sqrt((affine[:3, :3] ** 2).sum(0)) + inv_aff = np.linalg.inv(affine) + + # 1. Build 3-D vector field V_ijk (in voxel-index velocity units) from 26-neighbour flux26 + f_pos = np.maximum(np.asarray(flux26, dtype=np.float64), 0.0) + # Net flux vector in voxel-offset coordinates + unit_offs_vox = OFFSETS / np.linalg.norm(OFFSETS * zooms[None, :], axis=1, keepdims=True) + vec_t = f_pos @ unit_offs_vox # (Nt, 3) + + # Also add harmonic gradient fallback where net vector cancels or near absorbing boundaries + if q_vol is not None: + gq = np.stack(np.gradient(np.asarray(q_vol, dtype=np.float64)), axis=-1) + # Extract transient voxels using chain.to_volume inverse (padded transient mask) + pad_t = np.zeros(chain.pshape, dtype=bool) + pad_t.ravel()[chain.t_lin] = True + t_mask = pad_t[1:-1, 1:-1, 1:-1] + gq_t = gq[t_mask] + v_norm = np.linalg.norm(vec_t, axis=1, keepdims=True) + g_norm = np.linalg.norm(gq_t, axis=1, keepdims=True) + use_g = (v_norm[:, 0] <= 1e-12) & (g_norm[:, 0] > 1e-12) + vec_t[use_g] = gq_t[use_g] + + vec_vol = np.zeros(shape + (3,), dtype=np.float64) + for d_ax in range(3): + vol_d = chain.to_volume(vec_t[:, d_ax], "transient").astype(np.float64) + # Slight Gaussian smoothing (0.55 vox) gives C^1 sub-voxel streamlines while preserving branches + vec_vol[..., d_ax] = ndi.gaussian_filter(vol_d, 0.55) + + v_mag_vol = np.linalg.norm(vec_vol, axis=-1) + unit_vec_vol = np.divide( + vec_vol, v_mag_vol[..., None], out=np.zeros_like(vec_vol), where=v_mag_vol[..., None] > 1e-12 + ) + + afd_clean = np.clip(np.nan_to_num(np.asarray(afd_vol, dtype=np.float64)), 0.0, None) + peak_afd = float(afd_clean.max()) + if peak_afd <= 0: + raise ValueError("Empty AFD volume in extract_flux_streamlines") + + # Determine support threshold enclosing afd_mass_fraction (e.g. 96% of total AFD mass) + nz_vals = np.sort(afd_clean[afd_clean > 0])[::-1] + csum = np.cumsum(nz_vals) + cutoff_idx = min(int(np.searchsorted(csum, afd_mass_fraction * csum[-1])), len(nz_vals) - 1) + afd_floor = max(float(nz_vals[cutoff_idx]) * 0.35, peak_afd * 1e-3) + support_mask = (afd_clean >= afd_floor) & (v_mag_vol > 0) + + # 2. Select stratified deterministic seed points (ridge peaks + offshoots + weighted grid) + cand_ijk = np.argwhere(support_mask) + cand_afd = afd_clean[tuple(cand_ijk.T)] + # Weight by afd^0.55 so peripheral offshoots and branches are well-represented alongside the trunk + weights = cand_afd ** 0.55 + order = np.argsort(-weights) + + # Stratified sub-voxel jittered seeds with minimum spacing so lines fill the 3-D volume cleanly + seeds_ijk: List[np.ndarray] = [] + if arbor is not None: + for b in arbor.branches: + b_ijk = nib.affines.apply_affine(inv_aff, b.xyz) + for pt in b_ijk[::3]: + seeds_ijk.append(pt) + + # Add deterministic Halton-like offsets around top voxels across the support + offsets_sub = np.array( + [ + [0.0, 0.0, 0.0], + [0.32, -0.25, 0.18], + [-0.28, 0.30, -0.22], + [0.20, 0.28, -0.30], + [-0.25, -0.22, 0.28], + ] + ) + stride = max(1, len(order) // max(n_streamlines // 2, 1)) + for sub in offsets_sub: + for idx_o in order[::stride]: + if len(seeds_ijk) >= n_streamlines * 2: + break + seeds_ijk.append(cand_ijk[idx_o].astype(np.float64) + sub) + if len(seeds_ijk) >= n_streamlines * 2: + break + + step_vox = float(step_mm / np.mean(zooms)) + + def _vel_at(pt_ijk: np.ndarray) -> np.ndarray: + if np.any(pt_ijk < 1) or np.any(pt_ijk >= np.array(shape) - 2): + return np.zeros(3) + ix, iy, iz = int(round(pt_ijk[0])), int(round(pt_ijk[1])), int(round(pt_ijk[2])) + if not support_mask[ix, iy, iz]: + return np.zeros(3) + # Fast trilinear lookup on unit_vec_vol + x0, y0, z0 = int(np.floor(pt_ijk[0])), int(np.floor(pt_ijk[1])), int(np.floor(pt_ijk[2])) + xd, yd, zd = pt_ijk[0] - x0, pt_ijk[1] - y0, pt_ijk[2] - z0 + c00 = unit_vec_vol[x0, y0, z0] * (1 - xd) + unit_vec_vol[x0 + 1, y0, z0] * xd + c01 = unit_vec_vol[x0, y0, z0 + 1] * (1 - xd) + unit_vec_vol[x0 + 1, y0, z0 + 1] * xd + c10 = unit_vec_vol[x0, y0 + 1, z0] * (1 - xd) + unit_vec_vol[x0 + 1, y0 + 1, z0] * xd + c11 = unit_vec_vol[x0, y0 + 1, z0 + 1] * (1 - xd) + unit_vec_vol[x0 + 1, y0 + 1, z0 + 1] * xd + c0 = c00 * (1 - yd) + c10 * yd + c1 = c01 * (1 - yd) + c11 * yd + v = c0 * (1 - zd) + c1 * zd + nrm = float(np.linalg.norm(v)) + return v / nrm if nrm > 1e-6 else np.zeros(3) + + def _integrate_half(start_ijk: np.ndarray, sign: float) -> List[np.ndarray]: + pts = [start_ijk.copy()] + cur = start_ijk.copy() + prev_dir = None + for _ in range(max_steps): + k1 = sign * _vel_at(cur) + if np.linalg.norm(k1) < 1e-6: + break + if prev_dir is not None and float(np.dot(k1, prev_dir)) < 0.35: + break + k2 = sign * _vel_at(cur + 0.5 * step_vox * k1) + if np.linalg.norm(k2) < 1e-6: + break + k3 = sign * _vel_at(cur + 0.5 * step_vox * k2) + k4 = sign * _vel_at(cur + step_vox * k3) + step_vec = (k1 + 2.0 * k2 + 2.0 * k3 + k4) / 6.0 + nrm = float(np.linalg.norm(step_vec)) + if nrm < 1e-6: + break + step_dir = step_vec / nrm + nxt = cur + step_vox * step_dir + pts.append(nxt) + prev_dir = step_dir + cur = nxt + return pts + + raw_streamlines_xyz: List[np.ndarray] = [] + is_arbor_flag: List[int] = [] + branch_id_list: List[int] = [] + + # First include the exact BranchArbor ridge curves as hero streamlines + if arbor is not None: + for b in arbor.branches: + raw_streamlines_xyz.append(b.xyz.astype(np.float32)) + is_arbor_flag.append(1) + branch_id_list.append(int(b.branch_id)) + + # Integrate deterministic RK4 flux streamlines + for s_ijk in seeds_ijk: + if len(raw_streamlines_xyz) >= n_streamlines: + break + bwd = _integrate_half(s_ijk, -1.0)[::-1] + fwd = _integrate_half(s_ijk, +1.0)[1:] + full_ijk = np.array(bwd + fwd, dtype=np.float64) + if len(full_ijk) < 6: + continue + xyz = nib.affines.apply_affine(affine, full_ijk) + seg_len = float(np.linalg.norm(np.diff(xyz, axis=0), axis=1).sum()) + if seg_len < min_length_mm: + continue + # Assign to nearest branch in arbor if available + b_id = 0 + if arbor is not None and len(arbor.branches) > 1: + mid_pt = xyz[len(xyz) // 2] + end_pt1, end_pt2 = xyz[0], xyz[-1] + best_d = 1e30 + for b in arbor.branches: + d_min = min( + float(np.linalg.norm(b.xyz - mid_pt[None, :], axis=1).min()), + float(np.linalg.norm(b.xyz - end_pt1[None, :], axis=1).min()), + float(np.linalg.norm(b.xyz - end_pt2[None, :], axis=1).min()), + ) + if d_min < best_d: + best_d = d_min + b_id = b.branch_id + raw_streamlines_xyz.append(xyz.astype(np.float32)) + is_arbor_flag.append(0) + branch_id_list.append(int(b_id)) + + # 3. Compute DPV and DPS scalars and TRX groups + dpv_afd: List[np.ndarray] = [] + dpv_sift2: List[np.ndarray] = [] + dpv_q: List[np.ndarray] = [] + dpv_coh: List[np.ndarray] = [] + dpv_keff: List[np.ndarray] = [] + dpv_flux: List[np.ndarray] = [] + + dps_mean_afd = np.zeros(len(raw_streamlines_xyz), dtype=np.float32) + dps_peak_afd = np.zeros(len(raw_streamlines_xyz), dtype=np.float32) + dps_length = np.zeros(len(raw_streamlines_xyz), dtype=np.float32) + dps_branch_id = np.array(branch_id_list, dtype=np.float32) + dps_is_arbor = np.array(is_arbor_flag, dtype=np.float32) + + sift2_src = sift2_afd_vol if sift2_afd_vol is not None else afd_clean + + for i, xyz in enumerate(raw_streamlines_xyz): + ijk = nib.affines.apply_affine(inv_aff, xyz.astype(np.float64)) + v_afd = _sample_trilinear(afd_clean, ijk).astype(np.float32) + v_sift2 = _sample_trilinear(sift2_src, ijk).astype(np.float32) + v_q = ( + _sample_trilinear(q_vol, ijk).astype(np.float32) + if q_vol is not None + else np.linspace(0.0, 1.0, len(xyz), dtype=np.float32) + ) + v_coh = ( + _sample_trilinear(coherence_vol, ijk).astype(np.float32) + if coherence_vol is not None + else np.full(len(xyz), 0.7, dtype=np.float32) + ) + v_keff = ( + _sample_trilinear(keff_vol, ijk).astype(np.float32) + if keff_vol is not None + else np.full(len(xyz), 6.0, dtype=np.float32) + ) + v_flx = _sample_trilinear(v_mag_vol, ijk).astype(np.float32) + + dpv_afd.append(v_afd) + dpv_sift2.append(v_sift2) + dpv_q.append(v_q) + dpv_coh.append(v_coh) + dpv_keff.append(v_keff) + dpv_flux.append(v_flx) + + dps_mean_afd[i] = float(np.mean(v_afd)) + dps_peak_afd[i] = float(np.max(v_afd)) + dps_length[i] = float(np.linalg.norm(np.diff(xyz, axis=0), axis=1).sum()) + + # Organize into TRX groups so user can toggle trunk, branches, and offshoot tiers in TRXViz + q65 = float(np.quantile(dps_mean_afd, 0.65)) if len(dps_mean_afd) else 0.0 + q25 = float(np.quantile(dps_mean_afd, 0.25)) if len(dps_mean_afd) else 0.0 + + groups: Dict[str, np.ndarray] = { + "00_Branch_Arbor_Ridges": np.flatnonzero(dps_is_arbor > 0.5).astype(np.uint32), + "01_Dense_Trunk_Core": np.flatnonzero((dps_is_arbor == 0) & (dps_mean_afd >= q65)).astype(np.uint32), + "02_Primary_Branches": np.flatnonzero( + (dps_is_arbor == 0) & (dps_mean_afd >= q25) & (dps_mean_afd < q65) + ).astype(np.uint32), + "03_Fine_Offshoots": np.flatnonzero((dps_is_arbor == 0) & (dps_mean_afd < q25)).astype(np.uint32), + } + if arbor is not None: + for b in arbor.branches: + members = np.flatnonzero(dps_branch_id == b.branch_id).astype(np.uint32) + if len(members) > 0: + groups[f"Branch_{b.branch_id:02d}_{b.name}"] = members + + return FluxTractogram( + streamlines=raw_streamlines_xyz, + dpv={ + "afd": dpv_afd, + "sift2_afd": dpv_sift2, + "q_harmonic": dpv_q, + "coherence": dpv_coh, + "k_eff": dpv_keff, + "flux_magnitude": dpv_flux, + }, + dps={ + "mean_afd": dps_mean_afd, + "peak_afd": dps_peak_afd, + "length_mm": dps_length, + "branch_id": dps_branch_id, + "is_arbor_ridge": dps_is_arbor, + }, + groups=groups, + affine=np.asarray(affine, dtype=np.float64), + dimensions=(int(shape[0]), int(shape[1]), int(shape[2])), + ) + + +def write_trx(tractogram: FluxTractogram, out_path: str) -> str: + """Write a ``FluxTractogram`` to a standard ``.trx`` archive compatible with ``trx-rs`` / TRXViz.""" + n_streamlines = len(tractogram.streamlines) + lengths = np.array([len(s) for s in tractogram.streamlines], dtype=np.uint64) + offsets = np.zeros(n_streamlines + 1, dtype=np.uint64) + offsets[1:] = np.cumsum(lengths) + n_vertices = int(offsets[-1]) + + positions = ( + np.vstack(tractogram.streamlines).astype(" 0 + else np.zeros((0, 3), dtype=" 0 + else np.zeros(0, dtype=" Tuple[str, str, str]: + """Write ``_desc-arbor_path.tsv``, ``_desc-arbor.trx``, and + ``_desc-arbor.json`` for a :class:`BranchArbor`. + """ + tsv = f"{prefix}_desc-arbor_path.tsv" + with open(tsv, "w") as fh: + fh.write("branch_id\tbranch_name\tkind\tnode\tx_mm\ty_mm\tz_mm\tafd\tq_harmonic\tcoherence\tk_eff\n") + for b in arbor.branches: + for i in range(len(b.xyz)): + p = b.xyz[i] + fh.write( + f"{b.branch_id}\t{b.name}\t{b.kind}\t{i}\t" + f"{p[0]:.3f}\t{p[1]:.3f}\t{p[2]:.3f}\t" + f"{b.afd[i]:.6g}\t{b.q_harmonic[i]:.6g}\t{b.coherence[i]:.6g}\t{b.k_eff[i]:.6g}\n" + ) + + streamlines = [b.xyz.astype(np.float32) for b in arbor.branches] + dpv = { + "afd": [b.afd.astype(np.float32) for b in arbor.branches], + "q_harmonic": [b.q_harmonic.astype(np.float32) for b in arbor.branches], + "coherence": [b.coherence.astype(np.float32) for b in arbor.branches], + "k_eff": [b.k_eff.astype(np.float32) for b in arbor.branches], + } + dps = { + "branch_id": np.array([b.branch_id for b in arbor.branches], dtype=np.float32), + "share": np.array([b.share for b in arbor.branches], dtype=np.float32), + "length_mm": np.array([b.length_mm for b in arbor.branches], dtype=np.float32), + } + groups = { + f"Branch_{b.branch_id:02d}_{b.name}": np.array([idx], dtype=np.uint32) + for idx, b in enumerate(arbor.branches) + } + tractogram = FluxTractogram( + streamlines=streamlines, + dpv=dpv, + dps=dps, + groups=groups, + affine=np.asarray(ref.affine, dtype=np.float64), + dimensions=tuple(int(d) for d in ref.shape[:3]), + ) + trx = f"{prefix}_desc-arbor.trx" + write_trx(tractogram, trx) + + js = f"{prefix}_desc-arbor.json" + summary = { + "method": "3-D multi-branch cross-section ridge arbor (mpat.branches)", + "bundle": arbor.bundle_name, + "n_branches": len(arbor.branches), + "trunk_length_mm": round(float(arbor.trunk.length_mm), 1), + "total_arbor_length_mm": round(float(sum(b.length_mm for b in arbor.branches)), 1), + "branches": [ + { + "branch_id": int(b.branch_id), + "name": b.name, + "kind": b.kind, + "n_nodes": int(len(b.xyz)), + "length_mm": round(float(b.length_mm), 1), + "share": round(float(b.share), 4), + } + for b in arbor.branches + ], + **(extra or {}), + } + with open(js, "w") as fh: + json.dump(summary, fh, indent=1) + return tsv, trx, js + + +def write_arbors(folder: str, max_end_branches: int = 5, max_lateral_offshoots: int = 6) -> None: + """Compute and save the 3-D multi-branch arbor of every bundle under ``folder``.""" + import logging + from .core import bundle_files + + log = logging.getLogger("mpat") + for name, f in bundle_files(folder).items(): + if f["endpoints"] is None: + continue + dens_path = f.get("afd") or f["density"] + img = nib.load(dens_path) + load_mask = lambda k: (np.asarray(nib.load(f[k]).dataobj) > 0) if f.get(k) else None # noqa: E731 + load_vol = lambda k: np.asarray(nib.load(f[k]).dataobj, dtype=np.float32) if f.get(k) else None # noqa: E731 + try: + arbor = extract_branch_arbor( + np.asarray(img.dataobj, dtype=np.float32), + np.asarray(nib.load(f["endpoints"]).dataobj, dtype=np.float32), + img.affine, + q_vol=load_vol("qharmonic"), + coherence_vol=load_vol("coherence"), + keff_vol=load_vol("keff"), + start_mask=load_mask("start"), + end_mask=load_mask("end"), + bundle_name=name, + max_end_branches=max_end_branches, + max_lateral_offshoots=max_lateral_offshoots, + ) + except ValueError as err: + log.warning("%s: no arbor (%s)", name, err) + continue + write_arbor(arbor, f["prefix"], img) + log.info( + "arbor %-24s %d branches, trunk %4.0f mm, total %4.0f mm", + name, + len(arbor.branches), + arbor.trunk.length_mm, + sum(b.length_mm for b in arbor.branches), + ) + + +def _taubin_smooth_mesh( + verts: np.ndarray, faces: np.ndarray, n_iters: int = 10, lam: float = 0.5, mu: float = -0.53 +) -> np.ndarray: + """Shrink-free Taubin Laplacian mesh smoothing for organic 3-D branch iso-surfaces.""" + v = verts.copy().astype(np.float64) + n_v = len(v) + if n_v == 0 or len(faces) == 0: + return v.astype(np.float32) + + edges_a = np.concatenate([faces[:, 0], faces[:, 1], faces[:, 2]]) + edges_b = np.concatenate([faces[:, 1], faces[:, 2], faces[:, 0]]) + src = np.concatenate([edges_a, edges_b]) + dst = np.concatenate([edges_b, edges_a]) + deg = np.bincount(src, minlength=n_v).astype(np.float64) + deg_safe = np.maximum(deg, 1.0)[:, None] + + for _ in range(n_iters): + for step_w in (lam, mu): + nb_sum = np.zeros_like(v) + np.add.at(nb_sum, src, v[dst]) + lap = (nb_sum / deg_safe) - v + v = v + step_w * lap + return v.astype(np.float32) + + +def write_isosurface_gifti( + afd_vol: np.ndarray, + affine: np.ndarray, + out_surf_path: str, + mass_fraction: float = 0.85, + scalar_vol: Optional[np.ndarray] = None, + out_func_path: Optional[str] = None, + smooth_sigma: float = 0.65, + taubin_iters: int = 10, +) -> Tuple[np.ndarray, np.ndarray]: + """Extract a 3-D iso-surface shell enclosing ``mass_fraction`` of the bundle's AFD mass + and save it as a GIFTI ``.surf.gii`` mesh (with optional ``.func.gii`` vertex scalars) + for interactive 3-D rendering in TRXViz. + """ + from skimage.measure import marching_cubes + + vol = np.clip(np.nan_to_num(np.asarray(afd_vol, dtype=np.float64)), 0.0, None) + if smooth_sigma > 0: + vol = ndi.gaussian_filter(vol, smooth_sigma) + nz = np.sort(vol[vol > 0])[::-1] + if len(nz) == 0: + raise ValueError("Empty volume for iso-surface") + cs = np.cumsum(nz) + idx = min(int(np.searchsorted(cs, mass_fraction * cs[-1])), len(nz) - 1) + level = max(float(nz[idx]), float(vol.max()) * 1e-3) + + verts_ijk, faces, _, _ = marching_cubes(vol, level=level) + verts_ras = nib.affines.apply_affine(affine, verts_ijk).astype(np.float32) + verts_smooth = _taubin_smooth_mesh(verts_ras, faces, n_iters=taubin_iters) + + # Ensure outward-pointing triangle winding when det(affine) < 0 + if np.linalg.det(affine[:3, :3]) < 0: + faces = faces[:, [0, 2, 1]] + + da_coords = nib.gifti.GiftiDataArray( + data=verts_smooth.astype(np.float32), + intent="NIFTI_INTENT_POINTSET", + datatype="NIFTI_TYPE_FLOAT32", + ) + da_faces = nib.gifti.GiftiDataArray( + data=faces.astype(np.int32), + intent="NIFTI_INTENT_TRIANGLE", + datatype="NIFTI_TYPE_INT32", + ) + gii_surf = nib.gifti.GiftiImage(darrays=[da_coords, da_faces]) + nib.save(gii_surf, out_surf_path) + + if scalar_vol is not None and out_func_path is not None: + inv_aff = np.linalg.inv(affine) + v_ijk = nib.affines.apply_affine(inv_aff, verts_smooth) + vals = _sample_trilinear(scalar_vol, v_ijk).astype(np.float32) + da_val = nib.gifti.GiftiDataArray( + data=vals, + intent="NIFTI_INTENT_SHAPE", + datatype="NIFTI_TYPE_FLOAT32", + ) + nib.save(nib.gifti.GiftiImage(darrays=[da_val]), out_func_path) + + return verts_smooth, faces.astype(np.int32) + + +def write_trxviz_project( + out_project_path: str, + bundle_nifti_path: str, + trx_path: Optional[str] = None, + t1w_nifti_path: Optional[str] = None, + surface_shells: Optional[List[dict]] = None, + bundle_surface: bool = False, + bundle_surface_voxel_size_mm: float = 1.6, + bundle_surface_threshold: float = 0.8, + bundle_surface_smooth_sigma: float = 1.1, + bundle_surface_opacity: float = 0.22, + bundle_surface_outline_thickness: float = 2.5, + bundle_surface_color_mode: str = "SourceColors", + render_3d_mode: str = "Mip", + colormap: str = "Inferno", + vol_opacity: float = 0.82, + window_center: float = 0.22, + window_width: float = 0.44, + t1w_render_3d_mode: str = "Off", + t1w_opacity: float = 1.0, + slice_visible: Optional[List[bool]] = None, + slice_positions_ras: Optional[List[float]] = None, + dpv_field: str = "q_harmonic", + streamline_colormap: str = "Viridis", + tube_radius_mm: float = 0.55, + camera_target: Optional[List[float]] = None, + azimuth_deg: float = -68.0, + elevation_deg: float = 20.0, + distance: float = 172.0, +) -> str: + """Write a ``.trxviz`` workflow project file combining 3-D GPU volume rendering + (``Mip`` or ``DirectVolume``), 3-D ``.trx`` branch arbor tubes, translucent + cross-sectional surfaces (GIFTI iso-shells and/or ``BundleSurfaceBuild``), and + an optional background ``T1w`` anatomical volume with slice contour lines. + """ + if camera_target is None: + camera_target = [-32.0, -18.0, 14.0] + if slice_visible is None: + slice_visible = [True, True, True] if t1w_nifti_path else [False, False, False] + if slice_positions_ras is None: + slice_positions_ras = [2.0, -28.0, -32.0] + + nodes = {} + wires = [] + assets = [] + next_asset_id = 1 + next_node_id = 1 + + # 1. Optional background T1w volume + if t1w_nifti_path is not None: + t1_asset_id = next_asset_id + next_asset_id += 1 + assets.append({"Volume": {"id": t1_asset_id, "path": str(t1w_nifti_path)}}) + n_src = next_node_id + n_disp = next_node_id + 1 + next_node_id += 2 + nodes[str(n_src)] = { + "node": { + "uuid": n_src, + "op": {"VolumeSource": {"source_id": t1_asset_id}}, + "label": "T1w Source", + }, + "pos": {"x": 40.0, "y": 40.0}, + } + nodes[str(n_disp)] = { + "node": { + "uuid": n_disp, + "op": { + "VolumeDisplay": { + "colormap": "Grayscale", + "opacity": float(t1w_opacity), + "window_center": 0.52, + "window_width": 0.92, + "render_3d_mode": t1w_render_3d_mode, + } + }, + "label": "T1w Display", + }, + "pos": {"x": 320.0, "y": 40.0}, + } + wires.append({"from": {"node": n_src, "output": 0}, "to": {"node": n_disp, "input": 0}}) + + # 2. Bundle 3D Volume (MIP or DirectVolume) + b_asset_id = next_asset_id + next_asset_id += 1 + assets.append({"Volume": {"id": b_asset_id, "path": str(bundle_nifti_path)}}) + n_bsrc = next_node_id + n_bdisp = next_node_id + 1 + next_node_id += 2 + nodes[str(n_bsrc)] = { + "node": { + "uuid": n_bsrc, + "op": {"VolumeSource": {"source_id": b_asset_id}}, + "label": "Bundle Volume Source", + }, + "pos": {"x": 40.0, "y": 200.0}, + } + nodes[str(n_bdisp)] = { + "node": { + "uuid": n_bdisp, + "op": { + "VolumeDisplay": { + "colormap": colormap, + "opacity": float(vol_opacity), + "window_center": float(window_center), + "window_width": float(window_width), + "render_3d_mode": render_3d_mode, + } + }, + "label": "Bundle 3D Volume Display", + }, + "pos": {"x": 320.0, "y": 200.0}, + } + wires.append({"from": {"node": n_bsrc, "output": 0}, "to": {"node": n_bdisp, "input": 0}}) + + # 3. Optional 3-D Branch Arbor / Flux Streamlines (.trx) + optional BundleSurfaceBuild + if trx_path is not None: + s_asset_id = next_asset_id + next_asset_id += 1 + assets.append({"Streamlines": {"id": s_asset_id, "path": str(trx_path), "imported": False}}) + n_ssrc = next_node_id + n_scol = next_node_id + 1 + n_sdisp = next_node_id + 2 + next_node_id += 3 + nodes[str(n_ssrc)] = { + "node": { + "uuid": n_ssrc, + "op": {"StreamlineSource": {"source_id": s_asset_id}}, + "label": "Branch Arbor Source", + }, + "pos": {"x": 40.0, "y": 360.0}, + } + nodes[str(n_scol)] = { + "node": { + "uuid": n_scol, + "op": {"ColorByDPV": {"field": dpv_field, "colormap": streamline_colormap}}, + "label": "Color By DPV", + }, + "pos": {"x": 320.0, "y": 360.0}, + } + nodes[str(n_sdisp)] = { + "node": { + "uuid": n_sdisp, + "op": { + "StreamlineDisplay": { + "enabled": True, + "render_style": "Tubes", + "tube_radius_mm": float(tube_radius_mm), + "tube_sides": 8, + "slab_half_width_mm": 2.5, + "opacity": 0.96, + } + }, + "label": "Branch Arbor Tubes", + }, + "pos": {"x": 600.0, "y": 360.0}, + } + wires.append({"from": {"node": n_ssrc, "output": 0}, "to": {"node": n_scol, "input": 0}}) + wires.append({"from": {"node": n_scol, "output": 0}, "to": {"node": n_sdisp, "input": 0}}) + + if bundle_surface: + n_bsbuild = next_node_id + n_bsdisp = next_node_id + 1 + next_node_id += 2 + nodes[str(n_bsbuild)] = { + "node": { + "uuid": n_bsbuild, + "op": { + "BundleSurfaceBuild": { + "per_group": False, + "build_mode": "MarchingCubes", + "voxel_size_mm": float(bundle_surface_voxel_size_mm), + "threshold": float(bundle_surface_threshold), + "smooth_sigma": float(bundle_surface_smooth_sigma), + "min_component_volume_mm3": 10.0, + "tube_radius_mm": float(tube_radius_mm), + "tube_sides": 8, + "opacity": float(bundle_surface_opacity), + } + }, + "label": "Branch Cross-Section Surface Build", + }, + "pos": {"x": 600.0, "y": 500.0}, + } + nodes[str(n_bsdisp)] = { + "node": { + "uuid": n_bsdisp, + "op": { + "BundleSurfaceDisplay": { + "color_mode": bundle_surface_color_mode, + "outline_thickness": float(bundle_surface_outline_thickness), + } + }, + "label": "Branch Cross-Section Surface Display", + }, + "pos": {"x": 880.0, "y": 500.0}, + } + wires.append({"from": {"node": n_scol, "output": 0}, "to": {"node": n_bsbuild, "input": 0}}) + wires.append({"from": {"node": n_bsbuild, "output": 0}, "to": {"node": n_bsdisp, "input": 0}}) + + # 4. Optional GIFTI Cross-Sectional Iso-Surfaces (.surf.gii) with slice contour outlines + if surface_shells: + for idx_sh, sh in enumerate(surface_shells): + surf_path = sh["path"] + surf_label = sh.get("label", f"Cross-Section Shell {idx_sh + 1}") + surf_color = [float(c) for c in sh.get("color", [0.15, 0.90, 1.0])] + surf_opacity = float(sh.get("opacity", 0.20)) + outline_color = [float(c) for c in sh.get("outline_color", surf_color)] + outline_thickness = float(sh.get("outline_thickness", 2.6)) + + g_asset_id = next_asset_id + next_asset_id += 1 + assets.append({"Surface": {"id": g_asset_id, "path": str(surf_path)}}) + + n_gsrc = next_node_id + n_gstack = next_node_id + 1 + n_gdisp = next_node_id + 2 + next_node_id += 3 + y_pos = 640.0 + idx_sh * 140.0 + nodes[str(n_gsrc)] = { + "node": { + "uuid": n_gsrc, + "op": {"SurfaceSource": {"source_id": g_asset_id}}, + "label": f"{surf_label} Source", + }, + "pos": {"x": 40.0, "y": y_pos}, + } + nodes[str(n_gstack)] = { + "node": { + "uuid": n_gstack, + "op": {"SurfaceOverlayStack": {}}, + "label": f"{surf_label} Overlay", + }, + "pos": {"x": 320.0, "y": y_pos}, + } + nodes[str(n_gdisp)] = { + "node": { + "uuid": n_gdisp, + "op": { + "SurfaceDisplay": { + "color": surf_color, + "opacity": surf_opacity, + "outline_color": outline_color, + "outline_thickness": outline_thickness, + "show_projection_map": False, + "map_opacity": 1.0, + "map_threshold": 0.0, + "gloss": 0.55, + "projection_colormap": "Inferno", + "range_min": 0.0, + "range_max": 1.0, + "space": "Anatomical", + } + }, + "label": f"{surf_label} Display", + }, + "pos": {"x": 600.0, "y": y_pos}, + } + wires.append({"from": {"node": n_gsrc, "output": 0}, "to": {"node": n_gstack, "input": 0}}) + wires.append({"from": {"node": n_gstack, "output": 0}, "to": {"node": n_gdisp, "input": 0}}) + + project = { + "version": 1, + "document": { + "next_node_uuid": next_node_id + 5, + "graph": {"nodes": nodes, "wires": wires}, + "assets": assets, + "camera_3d": { + "target": [float(x) for x in camera_target], + "azimuth_deg": float(azimuth_deg), + "elevation_deg": float(elevation_deg), + "distance": float(distance), + }, + "slice_view_3d": { + "visible": [bool(v) for v in slice_visible], + "positions_ras": [float(p) for p in slice_positions_ras], + }, + "slice_view_ui": { + "mode": "Ortho", + "single_view": "Sagittal", + "lightbox_axis": "Axial", + "lightbox_rows": 3, + "lightbox_cols": 3, + "active_axis": 2, + "ortho_show_row": True, + "slice_cameras": [ + {"center": [float(camera_target[0]), float(camera_target[1])], "half_extent": 85.0, "rotation": 0.0}, + {"center": [float(camera_target[0]), float(camera_target[2])], "half_extent": 85.0, "rotation": 0.0}, + {"center": [float(camera_target[1]), float(camera_target[2])], "half_extent": 85.0, "rotation": 0.0}, + ], + }, + }, + } + with open(out_project_path, "w") as f: + json.dump(project, f, indent=2) + return out_project_path + + +def render_trxviz( + project_path: str, + out_png_path: str, + width: int = 1280, + height: int = 960, + view: str = "3d", + trxviz_cli_bin: Optional[str] = None, + return_ipython_image: bool = True, +): + """Render a ``.trxviz`` project file on the GPU via ``trxviz-cli render`` and + optionally return an ``IPython.display.Image`` for inline display in Jupyter notebooks. + """ + import os + import shutil + import subprocess + from pathlib import Path + + # A TRXViz checkout next to this repo (../odx/TRXViz) is the last resort. + sibling = Path(__file__).resolve().parents[3] / "odx" / "TRXViz" / "target" / "release" / "trxviz-cli" + cli = ( + trxviz_cli_bin + or os.environ.get("TRXVIZ_CLI") + or shutil.which("trxviz-cli") + or (str(sibling) if sibling.is_file() else "trxviz-cli") + ) + cmd = [ + cli, + "render", + "--project", + str(project_path), + "--out", + str(out_png_path), + "--width", + str(width), + "--height", + str(height), + "--view", + str(view), + ] + subprocess.run(cmd, check=True) + if return_ipython_image: + try: + from IPython.display import Image as IPyImage + + return IPyImage(filename=str(out_png_path)) + except ImportError: + pass + return out_png_path diff --git a/src/mpat/chain.py b/src/mpat/chain.py index a30ec61..b12d7cf 100644 --- a/src/mpat/chain.py +++ b/src/mpat/chain.py @@ -250,11 +250,28 @@ def _fingerprint(self, sh, zooms, transient, absorb_class): return h.hexdigest() def _save_cache(self, path, fp): + if str(path).endswith((".odx", ".odxd")): + from .transitions import save_transitions_odx + + save_transitions_odx(self, path, fingerprint=fp, quantize_weights=False) + return np.savez(path, fingerprint=np.array(fp), **{k: getattr(self, k) for k in self._CACHE_KEYS}) def _load_cache(self, path, fp): if not Path(path).exists(): return False + if str(path).endswith((".odx", ".odxd")): + from .transitions import load_transitions_odx + + try: + loaded = load_transitions_odx(path, fingerprint=fp) + except Exception: # noqa: BLE001 + log.info("cache %s does not match the inputs; rebuilding", path) + return False + for k in self._CACHE_KEYS: + setattr(self, k, getattr(loaded, k)) + log.info("loaded transitions from %s", path) + return True z = np.load(path) if str(z["fingerprint"]) != fp or any(k not in z.files for k in self._CACHE_KEYS): log.info("cache %s does not match the inputs; rebuilding", path) @@ -264,6 +281,32 @@ def _load_cache(self, path, fp): log.info("loaded transitions from %s", path) return True + def save_odx(self, path, affine=None, **kwargs): + """Persist this chain's transitions, fixel lobes and per-voxel metrics to an ``.odx`` archive.""" + from .transitions import save_transitions_odx + + return save_transitions_odx(self, path, affine=affine, **kwargs) + + @classmethod + def load_odx(cls, path, return_extras=False): + """Load a :class:`Chain` directly from an ``.odx`` archive without needing the fODF NIfTI.""" + from .transitions import load_transitions_odx + + return load_transitions_odx(path, return_extras=return_extras) + + def save_nifti(self, prefix, affine=None): + """Write 4-D ``(X, Y, Z, 26)`` voxel-to-neighbour transition NIfTI + ``codi``/``coasy`` maps.""" + from .transitions import save_transitions_nifti + + return save_transitions_nifti(self, prefix, affine=affine) + + @classmethod + def from_nifti(cls, nifti_path_or_prefix, absorb_class=None): + """Build a 26-class :class:`Chain` from a 4-D ``(X, Y, Z, 26)`` transition NIfTI.""" + from .transitions import load_transitions_nifti + + return load_transitions_nifti(nifti_path_or_prefix, absorb_class=absorb_class) + # ------------------------------------------------------------------ seeds def lin(self, ijk): return np.ravel_multi_index(tuple(np.asarray(ijk, int).T + 1), self.pshape) diff --git a/src/mpat/cli.py b/src/mpat/cli.py index 731f765..79c1070 100644 --- a/src/mpat/cli.py +++ b/src/mpat/cli.py @@ -57,6 +57,23 @@ def main(argv=None): p.add_argument("--fixels", action="store_true", help="also write an MRtrix fixel directory with each bundle's expected streamlines per fixel " "and its share of all traffic (mpat.fixels; one extra whole-brain solve)") + p.add_argument("--ptt", action="store_true", + help="use Parallel Transport Tractography (PTT) defaults (fod_thresh=0.08, fod_power=1.5, " + "curv_sigma=18.0, probe_radius=0.5, stop_mass=1e-4)") + p.add_argument("--step", type=float, default=1.0, help="hop length in voxels (default 1.0)") + p.add_argument("--stop-mass", type=float, default=None, help="MITTENS stopping regularizer tau") + p.add_argument("--fod-thresh", type=float, default=None, help="relative fODF floor") + p.add_argument("--fod-power", type=float, default=None, help="fODF sharpening exponent p") + p.add_argument("--curv-sigma", type=float, default=None, help="PTT curvature & co-circularity sigma (deg)") + p.add_argument("--probe-radius", type=float, default=None, help="PTT cylindrical probe radius (voxels)") + p.add_argument("--sift2", action="store_true", + help="calibrate seed launch weights globally with path-consistent SIFT2 before segmentation") + p.add_argument("--arbor", action="store_true", + help="also extract and write 3-D multi-branch cross-section ridge arbors (.trx, .json, .tsv)") + p.add_argument("--arbor-branches", type=int, default=5, + help="maximum cortical endpoint branches per side for arbor extraction (default 5)") + p.add_argument("--save-transitions", choices=("odx", "nifti", "both"), default=None, + help="persist transition probabilities as ODX (.odx), 4-D NIfTI (.nii.gz + codi/coasy), or both") p.add_argument("--afq-kwargs", default="{}", help="extra ParticipantAFQ arguments: JSON, or a Python expression giving a dict, " "with afd (AFQ.data.fetch), abd (AFQ.api.bundle_dict), mb (mpat.bundles) and the " @@ -95,7 +112,11 @@ def main(argv=None): synthseg_thalamus=not a.mni_thalamus, max_length=a.max_length, viz_rois=a.viz_rois, no_midline=a.no_midline, midline_tol=a.midline_tol, out_dir=a.out_dir, verbose=a.verbose, - fornix=not a.no_fornix_exclude, flux=a.flux, fixels=a.fixels) + fornix=not a.no_fornix_exclude, flux=a.flux, fixels=a.fixels, + ptt=a.ptt, step=a.step, stop_mass=a.stop_mass, fod_thresh=a.fod_thresh, + fod_power=a.fod_power, curv_sigma=a.curv_sigma, probe_radius=a.probe_radius, + sift2=a.sift2, arbor=a.arbor, arbor_branches=a.arbor_branches, + save_transitions=a.save_transitions or False) if a.pyafq: # pyAFQ's recognition: MPAT's rules removed, MPAT-only bundles (fornix) dropped from .bundles import pyafq_bd diff --git a/src/mpat/fields.py b/src/mpat/fields.py index 49e7894..a5c110d 100644 --- a/src/mpat/fields.py +++ b/src/mpat/fields.py @@ -199,20 +199,35 @@ def endpoint_patches(endpoints, sigma_vox=2.5, min_share=0.02, prominence=0.2): two ends. Patches pooled over many subjects in a template space are more stable than one subject's (docs/fields.md).""" from scipy import ndimage as ndi - from skimage.feature import peak_local_max - from skimage.segmentation import watershed vol = np.clip(np.nan_to_num(np.asarray(endpoints, np.float64)), 0, None) blur = ndi.gaussian_filter(vol, sigma_vox) if blur.max() <= 0: return np.zeros(vol.shape, np.int16), [] sup = blur > 0.01 * blur.max() - peaks = peak_local_max(blur, min_distance=3, threshold_abs=0.01 * blur.max(), - labels=sup.astype(int), exclude_border=False) - markers = np.zeros(vol.shape, int) - for k, p in enumerate(peaks): - markers[tuple(p)] = k + 1 - ws = watershed(-blur, markers, mask=sup) + try: + from skimage.feature import peak_local_max + from skimage.segmentation import watershed + + peaks = peak_local_max(blur, min_distance=3, threshold_abs=0.01 * blur.max(), + labels=sup.astype(int), exclude_border=False) + markers = np.zeros(vol.shape, int) + for k, p in enumerate(peaks): + markers[tuple(p)] = k + 1 + ws = watershed(-blur, markers, mask=sup) + except ImportError: + loc_max = (blur == ndi.maximum_filter(blur, size=7)) & sup + lbl_pk, n_pk = ndi.label(loc_max) + peaks = [] + for k in range(1, n_pk + 1): + pts = np.argwhere(lbl_pk == k) + peaks.append(pts[np.argmax(blur[tuple(pts.T)])]) + peaks = np.asarray(peaks, dtype=int).reshape(-1, 3) + ws = np.zeros(vol.shape, dtype=int) + if len(peaks) > 0: + sup_ijk = np.argwhere(sup) + dists = ((sup_ijk[:, None, :] - peaks[None, :, :]) ** 2).sum(-1) + ws[tuple(sup_ijk.T)] = np.argmin(dists, axis=1) + 1 npk = len(peaks) pk = np.concatenate([[0.0], [blur[tuple(p)] for p in peaks]]) mass = np.bincount(ws.ravel(), weights=vol.ravel(), minlength=npk + 1) diff --git a/src/mpat/kernel.py b/src/mpat/kernel.py index cb9d582..aba99a7 100644 --- a/src/mpat/kernel.py +++ b/src/mpat/kernel.py @@ -18,6 +18,10 @@ """ from __future__ import annotations +import os + +os.environ.setdefault("NUMBA_THREADING_LAYER", "workqueue") + import numpy as np from numba import njit, prange diff --git a/src/mpat/quantify.py b/src/mpat/quantify.py index ce95260..9148277 100644 --- a/src/mpat/quantify.py +++ b/src/mpat/quantify.py @@ -72,7 +72,13 @@ def afd_tract_metrics(bundle_res, whole_density_class, sh_rows, geo, lobes: Lobe lobes = segment_lobes(sh_rows, geo) n_b, u_b = fixel_streamlines(bundle_res.density_class, sh_rows, geo, lobes) n_w, u_w = fixel_streamlines(whole_density_class, sh_rows, geo, lobes) - share = np.divide(n_b, n_w, out=np.zeros_like(n_b), where=n_w > 1e-30) + # Regularize denominator so boundary voxels with tiny whole-brain visitation n_w + # do not amplify negligible bundle tails (n_b / (n_w + reg)). + pos_b = n_b[n_b > 0] + b_scale = float(np.percentile(pos_b, 95)) if pos_b.size else 1.0 + pos_w = n_w[n_w > 0] + w_reg = max(0.10 * float(np.median(pos_w)) if pos_w.size else 1e-6, 0.05 * b_scale, 1e-12) + share = np.divide(n_b, np.maximum(n_w, 0.0) + w_reg, out=np.zeros_like(n_b), where=(n_b > 0)) share = np.clip(share, 0.0, 1.0) fixel_afd = share * lobes.integral Nt = len(sh_rows) diff --git a/src/mpat/solve.py b/src/mpat/solve.py index 14ccf03..eaf86c4 100644 --- a/src/mpat/solve.py +++ b/src/mpat/solve.py @@ -139,7 +139,8 @@ def _crawling(hist, it, tol, window=10): return 0 < q1 < 1 and abs(q1 - q0) < 0.02 and np.log(tol / hist[-1]) / np.log(q1) > TAIL_SWITCH_AFTER -def solve_series(mul, x0, mask, tol, max_iter, what, ncomp=1, verbose=False, accel=False, krylov=True): +def solve_series(mul, x0, mask, tol, max_iter, what, ncomp=1, verbose=False, accel=False, krylov=True, + on_step=None): """total = sum_t (M A)^t x0 per column (M = diag(mask)), A x = mul(x, out), by power iteration until the remaining mass (mass rows, relative to the largest column's start) is below ``tol``. Stops early when it stalls (mass circulating in states that almost never @@ -147,6 +148,8 @@ def solve_series(mul, x0, mask, tol, max_iter, what, ncomp=1, verbose=False, acc ``verbose``: log the time per step (matrix product / masking and summing) every 100 steps. ``accel``: False (default), True / "mr" (invariant-preserving Periodic Minimal Residual extrapolation), or "aitken" (scalar Aitken delta-squared extrapolation). + ``on_step``: optional callback ``on_step(it, res, total, term)`` invoked after each iteration + (``term``: that iteration's term of the series, i.e. the current wavefront). Returns (total, info).""" t_start = time.perf_counter() t_mul = t_acc = 0.0 @@ -200,6 +203,8 @@ def solve_series(mul, x0, mask, tol, max_iter, what, ncomp=1, verbose=False, acc term, nxt = nxt, term hist.append(res) info.update(iterations=it, residual=res) + if on_step is not None: + on_step(it, res, total, term) if it % 100 == 0: log.info(" %s step %d: remaining mass %.2e", what, it, res) if verbose: @@ -481,9 +486,10 @@ def _trapped(chain, info, what, names, on_trapped): on_trapped(what, names, vol) -def _solve(chain, x0, mask, tol, max_iter, what, verbose=False, accel=False): +def _solve(chain, x0, mask, tol, max_iter, what, verbose=False, accel=False, on_step=None): mul = chain.mul_forward if what == "forward" else chain.mul_backward - return solve_series(mul, x0, mask, tol, max_iter, what, chain.ncomp, verbose, accel=accel, krylov=False) + return solve_series(mul, x0, mask, tol, max_iter, what, chain.ncomp, verbose, accel=accel, krylov=False, + on_step=on_step) def _solve_group(chain, plans, L, tol, max_iter, on_result, on_trapped=None, verbose=False, clock=None, diff --git a/src/mpat/transitions.py b/src/mpat/transitions.py new file mode 100644 index 0000000..b8e50e3 --- /dev/null +++ b/src/mpat/transitions.py @@ -0,0 +1,846 @@ +"""Persistence of MPAT and MITTENS transition probabilities in ODX (``.odx``) and NIfTI formats. + +* **ODX (``.odx``)** is the native container for 2nd-order / PTT (Parallel Transport Tractography) + and fixel-aware Markov chains: it stores the masked white-matter voxel grid (``mask.uint8``), + segmented fODF fixel lobes (``offsets.uint32``, ``directions.3.float32``, ``dpf/*``), + per-voxel scalar & 26-direction transition summaries (``dpv/*``), and the compressed + 26-class Markov stencil (``groups/mpat_*``) in a single spec-compliant ``.odx`` archive + that opens directly in ``odx-rs``, ``TRXViz``, and :meth:`mpat.Chain.load_odx`. +* **NIfTI (``.nii.gz`` + ``.json``)** is the classic 1st-order MITTENS representation: a 4-D + ``(X, Y, Z, 26)`` volume of voxel-to-neighbour transition probabilities plus 3-D scalar + dispersion (``codi``) and asymmetry (``coasy``) maps and a JSON sidecar listing the 26 + neighbour offsets. +""" +from __future__ import annotations + +import json +import zipfile +from dataclasses import replace +from pathlib import Path +from typing import Dict, Optional, Tuple, Union + +import nibabel as nib +import numpy as np +from numba import njit, prange + +from . import kernel as K +from .chain import ABSORB_CLASSES, CSF, Chain, ChainConfig +from .fixels import Lobes +from .geometry import OFFSETS, build_geometry +from .solve import Launches + +_DTYPE_TO_ODX = { + np.dtype("float16"): "float16", + np.dtype("float32"): "float32", + np.dtype("float64"): "float64", + np.dtype("int8"): "int8", + np.dtype("int16"): "int16", + np.dtype("int32"): "int32", + np.dtype("int64"): "int64", + np.dtype("uint8"): "uint8", + np.dtype("uint16"): "uint16", + np.dtype("uint32"): "uint32", + np.dtype("uint64"): "uint64", +} +_ODX_TO_DTYPE = {v: k for k, v in _DTYPE_TO_ODX.items()} + + +def neighbor_labels(affine: np.ndarray) -> list[str]: + """Human-readable labels (e.g. ``R_A_S`` or ``i+1_j+0_k-1``) for the 26 lexicographic offsets.""" + try: + axcodes = nib.orientations.aff2axcodes(np.asarray(affine, dtype=float)) + except Exception: # noqa: BLE001 + axcodes = ("I", "J", "K") + opp = {"R": "L", "L": "R", "A": "P", "P": "A", "S": "I", "I": "S"} + labels = [] + for di, dj, dk in OFFSETS: + parts = [] + for delta, pos_code in zip((di, dj, dk), axcodes): + if delta > 0: + parts.append(pos_code) + elif delta < 0: + parts.append(opp.get(pos_code, f"-{pos_code}")) + labels.append("".join(parts) if parts else "0") + return labels + + +@njit(parallel=True, cache=True) +def _marginal_stencil_numba( + Q_ptr: np.ndarray, + Q_slot: np.ndarray, + Q_w: np.ndarray, + R_ptr: np.ndarray, + R_ind: np.ndarray, + R_val: np.ndarray, + t_lin: np.ndarray, + a_lin: np.ndarray, + noff: np.ndarray, + dead: np.ndarray, + tmpl_n: np.ndarray, + nb: int, + Nt: int, +) -> Tuple[np.ndarray, np.ndarray, np.ndarray]: + """Collapse the (Nt * nb) stencil over incoming classes into (Nt, 26) marginal + voxel-to-neighbour probabilities (including both transient and absorbing neighbours), + (Nt,) absorption probabilities, and (Nt,) dead probabilities. + """ + p_nbr = np.zeros((Nt, 26), dtype=np.float32) + p_abs = np.zeros(Nt, dtype=np.float32) + p_dead = np.zeros(Nt, dtype=np.float32) + inv_nb = 1.0 / float(nb) + + for v in prange(Nt): + v_lin = t_lin[v] + s0 = v * nb + acc_abs = 0.0 + acc_dead = 0.0 + for b in range(nb): + s = s0 + b + acc_dead += dead[s] + for k in range(Q_ptr[s], Q_ptr[s + 1]): + slot = Q_slot[k] + nbr = tmpl_n[b, slot] + if nbr >= 0: + p_nbr[v, nbr] += np.float32(Q_w[k] * inv_nb) + for k in range(R_ptr[s], R_ptr[s + 1]): + w_r = R_val[k] + acc_abs += w_r + target_lin = a_lin[R_ind[k]] + diff = target_lin - v_lin + for n in range(26): + if noff[n] == diff: + p_nbr[v, n] += np.float32(w_r * inv_nb) + break + p_abs[v] = np.float32(acc_abs * inv_nb) + p_dead[v] = np.float32(acc_dead * inv_nb) + + return p_nbr, p_abs, p_dead + + +@njit(parallel=True, cache=True) +def _fixel_half_probs_numba( + Q_ptr: np.ndarray, + Q_slot: np.ndarray, + Q_w: np.ndarray, + tmpl_n: np.ndarray, + nb: int, + frow: np.ndarray, + b_plus: np.ndarray, + b_minus: np.ndarray, +) -> Tuple[np.ndarray, np.ndarray]: + """Extract (N_fixels, 26) outgoing neighbour transition probabilities along the + and - + half-lobe direction classes of each fixel. + """ + nf = frow.size + p_plus = np.zeros((nf, 26), dtype=np.float32) + p_minus = np.zeros((nf, 26), dtype=np.float32) + for f in prange(nf): + v = frow[f] + bp = b_plus[f] + bm = b_minus[f] + sp = v * nb + bp + for k in range(Q_ptr[sp], Q_ptr[sp + 1]): + nbr = tmpl_n[bp, Q_slot[k]] + if nbr >= 0: + p_plus[f, nbr] += np.float32(Q_w[k]) + sm = v * nb + bm + for k in range(Q_ptr[sm], Q_ptr[sm + 1]): + nbr = tmpl_n[bm, Q_slot[k]] + if nbr >= 0: + p_minus[f, nbr] += np.float32(Q_w[k]) + return p_plus, p_minus + + +def marginal_transition_metrics(chain: Chain) -> Dict[str, np.ndarray]: + """Compute marginal 26-neighbour transition probabilities ``(Nt, 26)``, ``codi`` ``(Nt,)``, + ``coasy`` ``(Nt,)``, ``p_absorb`` ``(Nt,)``, and ``dead_mean`` ``(Nt,)`` directly from ``chain``. + """ + Nt = int(chain.t_lin.size) + p_nbr, p_abs, p_dead = _marginal_stencil_numba( + chain.Q_ptr, + chain.Q_slot, + np.asarray(chain.Q_w, dtype=np.float64), + chain.R_ptr, + np.asarray(chain.R_ind, dtype=np.int32), + np.asarray(chain.R_val, dtype=np.float64), + np.asarray(chain.t_lin, dtype=np.int64), + np.asarray(chain.a_lin, dtype=np.int64), + np.asarray(chain.noff, dtype=np.int64), + np.asarray(chain.dead, dtype=np.float64), + chain.tmpl_n, + int(chain.nb), + Nt, + ) + # Normalize rows that have positive continuation mass for compositional metrics (CoDI & CoAsy) + row_sum = p_nbr.sum(axis=1, keepdims=True) + p_norm = np.divide(p_nbr, row_sum, out=np.full_like(p_nbr, 1.0 / 26.0), where=row_sum > 1e-12) + eps = 1e-7 + p_safe = np.maximum(p_norm, eps) + log_p = np.log(p_safe) + clr = log_p - log_p.mean(axis=1, keepdims=True) + codi = np.sqrt(np.sum(clr * clr, axis=1)).astype(np.float32) + codi[row_sum[:, 0] <= 1e-12] = 0.0 + + # Antipodal asymmetry across the 13 opposite neighbour pairs: OFFSETS[25 - n] == -OFFSETS[n] + p_rev = p_safe[:, ::-1] + diff_anti = np.log(p_safe[:, :13]) - np.log(p_rev[:, :13]) + coasy = np.sqrt(np.mean(diff_anti * diff_anti, axis=1)).astype(np.float32) + coasy[row_sum[:, 0] <= 1e-12] = 0.0 + + return { + "p_neighbor": p_nbr, + "p_absorb": p_abs, + "dead_mean": p_dead, + "codi": codi, + "coasy": coasy, + } + + +def _voxel_to_world_unit(vectors: np.ndarray, affine: np.ndarray) -> np.ndarray: + """Rotate unit vectors from voxel axes into scanner RAS+ world axes.""" + if len(vectors) == 0: + return np.zeros((0, 3), dtype=np.float32) + R = np.asarray(affine, dtype=np.float64)[:3, :3] + R_norm = R / np.maximum(np.linalg.norm(R, axis=0, keepdims=True), 1e-12) + w = np.asarray(vectors, dtype=np.float64) @ R_norm.T + nrm = np.maximum(np.linalg.norm(w, axis=1, keepdims=True), 1e-12) + return (w / nrm).astype(np.float32) + + +def _format_odx_entry(folder: str, name: str, arr: np.ndarray) -> Tuple[str, bytes]: + arr = np.ascontiguousarray(arr) + if arr.ndim == 1: + ncols = 1 + elif arr.ndim == 2: + ncols = int(arr.shape[1]) + else: + raise ValueError(f"ODX array {folder}/{name} must be 1D or 2D, got {arr.ndim}D") + dt_name = _DTYPE_TO_ODX[arr.dtype] + return f"{folder}/{name}.{ncols}.{dt_name}", arr.tobytes(order="C") + + +def save_transitions_odx( + chain: Chain, + path: Union[str, Path], + affine: Optional[np.ndarray] = None, + fingerprint: Optional[str] = None, + sh_rows: Optional[np.ndarray] = None, + lobes: Optional[Lobes] = None, + launches: Optional[Launches] = None, + whole_dc: Optional[np.ndarray] = None, + surv: Optional[np.ndarray] = None, + mittens_maps: Optional[Dict[str, np.ndarray]] = None, + quantize_weights: bool = True, +) -> Path: + """Persist ``chain`` (including PTT / 26-class stencil, fixel lobes, and per-voxel transition + metrics) as a spec-compliant ``.odx`` archive (or ``.odxd`` directory). + + Parameters + ---------- + chain : mpat.Chain + Built Markov chain. + path : str or Path + Destination ``.odx`` archive or ``.odxd`` directory. + affine : (4, 4) array, optional + Voxel-to-RAS+mm affine (defaults to ``diag(zooms, 1)``). + fingerprint : str, optional + Input + config SHA-1 digest used by :meth:`Chain.build` cache validation. + sh_rows : (Nt, K) float32 array, optional + Transient WM spherical harmonic coefficients (if ``lobes`` is not supplied, lobes are + segmented from ``sh_rows``). + lobes : mpat.fixels.Lobes, optional + Pre-segmented fODF lobes for the ``Nt`` transient WM voxels. + launches : mpat.solve.Launches, optional + Precomputed seed half-walk launches to embed for instant downstream solving. + whole_dc : (Nt, 26) float32 array, optional + Unconditioned whole-brain class visitation density for AFD attribution. + surv : (Ns,) or (Nt,) float32 array, optional + Overlength survival probabilities per state or per voxel. + mittens_maps : dict, optional + Additional per-voxel maps from ``mittens.TransitionModel.fit``. + quantize_weights : bool + Store ``Q_w`` and ``R_val`` in ``float32`` instead of ``float64`` (halves file size while + preserving transition probabilities to ``< 1e-7``). + """ + path = Path(path) + shape = tuple(int(s) for s in chain.shape) + Nt = int(chain.t_lin.size) + nb = int(chain.nb) + + if affine is None: + affine = getattr(chain, "affine", None) + if affine is None: + affine = np.eye(4, dtype=np.float64) + affine = np.asarray(affine, dtype=np.float64) + zooms = [float(x) for x in np.linalg.norm(affine[:3, :3], axis=0)] + + # Build full-grid uint8 mask matching chain.t_lin in C-order + t_ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), axis=1) - 1 + mask_3d = np.zeros(shape, dtype=np.uint8) + mask_3d[tuple(t_ijk.T)] = 1 + mask_bytes = np.ascontiguousarray(mask_3d.ravel(order="C"), dtype=" 0 and lobes._frow is not None: + verts = chain.geo.vertices + dots = lobes.direction @ verts.T + d_plus = np.argmax(dots, axis=1) + d_minus = np.argmin(dots, axis=1) + b_plus = chain.geo.vbin[d_plus].astype(np.int64) + b_minus = chain.geo.vbin[d_minus].astype(np.int64) + p_plus, p_minus = _fixel_half_probs_numba( + chain.Q_ptr, + chain.Q_slot, + np.asarray(chain.Q_w, dtype=np.float64), + chain.tmpl_n, + nb, + lobes._frow.astype(np.int64), + b_plus, + b_minus, + ) + for k_f, b_f in [ + _format_odx_entry("dpf", "ptt_plus", p_plus), + _format_odx_entry("dpf", "ptt_minus", p_minus), + ]: + entries[k_f] = b_f + else: + nb_peaks = 0 + offsets_u32 = np.zeros(Nt + 1, dtype=" 0: + group_arrays["mpat_kill"] = np.asarray(kill, dtype=" Tuple[dict, Dict[str, Tuple[int, np.dtype, bytes]]]: + """Read ``header.json`` and all typed array entries from an ``.odx`` archive or ``.odxd`` dir.""" + raw_files: Dict[str, bytes] = {} + if path.is_dir(): + for p in path.rglob("*"): + if p.is_file(): + rel = p.relative_to(path).as_posix() + raw_files[rel] = p.read_bytes() + else: + with zipfile.ZipFile(path, mode="r") as zf: + for name in zf.namelist(): + if not name.endswith("/"): + raw_files[name] = zf.read(name) + + header = json.loads(raw_files["header.json"].decode("utf-8")) + parsed: Dict[str, Tuple[int, np.dtype, bytes]] = {} + for rel, data in raw_files.items(): + if rel == "header.json": + continue + fname = rel.rsplit("/", 1)[-1] + parts = fname.split(".") + prefix = rel.rsplit("/", 1)[0] + "/" if "/" in rel else "" + if len(parts) == 2 and parts[1] in _ODX_TO_DTYPE: + parsed[f"{prefix}{parts[0]}"] = (1, _ODX_TO_DTYPE[parts[1]], data) + elif len(parts) == 3 and parts[2] in _ODX_TO_DTYPE: + parsed[f"{prefix}{parts[0]}"] = (int(parts[1]), _ODX_TO_DTYPE[parts[2]], data) + return header, parsed + + +def _decode_array(entry: Tuple[int, np.dtype, bytes], squeeze_1d: bool = True) -> np.ndarray: + ncols, dt, raw = entry + arr = np.frombuffer(raw, dtype=dt).copy() + if ncols > 1 or not squeeze_1d: + return arr.reshape(-1, ncols) + return arr + + +def load_transitions_odx( + path: Union[str, Path], + fingerprint: Optional[str] = None, + return_extras: bool = False, +): + """Load an :class:`mpat.Chain` (and optionally ``affine``, ``lobes``, ``launches``, ``whole_dc``, + ``dpv``) from an ``.odx`` archive or ``.odxd`` directory written by :func:`save_transitions_odx`. + """ + path = Path(path) + header, entries = _parse_odx_entries(path) + mpat_meta = header.get("mpat") or {} + if fingerprint is not None and mpat_meta.get("fingerprint") != fingerprint: + raise ValueError(f"ODX fingerprint mismatch in {path}") + if "groups/mpat_Q_ptr" not in entries: + raise ValueError(f"{path} does not contain MPAT stencil arrays (groups/mpat_Q_ptr)") + + cfg_dict = dict(mpat_meta.get("config") or {}) + valid_cfg = {f.name for f in ChainConfig.__dataclass_fields__.values()} + cfg = ChainConfig(**{k: v for k, v in cfg_dict.items() if k in valid_cfg}) + + dims = tuple(int(d) for d in header["DIMENSIONS"]) + pshape = tuple(int(d) for d in mpat_meta.get("pshape", [d + 2 for d in dims])) + affine = np.asarray(header["VOXEL_TO_RASMM"], dtype=np.float64) + zooms = tuple(float(z) for z in mpat_meta.get("zooms", np.linalg.norm(affine[:3, :3], axis=0))) + + mask_flat = _decode_array(entries["mask"]).reshape(dims) > 0 + trans_p = np.zeros(pshape, dtype=bool) + trans_p[1:-1, 1:-1, 1:-1] = mask_flat + + chain = Chain() + chain.cfg = cfg + chain.shape = dims + chain.pshape = pshape + chain.affine = affine + chain.noff = (OFFSETS @ np.array([pshape[1] * pshape[2], pshape[2], 1])).astype(np.int64) + chain.nb = int(mpat_meta.get("nb", 26)) + chain.t_lin = np.flatnonzero(trans_p.ravel()).astype(np.int64) + chain.tindex = np.full(int(np.prod(pshape)), -1, dtype=np.int64) + chain.tindex[chain.t_lin] = np.arange(chain.t_lin.size) + + chain.a_lin = _decode_array(entries["groups/mpat_a_lin"]).astype(np.int64) + chain.a_class = _decode_array(entries["groups/mpat_a_class"]).astype(np.int64) + chain.aindex = np.full(int(np.prod(pshape)), -1, dtype=np.int64) + chain.aindex[chain.a_lin] = np.arange(chain.a_lin.size) + + if "groups/mpat_label" in entries: + chain.label = _decode_array(entries["groups/mpat_label"]).astype(np.int8) + else: + label = np.zeros(int(np.prod(pshape)), dtype=np.int8) + label[chain.a_lin] = np.where(chain.a_class == CSF, K.BLOCKED, K.ABSORBING) + label[chain.t_lin] = K.TRANSIENT + chain.label = label + + chain.Q_ptr = _decode_array(entries["groups/mpat_Q_ptr"]).astype(np.int64) + chain.Q_slot = _decode_array(entries["groups/mpat_Q_slot"]) + chain.Q_w = _decode_array(entries["groups/mpat_Q_w"]).astype(np.float64) + chain.R_ptr = _decode_array(entries["groups/mpat_R_ptr"]).astype(np.int64) + chain.R_ind = _decode_array(entries["groups/mpat_R_ind"]).astype(np.int32) + chain.R_val = _decode_array(entries["groups/mpat_R_val"]).astype(np.float64) + chain.tmpl_n = _decode_array(entries["groups/mpat_tmpl_n"], squeeze_1d=False).astype(np.int16) + chain.tmpl_b = _decode_array(entries["groups/mpat_tmpl_b"], squeeze_1d=False).astype(np.int16) + chain.dead = _decode_array(entries["dpv/dead"], squeeze_1d=False).astype(np.float64).ravel() + + if "groups/mpat_kill" in entries: + chain.kill = _decode_array(entries["groups/mpat_kill"]).astype(bool) + else: + chain.kill = None + + chain.geo = build_geometry(zooms, cfg.angle, cfg.step, curv_sigma=cfg.curv_sigma) + chain._finalize() + + if not return_extras: + return chain + + extras: Dict[str, object] = { + "affine": affine, + "zooms": zooms, + "header": header, + } + if "sh/coefficients" in entries: + extras["sh_rows"] = _decode_array(entries["sh/coefficients"], squeeze_1d=False).astype(np.float32) + + if int(header.get("NB_PEAKS", 0)) > 0 and "offsets" in entries: + offsets_u32 = _decode_array(entries["offsets"]).astype(np.int64) + count = np.diff(offsets_u32) + offset = offsets_u32[:-1] + if "dpf/dir_vox" in entries: + dir_vox = _decode_array(entries["dpf/dir_vox"], squeeze_1d=False).astype(np.float64) + else: + dirs_ras = _decode_array(entries["directions"], squeeze_1d=False).astype(np.float64) + dir_vox = _voxel_to_world_unit(dirs_ras, np.linalg.inv(affine)).astype(np.float64) + peak = _decode_array(entries["dpf/amplitude"]).astype(np.float64) if "dpf/amplitude" in entries else np.ones(len(dir_vox)) + integral = _decode_array(entries["dpf/afd"]).astype(np.float64) if "dpf/afd" in entries else peak.copy() + w_fix = _decode_array(entries["dpf/w_class"], squeeze_1d=False).astype(np.float64) if "dpf/w_class" in entries else None + w_unass = _decode_array(entries["dpv/w_unass"], squeeze_1d=False).astype(np.float64) if "dpv/w_unass" in entries else None + frow = np.repeat(np.arange(len(count), dtype=np.int64), count) + extras["lobes"] = Lobes( + count=count, + offset=offset, + direction=dir_vox, + peak=peak, + integral=integral, + peak_min=float(mpat_meta.get("lobes_peak_min", 0.1)), + merge_ratio=float(mpat_meta.get("lobes_merge_ratio", 0.8)), + _frow=frow, + _w_fix=w_fix, + _w_unass=w_unass, + ) + + if "groups/mpat_L_seeds" in entries: + lval_2d = _decode_array(entries["groups/mpat_L_lval"], squeeze_1d=False).astype(np.float64) + extras["launches"] = Launches( + seeds=_decode_array(entries["groups/mpat_L_seeds"], squeeze_1d=False).astype(np.int64), + seed_lin=_decode_array(entries["groups/mpat_L_seed_lin"]).astype(np.int64), + pair_seed=_decode_array(entries["groups/mpat_L_pair_seed"]).astype(np.int64), + pair_w=_decode_array(entries["groups/mpat_L_pair_w"]).astype(np.float64), + pair_d=_decode_array(entries["groups/mpat_L_pair_d"], squeeze_1d=False).astype(np.int64), + hseed=_decode_array(entries["groups/mpat_L_hseed"]).astype(np.int64), + lptr=_decode_array(entries["groups/mpat_L_lptr"]).astype(np.int64), + lkey=_decode_array(entries["groups/mpat_L_lkey"]).astype(np.int32), + lval=lval_2d, + dead=_decode_array(entries["groups/mpat_L_dead"]).astype(np.float64), + ) + + if "groups/mpat_whole_dc" in entries: + extras["whole_dc"] = _decode_array(entries["groups/mpat_whole_dc"], squeeze_1d=False).astype(np.float32) + + dpv_out = {} + for k, entry in entries.items(): + if k.startswith("dpv/"): + dpv_out[k[4:]] = _decode_array(entry, squeeze_1d=True) + extras["dpv"] = dpv_out + return chain, extras + + +def save_transitions_nifti( + chain: Chain, + prefix: Union[str, Path], + affine: Optional[np.ndarray] = None, +) -> Dict[str, str]: + """Write classic 4-D ``(X, Y, Z, 26)`` voxel-to-neighbour transition probabilities + (``_desc-transitions_dwimap.nii.gz`` + ``.json``) and 3-D ``codi`` and ``coasy`` + scalar NIfTI maps. + """ + prefix_str = str(prefix) + if affine is None: + affine = getattr(chain, "affine", np.eye(4)) + affine = np.asarray(affine, dtype=np.float64) + shape = tuple(int(s) for s in chain.shape) + t_ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), axis=1) - 1 + idx = tuple(t_ijk.T) + + m = marginal_transition_metrics(chain) + vol_4d = np.zeros(shape + (26,), dtype=np.float32) + vol_4d[idx] = m["p_neighbor"] + + trans_nii = f"{prefix_str}_desc-transitions_dwimap.nii.gz" + trans_json = f"{prefix_str}_desc-transitions_dwimap.json" + codi_nii = f"{prefix_str}_desc-codi_map.nii.gz" + coasy_nii = f"{prefix_str}_desc-coasy_map.nii.gz" + + Path(trans_nii).parent.mkdir(parents=True, exist_ok=True) + nib.save(nib.Nifti1Image(vol_4d, affine), trans_nii) + nib.save(nib.Nifti1Image(chain.to_volume(m["codi"]), affine), codi_nii) + nib.save(nib.Nifti1Image(chain.to_volume(m["coasy"]), affine), coasy_nii) + + sidecar = { + "Description": "Voxel-to-26-neighbour Markov transition probabilities", + "config": chain.cfg.key(), + "neighbor_offsets_ijk": OFFSETS.tolist(), + "neighbor_labels": neighbor_labels(affine), + "n_transient_voxels": int(chain.t_lin.size), + "n_states": int(chain.t_lin.size * chain.nb), + "n_transitions": int(chain.Q_w.size), + } + with open(trans_json, "w") as fh: + json.dump(sidecar, fh, indent=2) + + return { + "transitions": trans_nii, + "sidecar": trans_json, + "codi": codi_nii, + "coasy": coasy_nii, + } + + +def load_transitions_nifti( + nifti_path_or_prefix: Union[str, Path], + absorb_class: Optional[np.ndarray] = None, +) -> Chain: + """Build a 26-class :class:`mpat.Chain` directly from a 4-D ``(X, Y, Z, 26)`` transition + probability NIfTI (such as ``*_desc-transitions_dwimap.nii.gz`` or MITTENS ``*_double.nii.gz``). + + Each step from voxel ``v`` into neighbour ``n`` arrives in direction class ``n`` (``nb = 26``), + and outgoing hops from class ``b`` are gated by the turning cone (or unconstrained when + ``angle >= 180``). + """ + from scipy import ndimage + + p = Path(nifti_path_or_prefix) + meta = {} + if not p.exists(): + for suffix in ("_desc-transitions_dwimap.nii.gz", "_double.nii.gz", ".nii.gz"): + cand = Path(f"{nifti_path_or_prefix}{suffix}") + if cand.exists(): + p = cand + break + for js_cand in ( + Path(str(p).replace(".nii.gz", ".json").replace(".nii", ".json")), + Path(f"{nifti_path_or_prefix}_transitions.json"), + ): + if js_cand.exists(): + with open(js_cand) as fh: + meta = json.load(fh) + break + + img = nib.load(p) + vol_4d = np.asarray(img.dataobj, dtype=np.float64) + if vol_4d.ndim != 4 or vol_4d.shape[3] != 26: + raise ValueError(f"Expected 4-D (X, Y, Z, 26) transition NIfTI, got shape {vol_4d.shape}") + + shape = tuple(int(d) for d in vol_4d.shape[:3]) + pshape = tuple(s + 2 for s in shape) + affine = np.asarray(img.affine, dtype=np.float64) + zooms = tuple(float(z) for z in np.linalg.norm(affine[:3, :3], axis=0)) + + transient = np.any(vol_4d > 0, axis=-1) + if absorb_class is None: + dil = ndimage.binary_dilation(transient, np.ones((3, 3, 3), dtype=bool)) + absorb_class = np.where(dil & ~transient, 1, 0).astype(np.int8) + else: + absorb_class = np.asarray(absorb_class, dtype=np.int8) + + cfg_dict = dict(meta.get("config") or {}) + valid_cfg = {f.name for f in ChainConfig.__dataclass_fields__.values()} + cfg = ChainConfig(**{k: v for k, v in cfg_dict.items() if k in valid_cfg}) + + chain = Chain() + chain.cfg = cfg + chain.shape = shape + chain.pshape = pshape + chain.affine = affine + chain.noff = (OFFSETS @ np.array([pshape[1] * pshape[2], pshape[2], 1])).astype(np.int64) + chain.nb = 26 + + trans_p = np.zeros(pshape, dtype=bool) + trans_p[1:-1, 1:-1, 1:-1] = transient + cls_p = np.zeros(pshape, dtype=np.int8) + cls_p[1:-1, 1:-1, 1:-1] = absorb_class + label = np.zeros(pshape, dtype=np.int8) + label[cls_p > 0] = K.ABSORBING + label[cls_p == CSF] = K.BLOCKED + label[trans_p] = K.TRANSIENT + chain.label = label.ravel() + chain.t_lin = np.flatnonzero(trans_p.ravel()).astype(np.int64) + chain.tindex = np.full(label.size, -1, dtype=np.int64) + chain.tindex[chain.t_lin] = np.arange(chain.t_lin.size) + a_mask = ndimage.binary_dilation(trans_p, np.ones((3, 3, 3), dtype=bool)) & ~trans_p + chain.a_lin = np.flatnonzero(a_mask.ravel()).astype(np.int64) + chain.aindex = np.full(label.size, -1, dtype=np.int64) + chain.aindex[chain.a_lin] = np.arange(chain.a_lin.size) + chain.a_class = cls_p.ravel()[chain.a_lin].astype(np.int64) + chain.geo = build_geometry(zooms, cfg.angle, cfg.step, curv_sigma=cfg.curv_sigma) + + # Each outgoing hop n in 0..25 lands in arrival class n: template has 26 slots per class + Nt = int(chain.t_lin.size) + nb = 26 + chain.tmpl_n = np.broadcast_to(np.arange(26, dtype=np.int16)[None, :], (26, 26)).copy() + chain.tmpl_b = np.broadcast_to(np.arange(26, dtype=np.int16)[None, :], (26, 26)).copy() + + t_ijk = np.stack(np.unravel_index(chain.t_lin, pshape), axis=1) - 1 + p_rows = np.clip(vol_4d[tuple(t_ijk.T)], 0.0, None) + + # Precompute turning cone compatibility between incoming class b and outgoing step n + unit_off = OFFSETS * np.asarray(zooms, dtype=np.float64) + unit_off /= np.linalg.norm(unit_off, axis=1, keepdims=True) + cos_max = float(np.cos(np.deg2rad(max(cfg.angle, 45.0)))) + cone_ok = (unit_off @ unit_off.T) >= cos_max + + Ns = Nt * nb + Q_ptr = np.zeros(Ns + 1, dtype=np.int64) + R_ptr = np.zeros(Ns + 1, dtype=np.int64) + q_slot_l, q_w_l = [], [] + r_ind_l, r_val_l = [], [] + dead = np.zeros(Ns, dtype=np.float64) + + for v_idx in range(Nt): + v_lin = chain.t_lin[v_idx] + p_v = p_rows[v_idx] + for b in range(nb): + s = v_idx * nb + b + w_b = np.where(cone_ok[b], p_v, 0.0) + if w_b.sum() <= 0.0: + w_b = p_v.copy() + # Zero out blocked (CSF) neighbours and renormalize + for n in range(26): + if chain.label[v_lin + chain.noff[n]] == K.BLOCKED: + w_b[n] = 0.0 + tot = float(w_b.sum()) + if tot <= 0.0: + dead[s] = 1.0 + Q_ptr[s + 1] = len(q_w_l) + R_ptr[s + 1] = len(r_val_l) + continue + scale = min(1.0 / tot, 1.0) if tot > 1.0 else 1.0 / tot + w_b = w_b * scale + dead[s] = max(0.0, 1.0 - float(w_b.sum())) + r_map: Dict[int, float] = {} + for n in range(26): + w = float(w_b[n]) + if w <= 0.0: + continue + nb_lin = v_lin + chain.noff[n] + lb = chain.label[nb_lin] + if lb == K.TRANSIENT: + q_slot_l.append(n) + q_w_l.append(w) + elif lb == K.ABSORBING: + ai = int(chain.aindex[nb_lin]) + if ai >= 0: + r_map[ai] = r_map.get(ai, 0.0) + w + else: + dead[s] += w + for ai, rw in sorted(r_map.items()): + r_ind_l.append(ai) + r_val_l.append(rw) + Q_ptr[s + 1] = len(q_w_l) + R_ptr[s + 1] = len(r_val_l) + + chain.Q_ptr = Q_ptr + chain.Q_slot = np.asarray(q_slot_l, dtype=np.uint8) + chain.Q_w = np.asarray(q_w_l, dtype=np.float64) + chain.R_ptr = R_ptr + chain.R_ind = np.asarray(r_ind_l, dtype=np.int32) + chain.R_val = np.asarray(r_val_l, dtype=np.float64) + chain.dead = dead + chain.kill = None + chain._finalize() + return chain diff --git a/tests/test_transitions_io.py b/tests/test_transitions_io.py new file mode 100644 index 0000000..0044a60 --- /dev/null +++ b/tests/test_transitions_io.py @@ -0,0 +1,146 @@ +"""Tests for ODX (.odx) and NIfTI (.nii.gz) transition probability persistence and 3-D arbors.""" +from pathlib import Path + +import nibabel as nib +import numpy as np + +from mpat import ( + Chain, + ChainConfig, + extract_branch_arbor, + prepare_launches, + quantify_bundle, + segment_bundles, + segment_lobes, + write_arbor, +) + + +def _sh(directions, kappa=20.0): + from dipy.core.sphere import Sphere + from dipy.data import get_sphere + from dipy.reconst.shm import sh_to_sf_matrix + + sph = get_sphere(name="repulsion724") + _, inv = sh_to_sf_matrix(Sphere(xyz=sph.vertices), sh_order_max=8, return_inv=True) + sf = sum(np.exp(kappa * (sph.vertices @ np.asarray(d, float)) ** 2) for d in directions) + return (sf @ inv).astype(np.float32) + + +def test_transitions_odx_and_nifti_roundtrip(tmp_path: Path): + nx, ny, nz = 12, 10, 5 + zooms = (2.0, 2.0, 2.0) + affine = np.diag([2.0, 2.0, 2.0, 1.0]) + sh = np.zeros((nx, ny, nz, 45), dtype=np.float32) + transient = np.zeros((nx, ny, nz), dtype=bool) + absorb = np.zeros((nx, ny, nz), dtype=np.int8) + + sh_x = _sh([(1.0, 0.0, 0.0)], kappa=18.0) + transient[2:-2, 3:-3, 1:-1] = True + absorb[1, 3:-3, 1:-1] = 1 + absorb[-2, 3:-3, 1:-1] = 1 + absorb[2:-2, 2, 1:-1] = 1 + absorb[2:-2, -3, 1:-1] = 1 + + for i in range(1, nx - 1): + for j in range(2, ny - 2): + for k in range(1, nz - 1): + sh[i, j, k] = sh_x + + cfg = ChainConfig.ptt(angle=35.0, curv_sigma=18.0, probe_radius=0.5, stop_mass=1e-4) + odx_cache = tmp_path / "chain_cache.odx" + chain = Chain.build(sh, zooms, transient, absorb, cfg, cache=str(odx_cache)) + assert odx_cache.exists() + + # Verify cache hit from .odx + chain_cached = Chain.build(sh, zooms, transient, absorb, cfg, cache=str(odx_cache)) + assert chain_cached.n_transitions == chain.n_transitions + + seeds = np.argwhere(transient) + launches = prepare_launches(chain, seeds) + t_ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1 + sh_rows = sh[tuple(t_ijk.T)] + lobes = segment_lobes(sh_rows, chain.geo) + whole = segment_bundles(chain, [{"name": "whole"}], launches, tol=1e-6)["whole"] + + # Save full ODX with fixel lobes, launches, and whole_dc + odx_full = tmp_path / "sub-01_desc-transitions_dwimap.odx" + chain.save_odx( + odx_full, + affine=affine, + sh_rows=sh_rows, + lobes=lobes, + launches=launches, + whole_dc=whole.density_class, + quantize_weights=True, + ) + assert odx_full.exists() + + # Load directly from .odx without needing sh or recomputing launches/lobes + chain_loaded, extras = Chain.load_odx(odx_full, return_extras=True) + assert "lobes" in extras + assert "launches" in extras + assert "whole_dc" in extras + assert "codi" in extras["dpv"] + assert "coasy" in extras["dpv"] + assert "p_neighbor" in extras["dpv"] + assert extras["dpv"]["p_neighbor"].shape == (chain.t_lin.size, 26) + + start_mask = np.zeros((nx, ny, nz), dtype=bool) + start_mask[1, 3:-3, 1:-1] = True + end_mask = np.zeros((nx, ny, nz), dtype=bool) + end_mask[-2, 3:-3, 1:-1] = True + spec = {"name": "LeftArcuate", "start": start_mask, "end": end_mask, "include": []} + + res_orig = segment_bundles(chain, [spec], launches, tol=1e-6)["LeftArcuate"] + res_odx = segment_bundles(chain_loaded, [spec], extras["launches"], tol=1e-6)["LeftArcuate"] + np.testing.assert_allclose(res_odx.density_t, res_orig.density_t, rtol=1e-4, atol=1e-5) + np.testing.assert_allclose(res_odx.endpoints_a, res_orig.endpoints_a, rtol=1e-4, atol=1e-5) + + qb = quantify_bundle( + chain_loaded, + res_odx, + extras["whole_dc"], + sh_rows, + affine, + lobes=extras["lobes"], + compute_boundary_conductance=False, + ) + assert qb.tract_afd_volume_mm3 > 0.0 + + # Test 3-D multi-branch arbor extraction and .trx/.json/.tsv export + afd_vol = chain_loaded.to_volume(qb.voxel_afd_t) + ep_vol = chain_loaded.to_volume(res_odx.endpoints_a, "absorbing") + q_vol = chain_loaded.to_volume(qb.q_harmonic_t) + coh_vol = chain_loaded.to_volume(qb.flux_coherence_t) + keff_vol = chain_loaded.to_volume(qb.branching_k_eff_t) + + arbor = extract_branch_arbor( + afd_vol, + ep_vol, + affine, + q_vol=q_vol, + coherence_vol=coh_vol, + keff_vol=keff_vol, + start_mask=start_mask, + end_mask=end_mask, + bundle_name="LeftArcuate", + ) + ref_img = nib.Nifti1Image(afd_vol, affine) + tsv_p, trx_p, js_p = write_arbor(arbor, str(tmp_path / "sub-01_bundle-LeftArcuate"), ref_img) + assert Path(tsv_p).exists() + assert Path(trx_p).exists() + assert Path(js_p).exists() + + # Test classic 4-D (X, Y, Z, 26) NIfTI transition persistence & loading + nii_prefix = tmp_path / "sub-01" + nii_out = chain.save_nifti(nii_prefix, affine=affine) + assert Path(nii_out["transitions"]).exists() + assert Path(nii_out["sidecar"]).exists() + assert Path(nii_out["codi"]).exists() + assert Path(nii_out["coasy"]).exists() + + chain_from_nii = Chain.from_nifti(nii_out["transitions"], absorb_class=absorb) + assert chain_from_nii.t_lin.size == chain.t_lin.size + res_nii = segment_bundles(chain_from_nii, [spec], launches, tol=1e-5)["LeftArcuate"] + assert res_nii.info["expected_bundle_streamlines"] > 0.5 From a7b4a335e6515c8bee991d3981c45885145d3001 Mon Sep 17 00:00:00 2001 From: mattcieslak Date: Tue, 17 Nov 2026 12:52:51 -0500 Subject: [PATCH 2/5] Add mpat.trxviz_bridge for TRXViz's MPAT nodes build_transitions and solve_bundle subcommands read a TRXViz request JSON, report PROGRESS lines, and stream live density frames during the solve through a double-buffered memory map (STREAM_FRAME), so TRXViz can show the bundle forming. Transition caches are mpat_transitions_.npz. Flux streamlines and branch arbors are written as TRX, and extraction failures are reported in the result instead of leaving an empty bundle. --- src/mpat/trxviz_bridge.py | 1564 +++++++++++++++++++++++++++++++++++ tests/test_trxviz_bridge.py | 246 ++++++ 2 files changed, 1810 insertions(+) create mode 100644 src/mpat/trxviz_bridge.py create mode 100644 tests/test_trxviz_bridge.py diff --git a/src/mpat/trxviz_bridge.py b/src/mpat/trxviz_bridge.py new file mode 100644 index 0000000..6ae5a2d --- /dev/null +++ b/src/mpat/trxviz_bridge.py @@ -0,0 +1,1564 @@ +"""Bridge between TRXViz (Rust GUI) and MPAT + MITTENS (Python). + +Provides two subcommands invoked by TRXViz's background worker pool: +1. ``python -m mpat.trxviz_bridge build_transitions `` + Computes MITTENS v2 transition probability summary volumes (``codi_double``, + ``codi_single``, ``coasy``, ``p_terminate_double``, ``p_terminate_single``, + ``total_amplitude``, ``kl_single``) and builds/caches the 26-class MPAT + absorbing Markov chain, seed launches, fixel lobes, and whole-brain reference + density (plus ``chain_dead.nii``). + +2. ``python -m mpat.trxviz_bridge solve_bundle `` + Loads the cached transition state, applies pyAFQ-style ROIs plus arbitrary + user-wired Waypoint (``include``), Avoid (``exclude``), Limiting, Endpoint + (``start``/``end``), Absorption (``term_mask`` — including interior white-matter + absorption!), and No-End (``no_end_mask``) regions, solves the absorbing Markov + chain, computes all 7 quantitative 3-D volumes (``afd``, ``density``, ``tdimm``, + ``qharmonic``, ``coherence``, ``keff``, ``endpoints``), and extracts the 3-D + reactive-flux streamlines and branch arbor into ``bundle.trx``. + +Progress is streamed to stdout as ``PROGRESS `` lines so TRXViz can +render a live progress bar on the active workflow node. +""" +from __future__ import annotations + +import hashlib +import json +import os +import sys +import time +from dataclasses import replace +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple + +os.environ.setdefault("NUMBA_THREADING_LAYER", "workqueue") +os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE") + +import nibabel as nib +import numpy as np +from scipy import ndimage as ndi + +# Ensure sibling odx-rs/python is on sys.path if odx is not installed in the env +_cand_odx = Path(__file__).resolve().parents[3] / "odx" / "odx-rs" / "python" +if _cand_odx.is_dir() and str(_cand_odx) not in sys.path: + sys.path.insert(0, str(_cand_odx)) + + +def _emit_progress(done: int, total: int) -> None: + print(f"PROGRESS {int(done)} {int(total)}", flush=True) + + +class LiveDensityStreamer: + """Double-buffered memory-mapped 3-D volume streamer between MPAT and TRXViz.""" + + HEADER_BYTES = 128 + + def __init__(self, mmap_path: Path, chain, affine: np.ndarray, min_interval_sec: float = 0.04) -> None: + import struct + + self._struct = struct + self.path = Path(mmap_path) + self.shape = tuple(int(d) for d in chain.shape) + self.nvox = int(np.prod(self.shape)) + self.slot_bytes = self.nvox * 4 + self.total_bytes = self.HEADER_BYTES + 2 * self.slot_bytes + self.affine_f32 = np.asarray(affine, dtype=np.float32).reshape(16) + self.t_ijk = tuple((np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1).T) + self.seq = 0 + self.min_interval_sec = float(min_interval_sec) + self._last_emit = 0.0 + + with open(self.path, "wb") as fh: + fh.truncate(self.total_bytes) + self._mm = np.memmap(self.path, dtype=np.uint8, mode="r+", shape=(self.total_bytes,)) + self._write_header(0, 0, 0, 1.0, 0.0) + self._mm.flush() + + def _write_header(self, seq: int, phase: int, step: int, residual: float, max_val: float) -> None: + nx, ny, nz = self.shape + hdr = self._struct.pack( + "<8I2f16f6I", + 0x5441504D, # "MPAT" + 1, + int(seq), + int(phase), + int(step), + int(nx), + int(ny), + int(nz), + float(residual), + float(max_val), + *self.affine_f32.tolist(), + 0, 0, 0, 0, 0, 0, + ) + self._mm[: self.HEADER_BYTES] = np.frombuffer(hdr, dtype=np.uint8) + + def emit_transient_values( + self, + vals_t: np.ndarray, + phase: int, + step: int, + residual: float, + force: bool = False, + ) -> None: + now = time.perf_counter() + if not force and (now - self._last_emit) < self.min_interval_sec: + return + self._last_emit = now + next_seq = self.seq + 1 + slot_idx = next_seq % 2 + offset = self.HEADER_BYTES + slot_idx * self.slot_bytes + slot_vol = np.ndarray( + self.shape, + dtype=np.float32, + buffer=self._mm, + offset=offset, + order="F", + ) + slot_vol.fill(0.0) + v_clean = np.clip(np.nan_to_num(np.asarray(vals_t, dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0), 0.0, None) + slot_vol[self.t_ijk] = v_clean + max_val = float(v_clean.max()) if v_clean.size else 0.0 + self.seq = next_seq + self._write_header(self.seq, phase, step, residual, max_val) + self._mm.flush() + print( + f"STREAM_FRAME {self.seq} {int(phase)} {int(step)} {float(residual):.6e} {max_val:.6e}", + flush=True, + ) + + + +def _save_nifti(vol: np.ndarray, affine: np.ndarray, path: Path) -> str: + arr = np.nan_to_num(np.asarray(vol, dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0) + img = nib.Nifti1Image(arr, np.asarray(affine, dtype=np.float64)) + img.header.set_qform(affine, code=1) + img.header.set_sform(affine, code=1) + nib.save(img, str(path)) + return str(path) + + +def _resample_mask_to_grid(mask_img: nib.Nifti1Image, shape: Tuple[int, int, int], affine: np.ndarray) -> np.ndarray: + data = np.asarray(mask_img.dataobj) > 0 + if data.ndim > 3: + data = data[..., 0] + if data.shape == tuple(shape) and np.allclose(mask_img.affine, affine, atol=1e-3): + return data.astype(bool) + # Transform target grid coordinates (i, j, k) -> RAS -> source voxel coordinates + inv_src = np.linalg.inv(mask_img.affine) + M = inv_src @ affine + resampled = ndi.affine_transform( + data.astype(np.uint8), + M[:3, :3], + offset=M[:3, 3], + output_shape=tuple(shape), + order=0, + mode="constant", + cval=0, + ) + return resampled > 0 + + +def _discover_subject_inputs( + working_dir: Optional[str], + odx_path: Optional[str], + wm_threshold: float = 0.4, +) -> Tuple[np.ndarray, np.ndarray, Tuple[float, float, float], np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]]: + """Resolve ``(sh, affine, zooms, transient, absorb_class, dseg, wmgm_mask)`` from + either a staged ``.npz`` bundle, a pyAFQ/MPAT directory, or an ``.odx``/``.fib.gz``/``.nii.gz`` file. + """ + from .afq import _on_grid + + # Case 1: working_dir or odx_path points directly to a staged .npz subject file + for cand in (working_dir, odx_path): + if cand and Path(cand).is_file() and str(cand).endswith(".npz"): + z = np.load(cand) + if "sh" in z.files and "transient" in z.files and "absorb" in z.files: + sh = np.asarray(z["sh"], dtype=np.float32) + affine = np.asarray(z["affine"], dtype=np.float64) + zooms = tuple(float(x) for x in z["zooms"][:3]) + transient = np.asarray(z["transient"], dtype=bool) + absorb = np.asarray(z["absorb"], dtype=np.int8) + dseg = ( + np.asarray(z["dseg"], dtype=np.uint8) + if "dseg" in z.files + else np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) + ) + wmgm = None + if "seeds" in z.files: + wmgm = np.zeros(transient.shape, dtype=bool) + seeds = np.asarray(z["seeds"], dtype=np.int64) + if seeds.ndim == 2 and seeds.shape[1] == 3 and len(seeds) > 0: + wmgm[tuple(seeds.T)] = True + return sh, affine, zooms, transient, absorb, dseg, wmgm + + # Case 2: working_dir is a directory (pyAFQ derivatives or folder with NIfTIs / .npz) + sh_img = None + pve_img = None + dseg_img = None + bm_img = None + wmgm_img = None + + if working_dir and Path(working_dir).is_dir(): + wdir = Path(working_dir) + # Check if there is a staged subject .npz in the folder + npz_files = sorted(wdir.glob("*sub*.npz")) + if npz_files: + return _discover_subject_inputs(str(npz_files[0]), None, wm_threshold=wm_threshold) + + all_niis = sorted(wdir.rglob("*.nii*")) + for p in all_niis: + name = p.name.lower() + if sh_img is None and any( + tok in name for tok in ("model-csd", "model-msmt", "model-opdt", "model-rumba", "_fod", "_sh") + ) and not any(tok in name for tok in ("_fa", "_md", "_cfa", "visitodf")): + try: + img = nib.load(str(p)) + if img.ndim == 4 and img.shape[-1] in (15, 28, 45, 66): + sh_img = img + except Exception: + pass + elif pve_img is None and "pve" in name: + try: + img = nib.load(str(p)) + if img.ndim == 4 and img.shape[-1] == 3: + pve_img = img + except Exception: + pass + elif dseg_img is None and "desc-mpat_dseg" in name: + try: + dseg_img = nib.load(str(p)) + except Exception: + pass + elif bm_img is None and "brain_mask" in name: + try: + bm_img = nib.load(str(p)) + except Exception: + pass + elif wmgm_img is None and "wm_gm_interface" in name: + try: + wmgm_img = nib.load(str(p)) + except Exception: + pass + + # Case 3: odx_path (or working_dir as a single file) is an .odx, .fib.gz, .fz, or 4D SH .nii.gz + target_file = odx_path if (odx_path and Path(odx_path).exists()) else ( + working_dir if (working_dir and Path(working_dir).is_file()) else None + ) + if sh_img is None and target_file is not None: + tf = str(target_file) + if tf.endswith((".nii", ".nii.gz")): + sh_img = nib.load(tf) + else: + import mittens + from mittens.io import default_sphere, sh_basis_matrix + + odf_data = mittens.load_odf_data(tf) + dims = tuple(int(d) for d in odf_data.dims) + affine = np.asarray(odf_data.affine, dtype=np.float64) + zooms = tuple(float(x) for x in np.linalg.norm(affine[:3, :3], axis=0)) + if odf_data.kind == "sh": + n_coef = odf_data.odfs.shape[1] + # Ensure descoteaux07 symmetric lmax=8 (45 coeffs) for the MPAT Chain + sph = default_sphere() + B_src = sh_basis_matrix( + sph, + int(odf_data.sh_order or 8), + str(odf_data.sh_basis or "descoteaux07"), + bool(odf_data.full_basis), + ) + B_dst = sh_basis_matrix(sph, 8, "descoteaux07", False) + if odf_data.sh_basis == "descoteaux07" and not odf_data.full_basis and n_coef == 45: + sh_rows = np.asarray(odf_data.odfs, dtype=np.float32) + else: + proj = np.linalg.pinv(B_dst) @ B_src + sh_rows = (np.asarray(odf_data.odfs, dtype=np.float64) @ proj.T).astype(np.float32) + else: + # Sampled amplitudes on sphere -> project to descoteaux07 lmax=8 (45 coeffs) + verts = np.asarray(odf_data.vertices, dtype=np.float64) + amps = np.asarray(odf_data.odfs, dtype=np.float64) + if odf_data.hemisphere and amps.shape[1] * 2 == len(verts): + amps = np.hstack([amps, amps]) + B_dst = sh_basis_matrix(verts[: amps.shape[1]], 8, "descoteaux07", False) + pinv = np.linalg.pinv(B_dst) + sh_rows = (amps @ pinv.T).astype(np.float32) + + sh = np.zeros(dims + (sh_rows.shape[1],), dtype=np.float32) + sh[tuple(odf_data.ijk.T)] = sh_rows + sh_img = nib.Nifti1Image(sh, affine) + + if sh_img is None: + raise ValueError( + "Could not find fODF SH NIfTI, .odx, .fib.gz, or .npz in the specified working directory / ODF input." + ) + + sh = np.asarray(sh_img.dataobj, dtype=np.float32) + affine = np.asarray(sh_img.affine, dtype=np.float64) + zooms = tuple(float(x) for x in np.linalg.norm(affine[:3, :3], axis=0)) + mask = np.any(sh != 0, axis=-1) + if bm_img is not None: + mask &= _on_grid(bm_img, sh_img) > 0.5 + + if pve_img is not None: + csf, gm, wm = np.moveaxis(_on_grid(pve_img, sh_img), -1, 0) + edge = find_boundaries(mask, mode="inner") & mask + transient = mask & ~edge & (wm > float(wm_threshold)) + absorb = np.zeros(mask.shape, np.int8) + absorb[mask & ~transient & (gm >= csf)] = 1 + absorb[mask & ~transient & (gm < csf)] = 2 + absorb[edge] = 3 + cube = np.ones((3, 3, 3), bool) + lab, n_cc = ndi.label(transient, cube) + trapped = np.zeros(mask.shape, bool) + if n_cc: + ends = ndi.binary_dilation((absorb == 1) | (absorb == 3), cube) + reach = np.zeros(n_cc + 1, bool) + reach[np.unique(lab[ends & transient])] = True + trapped = transient & ~reach[lab] + if trapped.any(): + transient = transient & ~trapped + absorb[trapped] = 2 + dseg = np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) + dseg[trapped] = 5 + elif dseg_img is not None: + dseg = np.rint(_on_grid(dseg_img, sh_img, order=0)).astype(np.uint8) + if dseg.ndim == 4: + dseg = dseg[..., 0] + transient = dseg == 1 + absorb = np.zeros(dseg.shape, dtype=np.int8) + absorb[dseg == 2] = 1 + absorb[dseg == 3] = 2 + absorb[dseg == 4] = 3 + absorb[dseg == 5] = 2 + else: + # Derive transient WM and absorbing boundary directly from the ODF mask & c0 amplitude + edge = mask & ~ndi.binary_erosion(mask) + c0 = sh[..., 0] + pos_c0 = c0[mask & ~edge] + thresh = float(np.percentile(pos_c0, 20.0)) if pos_c0.size else 0.0 + transient = mask & ~edge & (c0 >= thresh) + absorb = np.zeros(mask.shape, dtype=np.int8) + absorb[mask & ~transient] = 1 + absorb[edge] = 3 + dseg = np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) + + wmgm = None + if wmgm_img is not None: + wmgm = (_on_grid(wmgm_img, sh_img, order=0) > 0) & transient + + return sh, affine, zooms, transient, absorb, dseg, wmgm + + +def _compute_transitions_hash( + cfg_key: dict, + max_length_mm: float, + sh: np.ndarray, + affine: np.ndarray, + transient: np.ndarray, + absorb: np.ndarray, +) -> str: + """Compute a deterministic 16-hex-char SHA-1 hash of all transition inputs & parameters.""" + h = hashlib.sha1() + meta = dict(cfg_key) + meta["max_length_mm"] = round(float(max_length_mm), 3) + meta["sh_shape"] = list(sh.shape) + h.update(json.dumps(meta, sort_keys=True).encode()) + h.update(np.ascontiguousarray(affine, dtype=np.float64).tobytes()) + h.update(np.ascontiguousarray(transient, dtype=np.uint8).tobytes()) + h.update(np.ascontiguousarray(absorb, dtype=np.int8).tobytes()) + # Fast strided sample of c0 ODF values to distinguish subjects with identical grid geometry + h.update(np.ascontiguousarray(sh[::4, ::4, ::4, 0], dtype=np.float32).tobytes()) + return h.hexdigest()[:16] + + +def _export_volumes_from_cached_state( + z_st, + out_dir: Path, +) -> Tuple[Dict[str, str], Tuple[int, int, int], np.ndarray, int, int, int]: + """Write the 8 3D NIfTI volumes from a loaded ``mpat_transitions_*.npz`` archive.""" + shape = tuple(int(s) for s in z_st["shape"]) + pshape = tuple(int(s) for s in z_st["pshape"]) + affine = np.asarray(z_st["affine"], dtype=np.float64) + t_lin = np.asarray(z_st["t_lin"], dtype=np.int64) + dead_mean = np.asarray(z_st["dead"], dtype=np.float32).reshape(-1, int(z_st["nb"])).mean(axis=1) + + volume_paths: Dict[str, str] = {} + mit_ijk = np.asarray(z_st["mit_ijk"], dtype=np.int64) if "mit_ijk" in z_st.files else None + for map_key in ( + "codi_double", + "codi_single", + "coasy", + "p_terminate_double", + "p_terminate_single", + "total_amplitude", + "kl_single", + ): + vol = np.zeros(shape, dtype=np.float32) + arr_key = f"mit_{map_key}" + if mit_ijk is not None and arr_key in z_st.files: + vals = np.asarray(z_st[arr_key], dtype=np.float32) + vol[tuple(mit_ijk.T)] = np.nan_to_num(vals, nan=0.0, posinf=0.0, neginf=0.0) + volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") + + dead_vol = np.zeros(int(np.prod(pshape)), dtype=np.float32) + dead_vol[t_lin] = dead_mean + dead_vol = dead_vol.reshape(pshape)[1:-1, 1:-1, 1:-1] + volume_paths["chain_dead"] = _save_nifti(dead_vol, affine, out_dir / "chain_dead.nii") + + n_wm = int(t_lin.size) + n_states = int(z_st["dead"].size) + n_trans = int(z_st["Q_w"].size) + return volume_paths, shape, affine, n_wm, n_states, n_trans + + +def cmd_build_transitions(req_path: str) -> None: + """Execute ``build_transitions`` and emit ``RESULT ``.""" + import mittens + from mittens.io import OdfData + + from .chain import Chain, ChainConfig + from .fixels import segment_lobes + from .solve import overlength_states, prepare_launches, segment_bundles + + t_start = time.perf_counter() + with open(req_path, "r") as fh: + req = json.load(fh) + + out_dir = Path(req["out_dir"]) + out_dir.mkdir(parents=True, exist_ok=True) + + _emit_progress(1, 6) + + # Fast path 0: Did the user point working_dir or odx_path directly at a precomputed + # mpat_transitions_*.npz (or *_transitions_dwimap.odx) archive? + for direct_cand in (req.get("working_dir"), req.get("odx_path")): + if not direct_cand or not Path(direct_cand).exists(): + continue + if Path(direct_cand).is_file() and str(direct_cand).endswith(".npz"): + z_try = np.load(direct_cand) + if "Q_ptr" in z_try.files and "L_seeds" in z_try.files and "shape" in z_try.files: + _emit_progress(5, 6) + volume_paths, shape, affine, n_wm, n_states, n_trans = _export_volumes_from_cached_state( + z_try, out_dir + ) + _emit_progress(6, 6) + elapsed = time.perf_counter() - t_start + fp_h = str(z_try["fp_hash"]) if "fp_hash" in z_try.files else "" + result = { + "state_path": str(Path(direct_cand).resolve()), + "fp_hash": fp_h, + "dims": list(shape), + "voxel_to_ras": affine.tolist(), + "volumes": volume_paths, + "summary": ( + f"Loaded [{Path(direct_cand).name}]: " + f"{n_wm:,} WM voxels ({n_states:,} states, {n_trans / 1e6:.1f}M transitions) in {elapsed:.1f}s" + ), + } + with open(out_dir / "transitions_result.json", "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + return + elif str(direct_cand).endswith((".odx", ".odxd")): + from .transitions import load_transitions_odx + + try: + chain_odx, extras = load_transitions_odx(direct_cand, return_extras=True) + except Exception: # noqa: BLE001 + chain_odx, extras = None, None + if chain_odx is not None and extras is not None and "launches" in extras: + _emit_progress(5, 6) + affine = extras["affine"] + shape = chain_odx.shape + dpv = extras.get("dpv") or {} + volume_paths = {} + for map_key, fallback_key in ( + ("codi_double", "codi"), + ("codi_single", "codi"), + ("coasy", "coasy"), + ("p_terminate_double", "p_absorb"), + ("p_terminate_single", "p_absorb"), + ("total_amplitude", "p_absorb"), + ("kl_single", "codi"), + ): + vals = dpv.get(map_key) + if vals is None: + vals = dpv.get(fallback_key, np.zeros(chain_odx.t_lin.size, dtype=np.float32)) + vol = chain_odx.to_volume(np.asarray(vals, dtype=np.float32).ravel()) + volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") + dead_mean = dpv.get( + "dead_mean", + chain_odx.dead.reshape(-1, chain_odx.nb).mean(axis=1).astype(np.float32), + ) + volume_paths["chain_dead"] = _save_nifti( + chain_odx.to_volume(np.asarray(dead_mean, dtype=np.float32).ravel()), + affine, + out_dir / "chain_dead.nii", + ) + _emit_progress(6, 6) + elapsed = time.perf_counter() - t_start + fp_h = str((extras["header"].get("mpat") or {}).get("fingerprint", "")) + result = { + "state_path": str(Path(direct_cand).resolve()), + "fp_hash": fp_h, + "dims": list(shape), + "voxel_to_ras": affine.tolist(), + "volumes": volume_paths, + "summary": ( + f"Loaded ODX [{Path(direct_cand).name}]: " + f"{chain_odx.t_lin.size:,} WM voxels ({chain_odx.n_states:,} states, " + f"{chain_odx.n_transitions / 1e6:.1f}M transitions) in {elapsed:.1f}s" + ), + } + with open(out_dir / "transitions_result.json", "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + return + + wm_threshold = float(req.get("wm_threshold", 0.4)) + sh, affine, zooms, transient, absorb, dseg, wmgm = _discover_subject_inputs( + req.get("working_dir"), + req.get("odx_path"), + wm_threshold=wm_threshold, + ) + shape = tuple(int(d) for d in transient.shape) + + # Apply optional user-wired transient or absorbing masks + if req.get("transient_mask_path") and Path(req["transient_mask_path"]).exists(): + t_override = _resample_mask_to_grid(nib.load(req["transient_mask_path"]), shape, affine) + if t_override.any(): + transient = t_override & np.any(sh != 0, axis=-1) + absorb[transient] = 0 + absorb[(absorb == 0) & np.any(sh != 0, axis=-1) & ~transient] = 1 + + if req.get("absorb_mask_path") and Path(req["absorb_mask_path"]).exists(): + a_override = _resample_mask_to_grid(nib.load(req["absorb_mask_path"]), shape, affine) + if a_override.any(): + transient = transient & ~a_override + absorb[a_override] = 1 + + _emit_progress(2, 6) + + preset = str(req.get("preset", "standard")).lower() + angle_deg = float(req.get("angle_deg", 35.0)) + step_vox = float(req.get("step_vox", 1.0)) + double_odf = bool(req.get("double_odf", True)) + fod_thresh = float(req.get("fod_thresh", 0.08 if preset == "ptt" else 0.05)) + fod_power = float(req.get("fod_power", 1.5 if preset == "ptt" else 1.0)) + stop_mass_tau = float(req.get("stop_mass_tau", 1e-4 if preset == "ptt" else 0.0)) + curv_sigma_deg = float(req.get("curv_sigma_deg", 18.0 if preset == "ptt" else 0.0)) + probe_radius_vox = float(req.get("probe_radius_vox", 0.5 if preset == "ptt" else 0.0)) + max_length_mm = float(req.get("max_length_mm", 250.0)) + + cfg = ChainConfig( + angle=angle_deg, + step=step_vox, + double_odf=double_odf, + stop_mass=stop_mass_tau, + fod_thresh=fod_thresh, + fod_power=fod_power, + curv_sigma=curv_sigma_deg, + probe_radius=probe_radius_vox, + ) + fp_hash = _compute_transitions_hash(cfg.key(), max_length_mm, sh, affine, transient, absorb) + hashed_filename = f"mpat_transitions_{fp_hash}.npz" + + # Determine where to look for / save the hashed transitions file: + # Prefer the subject's working_dir (if a directory) or parent of odx_path, falling back to cache_dir. + fallback_cache_dir = Path(req.get("cache_dir") or out_dir.parent) + fallback_cache_dir.mkdir(parents=True, exist_ok=True) + + candidate_dirs = [] + if req.get("working_dir"): + wp = Path(req["working_dir"]) + if wp.is_dir(): + candidate_dirs.append(wp) + elif wp.parent.is_dir(): + candidate_dirs.append(wp.parent) + if req.get("odx_path"): + op = Path(req["odx_path"]) + if op.parent.is_dir(): + candidate_dirs.append(op.parent) + candidate_dirs.append(fallback_cache_dir) + + state_cache_path = None + for cdir in candidate_dirs: + p = cdir / hashed_filename + if p.exists(): + state_cache_path = p + break + if state_cache_path is None: + # Pick the first writable directory (preferring subject working_dir so the hashed .npz stays with the dataset) + for cdir in candidate_dirs: + if os.access(cdir, os.W_OK): + state_cache_path = cdir / hashed_filename + break + if state_cache_path is None: + state_cache_path = fallback_cache_dir / hashed_filename + + # Fast path 1: Hashed transitions archive already exists on disk! + if state_cache_path.exists(): + _emit_progress(5, 6) + z_st = np.load(state_cache_path) + if "mit_ijk" in z_st.files and "Q_ptr" in z_st.files: + volume_paths, _, _, n_wm, n_states, n_trans = _export_volumes_from_cached_state(z_st, out_dir) + _emit_progress(6, 6) + elapsed = time.perf_counter() - t_start + result = { + "state_path": str(state_cache_path), + "fp_hash": fp_hash, + "dims": list(shape), + "voxel_to_ras": affine.tolist(), + "volumes": volume_paths, + "summary": ( + f"Cached [{state_cache_path.name}]: {n_wm:,} WM voxels " + f"({n_states:,} states, {n_trans / 1e6:.1f}M transitions) in {elapsed:.1f}s" + ), + } + with open(out_dir / "transitions_result.json", "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + return + + # Full build path: + # 1. Compute MITTENS v2 transition probability maps across the active mask + min_zoom = float(min(zooms)) + step_mm = float(step_vox * min_zoom) + turning = "vmf" if curv_sigma_deg > 0.0 else "flat" + sigma_rad = max(np.deg2rad(curv_sigma_deg), 0.05) + persistence_mm = float(step_mm * (sigma_rad ** 2)) + + odf_mask = (transient | (absorb == 1) | (absorb == 3)) & np.any(sh != 0, axis=-1) + ijk_odf = np.argwhere(odf_mask) + n_coef = int(sh.shape[-1]) + sh_order_sym = int(round((-3.0 + np.sqrt(1.0 + 8.0 * n_coef)) / 2.0)) + if (sh_order_sym + 1) * (sh_order_sym + 2) // 2 == n_coef: + sh_order = sh_order_sym + full_basis = False + else: + sh_order = int(round(np.sqrt(n_coef) - 1.0)) + full_basis = True + odf_data = OdfData.from_sh( + sh[tuple(ijk_odf.T)], + ijk_odf, + shape, + affine, + sh_order=sh_order, + sh_basis="descoteaux07", + full_basis=full_basis, + ) + t_model = mittens.TransitionModel( + step_mm=step_mm, + angle_max=angle_deg, + turning=turning, + persistence_length_mm=persistence_mm, + tau=stop_mass_tau, + tau0=stop_mass_tau, + odf_power=fod_power, + ) + t_res = t_model.fit(odf_data) + m_maps = dict(t_res.maps()) + m_maps["kl_single"] = t_res.kl_single + + volume_paths: Dict[str, str] = {} + mit_arrays: Dict[str, np.ndarray] = {"mit_ijk": np.asarray(t_res.ijk, dtype=np.int32)} + for map_key in ( + "codi_double", + "codi_single", + "coasy", + "p_terminate_double", + "p_terminate_single", + "total_amplitude", + "kl_single", + ): + vals = np.nan_to_num(np.asarray(m_maps[map_key], dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0) + mit_arrays[f"mit_{map_key}"] = vals + vol = np.zeros(shape, dtype=np.float32) + vol[tuple(t_res.ijk.T)] = vals + volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") + + _emit_progress(3, 6) + + # 2. Build or load the 26-class MPAT absorbing Markov chain + chain_cache_path = state_cache_path.parent / f"mpat_chain_{fp_hash}.npz" + + chain = Chain.build(sh, zooms, transient, absorb, cfg, cache=str(chain_cache_path)) + _emit_progress(4, 6) + + if max_length_mm > 0: + kill, _, _ = overlength_states(chain, max_length_mm, zooms) + chain.kill = kill if kill.any() else None + else: + chain.kill = None + + # Prepare launches for ALL transient WM voxels so any downstream custom seed_mask works in O(1) + all_wm_seeds = np.argwhere(transient) + launches = prepare_launches(chain, all_wm_seeds) + chain.release_pmfs() + + # Default seed mask is wm_gm_interface if available, else all transient WM + if wmgm is not None and wmgm.any(): + default_seed_ok = wmgm[tuple(all_wm_seeds.T)] + else: + default_seed_ok = np.ones(len(all_wm_seeds), dtype=bool) + + _emit_progress(5, 6) + t_ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1 + sh_rows = np.ascontiguousarray(sh[tuple(t_ijk.T)], dtype=np.float32) + lobes = segment_lobes(sh_rows, chain.geo) + + # Solve unconditioned whole-brain density using default seeds for AFD attribution + launches_def = replace( + launches, + pair_w=launches.pair_w * default_seed_ok[launches.pair_seed].astype(np.float64), + ) + whole = segment_bundles( + chain, + [{"name": "whole_brain"}], + launches_def, + tol=1e-5, + accel="mr", + )["whole_brain"] + + dead_mean = chain.dead.reshape(-1, chain.nb).mean(axis=1).astype(np.float32) + dead_vol = chain.to_volume(dead_mean) + volume_paths["chain_dead"] = _save_nifti(dead_vol, affine, out_dir / "chain_dead.nii") + + np.savez( + state_cache_path, + fp_hash=np.array(fp_hash), + cfg_json=np.array(json.dumps(cfg.key())), + shape=np.array(shape, dtype=np.int64), + pshape=np.array(chain.pshape, dtype=np.int64), + affine=affine, + zooms=np.array(zooms, dtype=np.float64), + label=chain.label, + t_lin=chain.t_lin, + tindex=chain.tindex, + a_lin=chain.a_lin, + aindex=chain.aindex, + a_class=chain.a_class, + noff=chain.noff, + nb=np.array(chain.nb, dtype=np.int64), + Q_ptr=chain.Q_ptr, + Q_slot=chain.Q_slot, + Q_w=chain.Q_w, + R_ptr=chain.R_ptr, + R_ind=chain.R_ind, + R_val=chain.R_val, + dead=chain.dead, + tmpl_n=chain.tmpl_n, + tmpl_b=chain.tmpl_b, + kill=chain.kill if chain.kill is not None else np.zeros(0, dtype=bool), + vbin=chain.geo.vbin, + # Launches fields + L_seeds=launches.seeds, + L_seed_lin=launches.seed_lin, + L_pair_seed=launches.pair_seed, + L_pair_w=launches.pair_w, + L_pair_d=launches.pair_d, + L_hseed=launches.hseed, + L_lptr=launches.lptr, + L_lkey=launches.lkey, + L_lval=launches.lval, + L_dead=launches.dead, + default_seed_ok=default_seed_ok, + # Fixel lobes & whole-brain reference + sh_rows=sh_rows, + lobes_frow=lobes._frow, + lobes_w_fix=lobes._w_fix, + lobes_w_unass=lobes._w_unass, + lobes_dir=lobes.direction, + lobes_peak=lobes.peak, + lobes_integral=lobes.integral, + whole_dc=whole.density_class.astype(np.float32), + # MITTENS 3D scalar maps + **mit_arrays, + ) + n_states = int(chain.n_states) + n_trans = int(chain.n_transitions) + + _emit_progress(6, 6) + elapsed = time.perf_counter() - t_start + result = { + "state_path": str(state_cache_path), + "fp_hash": fp_hash, + "dims": list(shape), + "voxel_to_ras": affine.tolist(), + "volumes": volume_paths, + "summary": ( + f"Saved [{hashed_filename}]: {int(transient.sum()):,} WM voxels " + f"({n_states:,} states, {n_trans / 1e6:.1f}M transitions) in {elapsed:.1f}s" + ), + } + res_path = out_dir / "transitions_result.json" + with open(res_path, "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + + +def _reconstruct_state(state_path: str): + """Fast O(1) reconstruction of ``(chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms)`` + from ``mpat_transitions_*.npz`` or ``*_transitions_dwimap.odx`` without rebuilding geometry or ODF integrals. + """ + from . import kernel as K + from .chain import Chain, ChainConfig + from .fixels import Lobes, _sh_fingerprint, segment_lobes + from .geometry import build_geometry + from .solve import Launches + + if str(state_path).endswith((".odx", ".odxd")): + from .transitions import load_transitions_odx + + chain, extras = load_transitions_odx(state_path, return_extras=True) + affine = extras["affine"] + zooms = extras["zooms"] + launches = extras["launches"] + default_seed_ok = np.ones(len(launches.seeds), dtype=bool) + sh_rows = extras.get("sh_rows") + if sh_rows is None: + sh_rows = np.zeros((chain.t_lin.size, 45), dtype=np.float32) + lobes = extras.get("lobes") + if lobes is None: + lobes = segment_lobes(sh_rows, chain.geo) + else: + lobes._sh_fp = _sh_fingerprint(sh_rows) + whole_dc = extras.get("whole_dc") + if whole_dc is None: + whole_dc = np.ones((chain.t_lin.size, chain.nb), dtype=np.float32) + return chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms + + z = np.load(state_path) + cfg_dict = json.loads(str(z["cfg_json"])) + cfg = ChainConfig(**cfg_dict) + shape = tuple(int(x) for x in z["shape"]) + pshape = tuple(int(x) for x in z["pshape"]) + affine = np.asarray(z["affine"], dtype=np.float64) + zooms = tuple(float(x) for x in z["zooms"]) + + chain = Chain() + chain.cfg = cfg + chain.shape = shape + chain.pshape = pshape + chain.label = z["label"] + chain.t_lin = z["t_lin"] + chain.tindex = z["tindex"] + chain.a_lin = z["a_lin"] + chain.aindex = z["aindex"] + chain.a_class = z["a_class"] + chain.noff = z["noff"] + chain.nb = int(z["nb"]) + chain.Q_ptr = z["Q_ptr"] + chain.Q_slot = z["Q_slot"] + chain.Q_w = z["Q_w"] + chain.R_ptr = z["R_ptr"] + chain.R_ind = z["R_ind"] + chain.R_val = z["R_val"] + chain.dead = z["dead"] + chain.tmpl_n = z["tmpl_n"] + chain.tmpl_b = z["tmpl_b"] + kill_arr = z["kill"] + chain.kill = kill_arr if kill_arr.size > 0 else None + chain._finalize() + + # Lightweight geometry proxy holding vbin (and full geo only if needed) + class _GeoProxy: + pass + + geo = _GeoProxy() + geo.nb = chain.nb + geo.vbin = z["vbin"] + chain.geo = geo + + launches = Launches( + seeds=z["L_seeds"], + seed_lin=z["L_seed_lin"], + pair_seed=z["L_pair_seed"], + pair_w=z["L_pair_w"], + pair_d=z["L_pair_d"], + hseed=z["L_hseed"], + lptr=z["L_lptr"], + lkey=z["L_lkey"], + lval=z["L_lval"], + dead=z["L_dead"], + ) + default_seed_ok = np.asarray(z["default_seed_ok"], dtype=bool) + sh_rows = z["sh_rows"] + frow = z["lobes_frow"] + n_vox = len(sh_rows) + counts = ( + np.bincount(frow, minlength=n_vox).astype(np.int64) + if frow.size + else np.zeros(n_vox, dtype=np.int64) + ) + offset = ( + np.concatenate([[0], np.cumsum(counts)[:-1]]).astype(np.int64) + if counts.size + else counts + ) + w_unass = ( + z["lobes_w_unass"] + if "lobes_w_unass" in z.files + else np.zeros((n_vox, chain.nb), dtype=np.float64) + ) + lobes = Lobes( + count=counts, + offset=offset, + direction=z["lobes_dir"], + peak=z["lobes_peak"], + integral=z["lobes_integral"], + peak_min=0.1, + merge_ratio=0.8, + _frow=frow, + _w_fix=z["lobes_w_fix"], + _w_unass=w_unass, + _sh_fp=_sh_fingerprint(sh_rows), + ) + whole_dc = z["whole_dc"] + return chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms + + +def _solve_bundle_with_custom_regions( + chain, + launches, + spec: Dict[str, Any], + term_mask: Optional[np.ndarray], + no_end_mask: Optional[np.ndarray], + tol: float = 1e-6, + accel: Any = "mr", + use_cascade: bool = True, + streamer: Optional[LiveDensityStreamer] = None, +): + """Solve a bundle specification with support for: + - ``include`` (waypoint ROIs), + - ``exclude`` (avoid ROIs + outside of limiting_mask), + - ``start`` / ``end`` (endpoint ROIs), + - ``term_mask`` (arbitrary absorption ROIs — including interior white-matter voxels!), + - ``no_end_mask`` (forbidden absorption ROIs where walkers may not terminate). + """ + from . import kernel as K + from .chain import VALID_ENDS + from .solve import BundleResult, _endpoint_kinds, _Plan, _solve + + has_custom_term = term_mask is not None and np.any(term_mask) + has_no_end = no_end_mask is not None and np.any(no_end_mask) + + # Check if start or end mask is placed inside interior transient WM with no boundary overlap + pad = np.zeros(chain.pshape, dtype=bool) + + def _padded(m: np.ndarray) -> np.ndarray: + p = pad.copy() + p[1:-1, 1:-1, 1:-1] = m + return p.ravel() + + a_valid = np.isin(chain.a_class, np.asarray(VALID_ENDS)) + interior_absorb = np.zeros(chain.shape, dtype=bool) + if has_custom_term: + interior_absorb |= np.asarray(term_mask, dtype=bool) + a_valid = a_valid | _padded(term_mask)[chain.a_lin] + + for k in ("start", "end"): + m = spec.get(k) + if m is not None and np.any(m): + m_pad = _padded(m) + # If a user-supplied start/end ROI has no valid boundary absorbing voxels (e.g. a 3D sphere + # placed inside subcortical white matter), make its interior voxels absorbing automatically! + if not np.any(m_pad[chain.a_lin] & a_valid): + interior_absorb |= np.asarray(m, dtype=bool) + a_valid = a_valid | m_pad[chain.a_lin] + + # General exact solver supporting arbitrary interior absorption (term_mask), no_end_mask, and N waypoints + p = _Plan(chain, spec, VALID_ENDS) + nb, Ns, nc = chain.nb, chain.n_states, chain.ncomp + + # Recompute endpoint kinds if a_valid or no_end_mask or term_mask modified valid endpoints + ends = [_padded(spec[k])[chain.a_lin] if spec.get(k) is not None else None for k in ("start", "end")] + if has_custom_term: + t_a = _padded(term_mask)[chain.a_lin] + # Allow absorption in term_mask to satisfy endpoint completion + if ends[0] is not None and ends[1] is not None: + ends[1] = ends[1] | t_a + elif ends[0] is not None: + ends[0] = ends[0] | t_a + elif ends[1] is not None: + ends[1] = ends[1] | t_a + + if has_no_end: + ne_a = _padded(no_end_mask)[chain.a_lin] + a_valid = a_valid & ~ne_a + + kinds, p.M, p.end_rule = _endpoint_kinds(a_valid, *ends) + p.nK = len(kinds) + p.C = p.nX * p.nK + p.xcol = np.repeat(np.arange(p.nX), p.nK) + p.kcol = np.tile(np.arange(p.nK), p.nX) + p.absw = np.stack( + [kinds[p.kcol[c]] & ~p.taboo[chain.a_lin, p.xcol[c]] for c in range(p.C)], + axis=1, + ).astype(np.float64) + + # Interior absorption on transient voxels (term_t) + int_pad = _padded(interior_absorb) + if has_no_end: + int_pad &= ~_padded(no_end_mask) + term_t = int_pad[chain.t_lin] + has_int_abs = bool(np.any(term_t)) + + r_rhs = chain.absorb_rhs(p.absw) + if has_int_abs: + term_state = np.repeat(term_t, nb) + # Stop walkers upon reaching term_state (they absorb rather than stepping out) + p.mask[term_state, :] = 0 + + # Determine endpoint kind weights for interior absorbing voxels on chain.t_lin + ends_t = [_padded(spec[k])[chain.t_lin] if spec.get(k) is not None else None for k in ("start", "end")] + if has_custom_term: + t_t = _padded(term_mask)[chain.t_lin] + if ends_t[0] is not None and ends_t[1] is not None: + ends_t[1] = ends_t[1] | t_t + elif ends_t[0] is not None: + ends_t[0] = ends_t[0] | t_t + elif ends_t[1] is not None: + ends_t[1] = ends_t[1] | t_t + kinds_t, _, _ = _endpoint_kinds(term_t, *ends_t) + term_absw_t = np.stack( + [kinds_t[p.kcol[c]] & ~p.taboo[chain.t_lin, p.xcol[c]] for c in range(p.C)], + axis=1, + ).astype(np.float64) + term_absw_s = np.repeat(term_absw_t, nb, axis=0) + q_into_term = np.empty_like(r_rhs) + chain.mul_backward(np.ascontiguousarray(term_absw_s), q_into_term) + r_rhs = r_rhs + q_into_term + + mask = p.mask.copy() + r_rhs *= mask + Nt = chain.t_lin.size + colsign = p.signs[p.xcol] + log_tol = float(np.log10(max(tol, 1e-12))) + + def _on_bwd_step(it: int, res: float, total: np.ndarray, term: np.ndarray) -> None: + if streamer is not None and (it == 1 or it % 2 == 0): + # Wave front at power iteration step t from start & end ROIs (columns 0..nK) + w_step = np.clip(term[::nc, : p.nK].sum(1).reshape(Nt, nb).mean(1), 0.0, None) + w_max = float(w_step.max()) + if w_max > 1e-20: + w_step = w_step / w_max + # Waypoint-conditioned accumulated backward hitting probability + b_cond = np.clip((total[::nc] @ colsign).reshape(Nt, nb).mean(1), 0.0, None) + b_max = float(b_cond.max()) + if b_max > 1e-20: + b_cond = b_cond / b_max + b_vis = 0.60 * b_cond + 0.40 * w_step + else: + b_vis = w_step + streamer.emit_transient_values(b_vis, phase=1, step=it, residual=res, force=True) + frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 + _emit_progress(int(round(frac * 100)), 200) + if getattr(streamer, "pace_sec", 0.0) > 0.0: + time.sleep(streamer.pace_sec) + + bwd_accel = False if (streamer is not None and getattr(streamer, "pace_sec", 0.0) > 0.0) else accel + beta, info_b = _solve( + chain, r_rhs, mask, tol, 5000, "backward", verbose=False, accel=bwd_accel, on_step=_on_bwd_step + ) + if has_int_abs: + beta[term_state, :] = term_absw_s[term_state, :] + + P = launches.pair_seed.size + seed_ok = (~p.taboo[launches.hseed][:, p.xcol]).astype(np.float64) + vals = np.empty((launches.hseed.size, p.C), dtype=np.float64) + K.half_values( + launches.hseed, + launches.lptr, + launches.lkey, + launches.lval, + chain.label, + chain.noff, + chain.tindex, + chain.aindex, + nb, + np.ascontiguousarray(beta), + p.absw, + seed_ok, + vals, + ) + V = vals.reshape(P, 2, p.nX, p.nK) + pb = np.einsum("pxk,kl,pxl->px", V[:, 0], p.M, V[:, 1]) @ p.signs + seed_prob = np.bincount(launches.pair_seed, weights=launches.pair_w * pb, minlength=len(launches.seeds)) + coef = np.einsum("phxl,kl->phxk", V[:, ::-1], p.M).reshape(2 * P, p.C) + coef *= np.repeat(launches.pair_w, 2)[:, None] * seed_ok + pi0 = np.zeros((Ns * nc, p.C), dtype=np.float64) + a0 = np.zeros((chain.a_lin.size, p.C), dtype=np.float64) + K.scatter_init( + launches.hseed, + launches.lptr, + launches.lkey, + launches.lval, + coef, + chain.label, + chain.noff, + chain.tindex, + chain.aindex, + nb, + p.taboo, + p.xcol, + pi0, + a0, + ) + if has_int_abs: + a0_term_s = pi0[term_state, :].copy() + pi0[term_state, :] = 0.0 + if getattr(chain, "kill", None) is not None: + pi0[np.repeat(chain.kill, nc)] = 0.0 + + beta_c = np.ascontiguousarray(beta) + + def _on_fwd_step(it: int, res: float, total: np.ndarray, term: np.ndarray) -> None: + if streamer is not None and (it == 1 or it % 2 == 0): + d_tot = np.clip( + K.paired_density(np.ascontiguousarray(total), beta_c, colsign, Ns, nc).reshape(Nt, nb).sum(1), + 0.0, + None, + ) + d_wave = np.clip( + K.paired_density(np.ascontiguousarray(term), beta_c, colsign, Ns, nc).reshape(Nt, nb).sum(1), + 0.0, + None, + ) + t_max = float(d_tot.max()) + w_max = float(d_wave.max()) + if t_max > 1e-20 and w_max > 1e-20: + d_vis = (0.70 * (d_tot / t_max) + 0.30 * (d_wave / w_max)) * t_max + else: + d_vis = d_tot + streamer.emit_transient_values(d_vis, phase=2, step=it, residual=res, force=True) + frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 + _emit_progress(100 + int(round(frac * 95)), 200) + if getattr(streamer, "pace_sec", 0.0) > 0.0: + time.sleep(streamer.pace_sec) + + # When live streaming is active, run the forward pass unaccelerated (accel=False) + # so the Markov chain steps smoothly t=1,2,3,... and animates the bundle growth. + fwd_accel = False if (streamer is not None and getattr(streamer, "pace_sec", 0.0) > 0.0) else accel + S, info_f = _solve( + chain, pi0, mask, tol, 5000, "forward", verbose=False, accel=fwd_accel, on_step=_on_fwd_step + ) + S_p = np.ascontiguousarray(S) + dcls = K.paired_density(S_p, beta_c, colsign, Ns, nc).reshape(chain.t_lin.size, nb) + + ti = chain.tindex[launches.seed_lin] + pt = ti[launches.pair_seed] + on = pt >= 0 + w0 = 0.5 * (launches.pair_w * pb)[on] + for k in (0, 1): + np.add.at(dcls, (pt[on], chain.geo.vbin[launches.pair_d[on, k]]), w0) + density = dcls.sum(1) + endpoints = ((a0 + chain.absorbed_from(S_p)) * p.absw) @ colsign + + # Interior absorbed endpoints (mapped onto nearest boundary absorbing voxels or returned as volume) + interior_endpoints_t = None + if has_int_abs: + q_fwd_term = np.empty_like(S_p) + chain.mul_forward(S_p, q_fwd_term) + int_ep_s = ((a0_term_s + q_fwd_term[term_state, :]) * term_absw_s[term_state, :]) @ colsign + interior_endpoints_t = np.zeros(chain.t_lin.size, dtype=np.float64) + interior_endpoints_t[term_t] = np.clip(int_ep_s.reshape(-1, nb).sum(1), 0.0, None) + density[term_t] += interior_endpoints_t[term_t] + + f26 = np.empty((chain.t_lin.size, 26), dtype=np.float64) + K.stencil_flux( + chain.Q_ptr, + chain.Q_slot, + chain.Q_w, + chain.tmpl_n, + chain.tmpl_b, + chain.nbr_t, + chain.nb, + S_p, + np.ascontiguousarray(beta), + colsign, + f26, + ) + flux26 = np.clip(f26, 0.0, None).astype(np.float32) + + info = dict( + n_seeds=int(len(launches.seeds)), + n_streamlines=int(P), + expected_bundle_streamlines=float(np.clip(seed_prob, 0.0, None).sum()), + endpoint_rule=p.end_rule, + n_columns=int(p.C), + tolerance=tol, + backward=info_b, + forward=info_f, + ) + res = BundleResult( + p.name, + launches.seeds, + np.clip(seed_prob, 0.0, None), + np.clip(density, 0.0, None), + np.clip(endpoints, 0.0, None), + info, + np.clip(dcls, 0.0, None).astype(np.float32), + flux26=flux26, + start_mask=p.start_mask, + end_mask=p.end_mask, + ) + res.interior_endpoints_t = interior_endpoints_t + return res + + +def cmd_solve_bundle(req_path: str) -> None: + """Execute ``solve_bundle`` and emit ``RESULT ``.""" + from .afq import seal_26 as apply_seal_26 + from .branches import extract_branch_arbor, extract_flux_streamlines, write_trx + from .quantify import quantify_bundle + + t_start = time.perf_counter() + with open(req_path, "r") as fh: + req = json.load(fh) + + out_dir = Path(req["out_dir"]) + out_dir.mkdir(parents=True, exist_ok=True) + + _emit_progress(1, 5) + chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms = _reconstruct_state( + req["state_path"] + ) + shape = chain.shape + + # 1. Configure seed mask (either custom seed_mask_path or default_seed_ok) + if req.get("seed_mask_path") and Path(req["seed_mask_path"]).exists(): + s_mask = _resample_mask_to_grid(nib.load(req["seed_mask_path"]), shape, affine) + seed_ok = s_mask[tuple(launches.seeds.T)] + else: + seed_ok = default_seed_ok + active_launches = replace( + launches, + pair_w=launches.pair_w * seed_ok[launches.pair_seed].astype(np.float64), + ) + + # 2. Load and resample ROIs from TrackingPlan + do_seal = bool(req.get("seal_26", True)) + include_masks: List[np.ndarray] = [] + for inc_path in req.get("include_mask_paths", []): + if inc_path and Path(inc_path).exists(): + m = _resample_mask_to_grid(nib.load(inc_path), shape, affine) + if m.any(): + include_masks.append(apply_seal_26(m) if do_seal else m) + + exclude_mask: Optional[np.ndarray] = None + if req.get("exclude_mask_path") and Path(req["exclude_mask_path"]).exists(): + m = _resample_mask_to_grid(nib.load(req["exclude_mask_path"]), shape, affine) + if m.any(): + exclude_mask = apply_seal_26(m) if do_seal else m + + if req.get("limiting_mask_path") and Path(req["limiting_mask_path"]).exists(): + lim = _resample_mask_to_grid(nib.load(req["limiting_mask_path"]), shape, affine) + if lim.any(): + outside_lim = ~lim + exclude_mask = outside_lim if exclude_mask is None else (exclude_mask | outside_lim) + + start_mask: Optional[np.ndarray] = None + if req.get("start_mask_path") and Path(req["start_mask_path"]).exists(): + m = _resample_mask_to_grid(nib.load(req["start_mask_path"]), shape, affine) + if m.any(): + start_mask = m + + end_mask: Optional[np.ndarray] = None + if req.get("end_mask_path") and Path(req["end_mask_path"]).exists(): + m = _resample_mask_to_grid(nib.load(req["end_mask_path"]), shape, affine) + if m.any(): + end_mask = m + + term_mask: Optional[np.ndarray] = None + if req.get("term_mask_path") and Path(req["term_mask_path"]).exists(): + m = _resample_mask_to_grid(nib.load(req["term_mask_path"]), shape, affine) + if m.any(): + term_mask = m + + no_end_mask: Optional[np.ndarray] = None + if req.get("no_end_mask_path") and Path(req["no_end_mask_path"]).exists(): + m = _resample_mask_to_grid(nib.load(req["no_end_mask_path"]), shape, affine) + if m.any(): + no_end_mask = m + + # Optional midline exclusion rule + midline_raw = req.get("midline_exclusion", "auto") + if isinstance(midline_raw, bool): + midline_mode = "auto" if midline_raw else "none" + else: + midline_mode = str(midline_raw).lower() + if midline_mode == "true": + midline_mode = "auto" + elif midline_mode == "false": + midline_mode = "none" + midline_tol_mm = float(req.get("midline_tol_mm", 0.0)) + bundle_name = str(req.get("bundle_name") or "Bundle") + if midline_mode in ("left", "right") or ( + midline_mode == "auto" + and any(tok in bundle_name.lower() for tok in ("left", "right", "_l", "_r")) + ): + xyz_x = nib.affines.apply_affine(affine, np.indices(shape).reshape(3, -1).T)[:, 0].reshape(shape) + is_left = midline_mode == "left" or bundle_name.lower().startswith("left") or bundle_name.lower().endswith("_l") or "left" in bundle_name.lower() + mid_exc = (xyz_x > midline_tol_mm) if is_left else (xyz_x < -midline_tol_mm) + exclude_mask = mid_exc if exclude_mask is None else (exclude_mask | mid_exc) + + spec: Dict[str, Any] = { + "name": bundle_name, + "include": include_masks, + "exclude": exclude_mask, + "start": start_mask, + "end": end_mask, + } + + _emit_progress(2, 5) + tol = float(req.get("solver_tol") or req.get("tol") or 1e-6) + accel_str = str(req.get("solver_accel") or req.get("accel") or "mr").lower() + accel: Any = False if accel_str in ("none", "false", "") else accel_str + use_cascade = bool(req.get("use_cascade", True)) + + explicit_stream = bool(req.get("stream_mmap_path")) + stream_mmap_path = req.get("stream_mmap_path") or str(out_dir / "live_density.mmap") + streamer: Optional[LiveDensityStreamer] = None + try: + streamer = LiveDensityStreamer(Path(stream_mmap_path), chain, affine) + streamer.pace_sec = 0.035 if explicit_stream else 0.0 + except Exception: + streamer = None + + res = _solve_bundle_with_custom_regions( + chain, + active_launches, + spec, + term_mask=term_mask, + no_end_mask=no_end_mask, + tol=tol, + accel=accel, + use_cascade=use_cascade, + streamer=streamer, + ) + + _emit_progress(3, 5) + qb = quantify_bundle( + chain, + res, + whole_dc, + sh_rows, + affine, + lobes=lobes, + start_mask=start_mask, + end_mask=end_mask if end_mask is not None else term_mask, + compute_boundary_conductance=False, + ) + if streamer is not None: + streamer.emit_transient_values(res.density_t, phase=3, step=int(res.info["forward"]["iterations"]), residual=0.0, force=True) + + afd_vol = chain.to_volume(qb.voxel_afd_t) + density_vol = chain.to_volume(res.density_t) + tdimm_vol = chain.to_volume(qb.tdi_mm_t) + qharm_vol = chain.to_volume(qb.q_harmonic_t) + coh_vol = chain.to_volume(qb.flux_coherence_t) + keff_vol = chain.to_volume(qb.branching_k_eff_t) + endpoints_vol = chain.to_volume(res.endpoints_a, "absorbing") + if getattr(res, "interior_endpoints_t", None) is not None: + endpoints_vol = endpoints_vol + chain.to_volume(res.interior_endpoints_t, "transient") + + volume_paths = { + "afd": _save_nifti(afd_vol, affine, out_dir / "afd.nii"), + "density": _save_nifti(density_vol, affine, out_dir / "density.nii"), + "tdimm": _save_nifti(tdimm_vol, affine, out_dir / "tdimm.nii"), + "qharmonic": _save_nifti(qharm_vol, affine, out_dir / "qharmonic.nii"), + "coherence": _save_nifti(coh_vol, affine, out_dir / "coherence.nii"), + "keff": _save_nifti(keff_vol, affine, out_dir / "keff.nii"), + "endpoints": _save_nifti(endpoints_vol, affine, out_dir / "endpoints.nii"), + } + + _emit_progress(4, 5) + n_streamlines = int(req.get("n_streamlines", 800)) + afd_mass_fraction = float(req.get("afd_mass_fraction", 0.96)) + max_end_branches = int(req.get("n_arbor_branches", 6)) + max_lateral_offshoots = int(req.get("max_lateral_offshoots", 8)) + min_branch_sep_mm = float(req.get("min_branch_sep_mm", 7.0)) + want_streamlines = bool(req.get("extract_streamlines", True)) + want_arbor = bool(req.get("extract_arbor", True)) + # The RK4 step arrives in voxels; extract_flux_streamlines takes millimetres (it divides by + # the mean voxel size), and its max_steps bounds each half of the bidirectional integration. + mean_zoom = float(np.mean(np.sqrt((np.asarray(affine, float)[:3, :3] ** 2).sum(0)))) + step_mm = max(float(req.get("step_vox", 0.5)), 1e-3) * mean_zoom + min_length_mm = float(req.get("min_length_mm", 18.0)) + max_length_mm = float(req.get("max_length_mm", 250.0)) + max_steps = max(1, int(np.ceil(max_length_mm / (2.0 * step_mm)))) + + warnings: List[str] = [] + + def _warn(stage: str, err: Exception) -> None: + import traceback + + traceback.print_exc(file=sys.stderr) + warnings.append(f"{stage} failed: {type(err).__name__}: {err}") + + trx_path = out_dir / "bundle.trx" + fg = None + n_branches = 0 + if float(afd_vol.max()) > 0 and float(res.density_t.max()) > 0: + arbor = None + if want_arbor: + try: + arbor = extract_branch_arbor( + afd_vol, + endpoints_vol, + affine, + q_vol=qharm_vol, + coherence_vol=coh_vol, + keff_vol=keff_vol, + start_mask=start_mask, + end_mask=end_mask if end_mask is not None else term_mask, + bundle_name=bundle_name, + max_end_branches=max_end_branches, + max_lateral_offshoots=max_lateral_offshoots, + min_branch_sep_mm=min_branch_sep_mm, + ) + n_branches = len(arbor.branches) + except Exception as err: + _warn("arbor extraction", err) + + if want_streamlines or arbor is not None: + try: + # With extract_streamlines off, n_streamlines=0 keeps only the arbor ridge curves. + fg = extract_flux_streamlines( + chain, + res.flux26, + afd_vol, + affine, + q_vol=qharm_vol, + coherence_vol=coh_vol, + keff_vol=keff_vol, + arbor=arbor, + n_streamlines=n_streamlines if want_streamlines else 0, + step_mm=step_mm, + max_steps=max_steps, + min_length_mm=min_length_mm, + afd_mass_fraction=afd_mass_fraction, + ) + except Exception as err: + _warn("flux streamline extraction", err) + else: + warnings.append("empty bundle: nothing to extract streamlines from") + + if fg is None: + from .branches import FluxTractogram + + fg = FluxTractogram( + streamlines=[], + dpv={}, + dps={}, + groups={}, + affine=affine, + dimensions=shape, + ) + write_trx(fg, str(trx_path)) + n_extracted = len(fg.streamlines) + + _emit_progress(5, 5) + elapsed = time.perf_counter() - t_start + exp_sl = float(res.info["expected_bundle_streamlines"]) + afd_vol_mm3 = float(qb.summary.get("tract_afd_volume_mm3", 0.0)) + summary = ( + f"{n_extracted} flux streamlines ({n_branches} branches), " + f"{exp_sl:.1f} expected walks, {afd_vol_mm3 / 1000.0:.2f} cm³ AFD in {elapsed:.2f}s" + ) + if warnings: + summary += " — " + "; ".join(warnings) + result = { + "trx_path": str(trx_path), + "volumes": volume_paths, + "expected_streamlines": exp_sl, + "n_flux_streamlines": n_extracted, + "n_branches": n_branches, + "quantification": qb.summary, + "warnings": warnings, + "summary": summary, + } + with open(out_dir / "solve_result.json", "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + + +def cmd_precompute_cli(argv: List[str]) -> int: + """CLI helper to precompute ``mpat_transitions_.npz`` directly from an ODX file or subject folder.""" + import argparse + import tempfile + + p = argparse.ArgumentParser( + prog="python -m mpat.trxviz_bridge precompute", + description="Precompute and cache mpat_transitions_.npz for instant loading in TRXViz.", + ) + p.add_argument("input_path", help="Path to an .odx / .nii.gz / .npz file or a pyAFQ/MPAT subject directory") + p.add_argument("--out-dir", help="Directory to store the hashed mpat_transitions_.npz (default: alongside input)") + p.add_argument("--preset", choices=("standard", "ptt"), default="standard") + p.add_argument("--angle-deg", type=float, default=35.0) + p.add_argument("--step-vox", type=float, default=1.0) + p.add_argument("--single-odf", action="store_true", help="Use single-ODF transitions instead of double-ODF") + p.add_argument("--fod-thresh", type=float, default=None) + p.add_argument("--fod-power", type=float, default=None) + p.add_argument("--stop-mass-tau", type=float, default=None) + p.add_argument("--curv-sigma-deg", type=float, default=None) + p.add_argument("--probe-radius-vox", type=float, default=None) + p.add_argument("--max-length-mm", type=float, default=250.0) + p.add_argument("--wm-threshold", type=float, default=0.4) + a = p.parse_args(argv) + + inp = Path(a.input_path).resolve() + target_dir = Path(a.out_dir).resolve() if a.out_dir else (inp if inp.is_dir() else inp.parent) + target_dir.mkdir(parents=True, exist_ok=True) + + is_ptt = a.preset == "ptt" + with tempfile.TemporaryDirectory(prefix="mpat_precompute_") as tmp: + req = { + "out_dir": tmp, + "cache_dir": str(target_dir), + "working_dir": str(inp) if inp.is_dir() else str(target_dir), + "odx_path": str(inp) if inp.is_file() else None, + "preset": a.preset, + "angle_deg": a.angle_deg, + "step_vox": a.step_vox, + "double_odf": not a.single_odf and (not is_ptt), + "fod_thresh": a.fod_thresh if a.fod_thresh is not None else (0.08 if is_ptt else 0.05), + "fod_power": a.fod_power if a.fod_power is not None else (2.0 if is_ptt else 1.0), + "stop_mass_tau": a.stop_mass_tau if a.stop_mass_tau is not None else (0.25 if is_ptt else 0.0), + "curv_sigma_deg": a.curv_sigma_deg if a.curv_sigma_deg is not None else (22.5 if is_ptt else 0.0), + "probe_radius_vox": a.probe_radius_vox if a.probe_radius_vox is not None else (0.35 if is_ptt else 0.0), + "max_length_mm": a.max_length_mm, + "wm_threshold": a.wm_threshold, + } + req_file = Path(tmp) / "req.json" + req_file.write_text(json.dumps(req, indent=2)) + cmd_build_transitions(str(req_file)) + return 0 + + +def main(argv: Optional[List[str]] = None) -> int: + args = list(sys.argv[1:] if argv is None else argv) + if not args or args[0] not in ("build_transitions", "solve_bundle", "precompute"): + print( + "Usage:\n" + " python -m mpat.trxviz_bridge precompute [options]\n" + " python -m mpat.trxviz_bridge ", + file=sys.stderr, + ) + return 2 + cmd = args[0] + if cmd == "precompute": + return cmd_precompute_cli(args[1:]) + if len(args) < 2: + return 2 + req_path = args[1] + if cmd == "build_transitions": + cmd_build_transitions(req_path) + elif cmd == "solve_bundle": + cmd_solve_bundle(req_path) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_trxviz_bridge.py b/tests/test_trxviz_bridge.py new file mode 100644 index 0000000..63732ac --- /dev/null +++ b/tests/test_trxviz_bridge.py @@ -0,0 +1,246 @@ +"""Tests for the TRXViz <-> MPAT + MITTENS bridge (mpat.trxviz_bridge).""" +import json +from pathlib import Path + +import nibabel as nib +import numpy as np + +from mpat.trxviz_bridge import cmd_build_transitions, cmd_solve_bundle + + +def _sh(directions, kappa=20.0): + from dipy.core.sphere import Sphere + from dipy.data import get_sphere + from dipy.reconst.shm import sh_to_sf_matrix + + sph = get_sphere(name="repulsion724") + _, inv = sh_to_sf_matrix(Sphere(xyz=sph.vertices), sh_order_max=8, return_inv=True) + sf = sum(np.exp(kappa * (sph.vertices @ np.asarray(d, float)) ** 2) for d in directions) + return (sf @ inv).astype(np.float32) + + +def test_trxviz_bridge_transitions_and_custom_rois(tmp_path: Path): + nx, ny, nz = 12, 10, 5 + zooms = np.array([2.0, 2.0, 2.0], dtype=np.float64) + affine = np.diag([2.0, 2.0, 2.0, 1.0]) + sh = np.zeros((nx, ny, nz, 45), dtype=np.float32) + transient = np.zeros((nx, ny, nz), dtype=bool) + absorb = np.zeros((nx, ny, nz), dtype=np.int8) + + sh_x = _sh([(1.0, 0.0, 0.0)], kappa=18.0) + transient[2:-2, 3:-3, 1:-1] = True + absorb[1, 3:-3, 1:-1] = 1 + absorb[-2, 3:-3, 1:-1] = 1 + absorb[2:-2, 2, 1:-1] = 1 + absorb[2:-2, -3, 1:-1] = 1 + + for i in range(1, nx - 1): + for j in range(2, ny - 2): + for k in range(1, nz - 1): + sh[i, j, k] = sh_x + + subj_npz = tmp_path / "subj_sub01.npz" + seeds = np.argwhere(transient) + np.savez( + subj_npz, + sh=sh, + affine=affine, + zooms=zooms, + transient=transient, + absorb=absorb, + seeds=seeds, + ) + + trans_out = tmp_path / "transitions" + req_trans = tmp_path / "req_trans.json" + req_trans.write_text( + json.dumps( + { + "out_dir": str(trans_out), + "working_dir": str(subj_npz), + "preset": "ptt", + "angle_deg": 35.0, + "step_vox": 1.0, + "double_odf": True, + "stop_mass_tau": 1e-4, + "curv_sigma_deg": 18.0, + "probe_radius_vox": 0.0, + "max_length_mm": 120.0, + } + ) + ) + cmd_build_transitions(str(req_trans)) + + res_trans = json.loads((trans_out / "transitions_result.json").read_text()) + assert Path(res_trans["state_path"]).name.startswith("mpat_transitions_") + assert len(res_trans["fp_hash"]) == 16 + expected_trans_keys = { + "codi_double", + "codi_single", + "coasy", + "p_terminate_double", + "p_terminate_single", + "total_amplitude", + "kl_single", + "chain_dead", + } + assert set(res_trans["volumes"].keys()) == expected_trans_keys + for k, p in res_trans["volumes"].items(): + assert Path(p).exists(), f"Missing transition volume {k}" + vol = np.asarray(nib.load(p).dataobj, dtype=np.float32) + assert vol.shape == (nx, ny, nz) + # p_terminate_double should be positive inside mask since tau > 0 + p_term = np.asarray(nib.load(res_trans["volumes"]["p_terminate_double"]).dataobj) + assert float(p_term[transient].max()) > 0.0 + + # Verify automatic hash-based cache hit on identical inputs + parameters + trans_out_cached = tmp_path / "transitions_cached" + req_trans_cached = tmp_path / "req_trans_cached.json" + req_trans_cached.write_text( + json.dumps( + { + "out_dir": str(trans_out_cached), + "working_dir": str(subj_npz), + "preset": "ptt", + "angle_deg": 35.0, + "step_vox": 1.0, + "double_odf": True, + "stop_mass_tau": 1e-4, + "curv_sigma_deg": 18.0, + "probe_radius_vox": 0.0, + "max_length_mm": 120.0, + } + ) + ) + cmd_build_transitions(str(req_trans_cached)) + res_cached = json.loads((trans_out_cached / "transitions_result.json").read_text()) + assert res_cached["fp_hash"] == res_trans["fp_hash"] + assert res_cached["state_path"] == res_trans["state_path"] + assert "Cached [mpat_transitions_" in res_cached["summary"] + + # Verify direct loading when working_dir points directly to mpat_transitions_.npz + trans_out_direct = tmp_path / "transitions_direct" + req_trans_direct = tmp_path / "req_trans_direct.json" + req_trans_direct.write_text( + json.dumps( + { + "out_dir": str(trans_out_direct), + "working_dir": res_trans["state_path"], + } + ) + ) + cmd_build_transitions(str(req_trans_direct)) + res_direct = json.loads((trans_out_direct / "transitions_result.json").read_text()) + assert res_direct["state_path"] == res_trans["state_path"] + assert "Loaded [mpat_transitions_" in res_direct["summary"] + + # Prepare start, end, include, avoid, and interior absorption ROI masks + start_mask = np.zeros((nx, ny, nz), dtype=np.uint8) + start_mask[1, 3:-3, 1:-1] = 1 + end_mask = np.zeros((nx, ny, nz), dtype=np.uint8) + end_mask[-2, 3:-3, 1:-1] = 1 + inc_mask = np.zeros((nx, ny, nz), dtype=np.uint8) + inc_mask[5:7, 3:-3, 1:-1] = 1 + + start_p = tmp_path / "start.nii" + end_p = tmp_path / "end.nii" + inc_p = tmp_path / "inc.nii" + nib.save(nib.Nifti1Image(start_mask, affine), str(start_p)) + nib.save(nib.Nifti1Image(end_mask, affine), str(end_p)) + nib.save(nib.Nifti1Image(inc_mask, affine), str(inc_p)) + + # 1. Baseline solve with start, end, and include + solve_out1 = tmp_path / "solve_base" + req_solve1 = tmp_path / "req_solve1.json" + req_solve1.write_text( + json.dumps( + { + "state_path": res_trans["state_path"], + "out_dir": str(solve_out1), + "bundle_name": "PhantomTract", + "include_mask_paths": [str(inc_p)], + "start_mask_path": str(start_p), + "end_mask_path": str(end_p), + "seal_26": False, + "midline_exclusion": "none", + "n_streamlines": 60, + "extract_arbor": False, + "step_vox": 0.5, + "min_length_mm": 4.0, + } + ) + ) + cmd_solve_bundle(str(req_solve1)) + res_s1 = json.loads((solve_out1 / "solve_result.json").read_text()) + assert res_s1["expected_streamlines"] > 1.0 + assert Path(res_s1["trx_path"]).exists() + # Streamline extraction errors used to be swallowed, leaving an empty TRX + assert not any("flux streamline extraction" in w for w in res_s1["warnings"]), res_s1["warnings"] + assert res_s1["n_flux_streamlines"] > 0 + for k in ("afd", "density", "tdimm", "qharmonic", "coherence", "keff", "endpoints"): + assert Path(res_s1["volumes"][k]).exists() + mmap_file = solve_out1 / "live_density.mmap" + assert mmap_file.exists() + raw_hdr = mmap_file.read_bytes()[:40] + import struct + magic, ver, seq, phase, step, m_nx, m_ny, m_nz, resid, max_val = struct.unpack("<8I2f", raw_hdr) + assert magic == 0x5441504D and ver == 1 + assert seq >= 2 and phase == 3 + assert (m_nx, m_ny, m_nz) == (nx, ny, nz) + assert max_val > 0.0 + + # 2. Add an Avoid ROI blocking the middle of the bundle -> expected streamlines should drop sharply + avoid_mask = np.zeros((nx, ny, nz), dtype=np.uint8) + avoid_mask[5:7, :, :] = 1 + avoid_p = tmp_path / "avoid.nii" + nib.save(nib.Nifti1Image(avoid_mask, affine), str(avoid_p)) + + solve_out2 = tmp_path / "solve_avoid" + req_solve2 = tmp_path / "req_solve2.json" + req_solve2.write_text( + json.dumps( + { + "state_path": res_trans["state_path"], + "out_dir": str(solve_out2), + "bundle_name": "PhantomTractAvoid", + "start_mask_path": str(start_p), + "end_mask_path": str(end_p), + "exclude_mask_path": str(avoid_p), + "seal_26": True, + "midline_exclusion": "none", + "n_streamlines": 40, + } + ) + ) + cmd_solve_bundle(str(req_solve2)) + res_s2 = json.loads((solve_out2 / "solve_result.json").read_text()) + assert res_s2["expected_streamlines"] < 1e-4 + + # 3. Add an arbitrary interior Absorption ROI (term_mask) at i=6..7 (inside transient WM!) + term_mask = np.zeros((nx, ny, nz), dtype=np.uint8) + term_mask[6:8, 3:-3, 1:-1] = 1 + term_p = tmp_path / "term.nii" + nib.save(nib.Nifti1Image(term_mask, affine), str(term_p)) + + solve_out3 = tmp_path / "solve_term" + req_solve3 = tmp_path / "req_solve3.json" + req_solve3.write_text( + json.dumps( + { + "state_path": res_trans["state_path"], + "out_dir": str(solve_out3), + "bundle_name": "PhantomTractTerm", + "start_mask_path": str(start_p), + "term_mask_path": str(term_p), + "seal_26": False, + "midline_exclusion": "none", + "n_streamlines": 40, + } + ) + ) + cmd_solve_bundle(str(req_solve3)) + res_s3 = json.loads((solve_out3 / "solve_result.json").read_text()) + assert res_s3["expected_streamlines"] > 1.0 + ep_vol3 = np.asarray(nib.load(res_s3["volumes"]["endpoints"]).dataobj) + # Verify walkers absorbed inside the interior term_mask (i=6..7) + assert float(ep_vol3[6:8, 3:-3, 1:-1].sum()) > 0.5 From 6c8dd6e5ecc71895829dd0e7563f09d903ea2c87 Mon Sep 17 00:00:00 2001 From: mattcieslak Date: Tue, 17 Nov 2026 13:00:14 -0500 Subject: [PATCH 3/5] Use installed odx and trxviz-cli instead of sibling checkouts trxviz_bridge no longer puts a local odx-rs/python on sys.path ahead of the installed odx, and render_trxviz finds trxviz-cli through TRXVIZ_CLI or PATH only. Install odx from PyPI, like mittens-dmri already requires. --- src/mpat/branches.py | 11 +---------- src/mpat/trxviz_bridge.py | 5 ----- 2 files changed, 1 insertion(+), 15 deletions(-) diff --git a/src/mpat/branches.py b/src/mpat/branches.py index eecd884..110c70b 100644 --- a/src/mpat/branches.py +++ b/src/mpat/branches.py @@ -1160,16 +1160,7 @@ def render_trxviz( import os import shutil import subprocess - from pathlib import Path - - # A TRXViz checkout next to this repo (../odx/TRXViz) is the last resort. - sibling = Path(__file__).resolve().parents[3] / "odx" / "TRXViz" / "target" / "release" / "trxviz-cli" - cli = ( - trxviz_cli_bin - or os.environ.get("TRXVIZ_CLI") - or shutil.which("trxviz-cli") - or (str(sibling) if sibling.is_file() else "trxviz-cli") - ) + cli = trxviz_cli_bin or os.environ.get("TRXVIZ_CLI") or shutil.which("trxviz-cli") or "trxviz-cli" cmd = [ cli, "render", diff --git a/src/mpat/trxviz_bridge.py b/src/mpat/trxviz_bridge.py index 6ae5a2d..2e1acbd 100644 --- a/src/mpat/trxviz_bridge.py +++ b/src/mpat/trxviz_bridge.py @@ -38,11 +38,6 @@ import numpy as np from scipy import ndimage as ndi -# Ensure sibling odx-rs/python is on sys.path if odx is not installed in the env -_cand_odx = Path(__file__).resolve().parents[3] / "odx" / "odx-rs" / "python" -if _cand_odx.is_dir() and str(_cand_odx) not in sys.path: - sys.path.insert(0, str(_cand_odx)) - def _emit_progress(done: int, total: int) -> None: print(f"PROGRESS {int(done)} {int(total)}", flush=True) From 8eddb172574054b9cfcbfa4e5877a08be836d027 Mon Sep 17 00:00:00 2001 From: mattcieslak Date: Tue, 17 Nov 2026 13:32:52 -0500 Subject: [PATCH 4/5] Keep the AFD share formula and add a solve streaming hook - afd_tract_metrics divides bundle visitation by whole-brain visitation again (n_b / n_w, as on main). The data-dependent regulariser changed every bundle's AFD and stopped the shares from partitioning each voxel. - segment_bundles takes on_step(SolveStep), called after every backward and forward iteration, so callers can stream a solve without their own solver. - Transitions ODX files record the maximum length they were built for, and mpat run passes it. --- src/mpat/afq.py | 1 + src/mpat/quantify.py | 8 +------- src/mpat/solve.py | 38 ++++++++++++++++++++++++++++++++------ src/mpat/transitions.py | 6 +++++- 4 files changed, 39 insertions(+), 14 deletions(-) diff --git a/src/mpat/afq.py b/src/mpat/afq.py index c6d10b0..fc8877f 100644 --- a/src/mpat/afq.py +++ b/src/mpat/afq.py @@ -785,6 +785,7 @@ def trapped(what, names, vol): launches=launches, whole_dc=whole.density_class, surv=surv_state, + max_length_mm=max_length, ) log.info("transitions ODX written to %s", odx_out) if st_mode in ("nifti", "both"): diff --git a/src/mpat/quantify.py b/src/mpat/quantify.py index 9148277..ce95260 100644 --- a/src/mpat/quantify.py +++ b/src/mpat/quantify.py @@ -72,13 +72,7 @@ def afd_tract_metrics(bundle_res, whole_density_class, sh_rows, geo, lobes: Lobe lobes = segment_lobes(sh_rows, geo) n_b, u_b = fixel_streamlines(bundle_res.density_class, sh_rows, geo, lobes) n_w, u_w = fixel_streamlines(whole_density_class, sh_rows, geo, lobes) - # Regularize denominator so boundary voxels with tiny whole-brain visitation n_w - # do not amplify negligible bundle tails (n_b / (n_w + reg)). - pos_b = n_b[n_b > 0] - b_scale = float(np.percentile(pos_b, 95)) if pos_b.size else 1.0 - pos_w = n_w[n_w > 0] - w_reg = max(0.10 * float(np.median(pos_w)) if pos_w.size else 1e-6, 0.05 * b_scale, 1e-12) - share = np.divide(n_b, np.maximum(n_w, 0.0) + w_reg, out=np.zeros_like(n_b), where=(n_b > 0)) + share = np.divide(n_b, n_w, out=np.zeros_like(n_b), where=n_w > 1e-30) share = np.clip(share, 0.0, 1.0) fixel_afd = share * lobes.integral Nt = len(sh_rows) diff --git a/src/mpat/solve.py b/src/mpat/solve.py index eaf86c4..1a91f92 100644 --- a/src/mpat/solve.py +++ b/src/mpat/solve.py @@ -409,6 +409,19 @@ class BundleResult: end_mask: np.ndarray = None # optional end ROI mask on the chain grid +@dataclass +class SolveStep: + """What a :func:`segment_bundles` ``on_step`` callback gets after each series iteration.""" + phase: str # "backward" (completion probabilities) or "forward" (occupancy) + it: int # iteration number within the phase + res: float # relative residual + total: np.ndarray # solution so far, (n_states * ncomp, columns) + term: np.ndarray # this iteration's term of the series: the current wavefront + colsign: np.ndarray # inclusion-exclusion sign of each column + n_kinds: int # end kinds of the first bundle (its columns 0 .. n_kinds - 1 avoid nothing) + beta: np.ndarray = None # the backward solution; forward phase only + + def _endpoint_kinds(a_valid, a_start, a_end): """Disjoint end categories per half and the non-negative bilinear form M >= 0: P(both ends acceptable) = sum_kl M[k, l] V_k(h1) V_l(h2).""" @@ -493,8 +506,17 @@ def _solve(chain, x0, mask, tol, max_iter, what, verbose=False, accel=False, on_ def _solve_group(chain, plans, L, tol, max_iter, on_result, on_trapped=None, verbose=False, clock=None, - keep_fields=False, accel=False, arc_length=False, zooms=None): + keep_fields=False, accel=False, arc_length=False, zooms=None, on_step=None): t0 = time.time() + colsign_all = np.concatenate([p.signs[p.xcol] for p in plans]) + n_kinds = plans[0].nK + + def step_hook(phase, beta=None): + if on_step is None: + return None + return lambda it, res, total, term: on_step(SolveStep(phase, it, res, total, term, colsign_all, + n_kinds, beta)) + gclock = Clock() nb, Ns, nc = chain.nb, chain.n_states, chain.ncomp offs = np.cumsum([0] + [p.C for p in plans]) @@ -508,7 +530,8 @@ def _solve_group(chain, plans, L, tol, max_iter, on_result, on_trapped=None, ver r = np.concatenate([chain.absorb_rhs(p.absw) for p in plans], axis=1) r *= mask with gclock("backward solve"): - beta, info_b = _solve(chain, r, mask, tol, max_iter, "backward", verbose, accel=accel) + beta, info_b = _solve(chain, r, mask, tol, max_iter, "backward", verbose, accel=accel, + on_step=step_hook("backward")) with gclock("trapped maps"): _trapped(chain, info_b, "backward", names, on_trapped) del r @@ -537,7 +560,8 @@ def _solve_group(chain, plans, L, tol, max_iter, on_result, on_trapped=None, ver gclock.add("seed weights (forward start)", time.perf_counter() - t_init) launch = pi0.copy() if keep_fields else None # solve_series consumes pi0 with gclock("forward solve"): - S, info_f = _solve(chain, pi0, mask, tol, max_iter, "forward", verbose, accel=accel) + S, info_f = _solve(chain, pi0, mask, tol, max_iter, "forward", verbose, accel=accel, + on_step=step_hook("forward", beta)) with gclock("trapped maps"): _trapped(chain, info_f, "forward", names, on_trapped) del pi0, mask @@ -605,7 +629,7 @@ def _solve_group(chain, plans, L, tol, max_iter, on_result, on_trapped=None, ver def segment_bundles(chain, specs, launches, tol=1e-6, max_mem=8e9, max_iter=5000, valid_classes=VALID_ENDS, on_result=None, on_trapped=None, verbose=False, - clock=None, keep_fields=False, accel=False, arc_length=False, zooms=None): + clock=None, keep_fields=False, accel=False, arc_length=False, zooms=None, on_step=None): """Segment bundles, sharing solves. ``specs``: dicts with ``name`` and optional ``include`` (list of masks), ``exclude``, ``start``, ``end`` (boolean volumes on the chain grid). Bundles are packed in order into groups whose columns fit in ``max_mem`` bytes; @@ -621,6 +645,8 @@ def segment_bundles(chain, specs, launches, tol=1e-6, max_mem=8e9, max_iter=5000 ``accel``: False (default), True / "mr" (Periodic Minimal Residual), or "aitken". ``arc_length``: weight class visits by physical intra-voxel chord lengths (in mm if ``zooms`` is provided, else in voxels). + ``on_step(step)``: called with a :class:`SolveStep` after every backward and forward + iteration (e.g. to stream the solve as it converges). Returns {name: BundleResult}.""" if keep_fields and chain.ncomp != 1: raise ValueError("keep_fields needs the plain chain (ncomp == 1), not the moment chain") @@ -646,14 +672,14 @@ def segment_bundles(chain, specs, launches, tol=1e-6, max_mem=8e9, max_iter=5000 if group and used + p.C > cap: out.update(_solve_group(chain, group, launches, tol, max_iter, on_result, on_trapped, verbose, clock, keep_fields, accel=accel, arc_length=arc_length, - zooms=zooms)) + zooms=zooms, on_step=on_step)) group, used = [], 0 group.append(p) used += p.C if group: out.update(_solve_group(chain, group, launches, tol, max_iter, on_result, on_trapped, verbose, clock, keep_fields, accel=accel, arc_length=arc_length, - zooms=zooms)) + zooms=zooms, on_step=on_step)) if own: clock.report("bundle segmentation time", time.perf_counter() - t_all) return out diff --git a/src/mpat/transitions.py b/src/mpat/transitions.py index b8e50e3..e2ab1d9 100644 --- a/src/mpat/transitions.py +++ b/src/mpat/transitions.py @@ -15,7 +15,6 @@ import json import zipfile -from dataclasses import replace from pathlib import Path from typing import Dict, Optional, Tuple, Union @@ -231,6 +230,7 @@ def save_transitions_odx( surv: Optional[np.ndarray] = None, mittens_maps: Optional[Dict[str, np.ndarray]] = None, quantize_weights: bool = True, + max_length_mm: Optional[float] = None, ) -> Path: """Persist ``chain`` (including PTT / 26-class stencil, fixel lobes, and per-voxel transition metrics) as a spec-compliant ``.odx`` archive (or ``.odxd`` directory). @@ -261,6 +261,9 @@ def save_transitions_odx( quantize_weights : bool Store ``Q_w`` and ``R_val`` in ``float32`` instead of ``float64`` (halves file size while preserving transition probabilities to ``< 1e-7``). + max_length_mm : float, optional + The soft maximum length the chain's overlength states were computed for; recorded in + the header so readers can check it. """ path = Path(path) shape = tuple(int(s) for s in chain.shape) @@ -438,6 +441,7 @@ def save_transitions_odx( "mpat": { "format_version": 1, "fingerprint": fingerprint or "", + "max_length_mm": float(max_length_mm) if max_length_mm else None, "config": chain.cfg.key(), "zooms": zooms, "pshape": list(chain.pshape), From ae50dd833c44826060444800cce7151eb8f858ae Mon Sep 17 00:00:00 2001 From: mattcieslak Date: Tue, 17 Nov 2026 13:32:52 -0500 Subject: [PATCH 5/5] Fix the TRXViz bridge's input handling and use mpat.solve - Import find_boundaries for folders with PVE tissue maps. - Pick a folder's staged subject .npz by its arrays, not its file name, so chain and transition caches are skipped. - Without tissue maps, require a transient WM mask instead of guessing tissue classes from the fODF. - Prebuilt transitions (.odx or cached .npz) refuse requests for other settings or for mask overrides, and load errors are raised instead of falling back to a rebuild. - Transitions from an .odx get all seven MITTENS maps, computed from the stored fODF, instead of stand-ins. - Midline exclusion picks the side with mpat's _is_left (name, else ROI centres) instead of matching "_l"/"_r" anywhere in the name. - Ordinary bundles are solved with segment_bundles, the solver mpat run uses; the custom solver remains only for interior absorption and no-end masks. Frame streaming is shared by both. - The precompute command's PTT defaults match mpat run --ptt. --- src/mpat/trxviz_bridge.py | 633 ++++++++++++++++++++++-------------- tests/test_trxviz_bridge.py | 39 +++ 2 files changed, 425 insertions(+), 247 deletions(-) diff --git a/src/mpat/trxviz_bridge.py b/src/mpat/trxviz_bridge.py index 2e1acbd..c9e2d3a 100644 --- a/src/mpat/trxviz_bridge.py +++ b/src/mpat/trxviz_bridge.py @@ -61,6 +61,7 @@ def __init__(self, mmap_path: Path, chain, affine: np.ndarray, min_interval_sec: self.t_ijk = tuple((np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1).T) self.seq = 0 self.min_interval_sec = float(min_interval_sec) + self.pace_sec = 0.0 # seconds to pause after each frame so the animation is watchable self._last_emit = 0.0 with open(self.path, "wb") as fh: @@ -154,6 +155,18 @@ def _resample_mask_to_grid(mask_img: nib.Nifti1Image, shape: Tuple[int, int, int return resampled > 0 +_STAGED_SUBJECT_KEYS = {"sh", "affine", "zooms", "transient", "absorb"} + + +def _is_staged_subject_npz(path) -> bool: + """True for an .npz holding a staged subject (fODF SH plus tissue classes).""" + try: + with np.load(path) as z: + return _STAGED_SUBJECT_KEYS.issubset(z.files) + except Exception: # noqa: BLE001 - unreadable or not an npz: not a subject bundle + return False + + def _discover_subject_inputs( working_dir: Optional[str], odx_path: Optional[str], @@ -161,31 +174,31 @@ def _discover_subject_inputs( ) -> Tuple[np.ndarray, np.ndarray, Tuple[float, float, float], np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]]: """Resolve ``(sh, affine, zooms, transient, absorb_class, dseg, wmgm_mask)`` from either a staged ``.npz`` bundle, a pyAFQ/MPAT directory, or an ``.odx``/``.fib.gz``/``.nii.gz`` file. + ``transient``, ``absorb_class`` and ``dseg`` are None when no tissue maps were found. """ from .afq import _on_grid # Case 1: working_dir or odx_path points directly to a staged .npz subject file for cand in (working_dir, odx_path): - if cand and Path(cand).is_file() and str(cand).endswith(".npz"): + if cand and Path(cand).is_file() and str(cand).endswith(".npz") and _is_staged_subject_npz(cand): z = np.load(cand) - if "sh" in z.files and "transient" in z.files and "absorb" in z.files: - sh = np.asarray(z["sh"], dtype=np.float32) - affine = np.asarray(z["affine"], dtype=np.float64) - zooms = tuple(float(x) for x in z["zooms"][:3]) - transient = np.asarray(z["transient"], dtype=bool) - absorb = np.asarray(z["absorb"], dtype=np.int8) - dseg = ( - np.asarray(z["dseg"], dtype=np.uint8) - if "dseg" in z.files - else np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) - ) - wmgm = None - if "seeds" in z.files: - wmgm = np.zeros(transient.shape, dtype=bool) - seeds = np.asarray(z["seeds"], dtype=np.int64) - if seeds.ndim == 2 and seeds.shape[1] == 3 and len(seeds) > 0: - wmgm[tuple(seeds.T)] = True - return sh, affine, zooms, transient, absorb, dseg, wmgm + sh = np.asarray(z["sh"], dtype=np.float32) + affine = np.asarray(z["affine"], dtype=np.float64) + zooms = tuple(float(x) for x in z["zooms"][:3]) + transient = np.asarray(z["transient"], dtype=bool) + absorb = np.asarray(z["absorb"], dtype=np.int8) + dseg = ( + np.asarray(z["dseg"], dtype=np.uint8) + if "dseg" in z.files + else np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) + ) + wmgm = None + if "seeds" in z.files: + wmgm = np.zeros(transient.shape, dtype=bool) + seeds = np.asarray(z["seeds"], dtype=np.int64) + if seeds.ndim == 2 and seeds.shape[1] == 3 and len(seeds) > 0: + wmgm[tuple(seeds.T)] = True + return sh, affine, zooms, transient, absorb, dseg, wmgm # Case 2: working_dir is a directory (pyAFQ derivatives or folder with NIfTIs / .npz) sh_img = None @@ -196,10 +209,11 @@ def _discover_subject_inputs( if working_dir and Path(working_dir).is_dir(): wdir = Path(working_dir) - # Check if there is a staged subject .npz in the folder - npz_files = sorted(wdir.glob("*sub*.npz")) - if npz_files: - return _discover_subject_inputs(str(npz_files[0]), None, wm_threshold=wm_threshold) + # A staged subject .npz holds sh/transient/absorb arrays; other .npz files in the folder + # (chain caches, transition caches) are not inputs. + for npz_path in sorted(wdir.glob("*.npz")): + if _is_staged_subject_npz(npz_path): + return _discover_subject_inputs(str(npz_path), None, wm_threshold=wm_threshold) all_niis = sorted(wdir.rglob("*.nii*")) for p in all_niis: @@ -296,6 +310,8 @@ def _discover_subject_inputs( if pve_img is not None: csf, gm, wm = np.moveaxis(_on_grid(pve_img, sh_img), -1, 0) + from skimage.segmentation import find_boundaries + edge = find_boundaries(mask, mode="inner") & mask transient = mask & ~edge & (wm > float(wm_threshold)) absorb = np.zeros(mask.shape, np.int8) @@ -326,19 +342,12 @@ def _discover_subject_inputs( absorb[dseg == 4] = 3 absorb[dseg == 5] = 2 else: - # Derive transient WM and absorbing boundary directly from the ODF mask & c0 amplitude - edge = mask & ~ndi.binary_erosion(mask) - c0 = sh[..., 0] - pos_c0 = c0[mask & ~edge] - thresh = float(np.percentile(pos_c0, 20.0)) if pos_c0.size else 0.0 - transient = mask & ~edge & (c0 >= thresh) - absorb = np.zeros(mask.shape, dtype=np.int8) - absorb[mask & ~transient] = 1 - absorb[edge] = 3 - dseg = np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) + # No tissue maps: the caller has to supply a white-matter mask. Guessing tissue classes + # from the fODF would make arbitrary voxels (deep white matter included) valid endpoints. + transient = absorb = dseg = None wmgm = None - if wmgm_img is not None: + if wmgm_img is not None and transient is not None: wmgm = (_on_grid(wmgm_img, sh_img, order=0) > 0) & transient return sh, affine, zooms, transient, absorb, dseg, wmgm @@ -406,12 +415,141 @@ def _export_volumes_from_cached_state( return volume_paths, shape, affine, n_wm, n_states, n_trans -def cmd_build_transitions(req_path: str) -> None: - """Execute ``build_transitions`` and emit ``RESULT ``.""" +MAP_KEYS = ( + "codi_double", + "codi_single", + "coasy", + "p_terminate_double", + "p_terminate_single", + "total_amplitude", + "kl_single", +) + + +def _requested_config(req: Dict[str, Any]): + """The chain settings a build_transitions request asks for, and its maximum length (mm).""" + from .chain import ChainConfig + + ptt = str(req.get("preset", "standard")).lower() == "ptt" + cfg = ChainConfig( + angle=float(req.get("angle_deg", 35.0)), + step=float(req.get("step_vox", 1.0)), + double_odf=bool(req.get("double_odf", True)), + stop_mass=float(req.get("stop_mass_tau", 1e-4 if ptt else 0.0)), + fod_thresh=float(req.get("fod_thresh", 0.08 if ptt else 0.05)), + fod_power=float(req.get("fod_power", 1.5 if ptt else 1.0)), + curv_sigma=float(req.get("curv_sigma_deg", 18.0 if ptt else 0.0)), + probe_radius=float(req.get("probe_radius_vox", 0.5 if ptt else 0.0)), + ) + return cfg, float(req.get("max_length_mm", 250.0)) + + +# build_transitions request keys for each ChainConfig field +_REQUEST_KEYS = { + "angle": "angle_deg", + "step": "step_vox", + "double_odf": "double_odf", + "stop_mass": "stop_mass_tau", + "fod_thresh": "fod_thresh", + "fod_power": "fod_power", + "curv_sigma": "curv_sigma_deg", + "probe_radius": "probe_radius_vox", +} + + +def _check_prebuilt(source, stored_cfg: Dict[str, Any], stored_max_length, req, cfg, max_length_mm) -> None: + """Prebuilt transitions keep the settings they were built with. Refuse a request that asks for + other settings or for tissue-mask overrides instead of silently ignoring them. A request that + names a preset asks for every setting (the preset fills the gaps); otherwise only the settings + it names are checked.""" + import math + from dataclasses import asdict + + from .chain import ChainConfig + + valid = {f for f in ChainConfig.__dataclass_fields__} + built = asdict(ChainConfig(**{k: v for k, v in stored_cfg.items() if k in valid})) + wanted = asdict(cfg) + problems = [] + for key, want in wanted.items(): + if key not in _REQUEST_KEYS or ("preset" not in req and _REQUEST_KEYS[key] not in req): + continue + have = built[key] + if isinstance(want, (bool, str)) or isinstance(have, (bool, str)): + same = have == want + else: + same = math.isclose(float(have), float(want), rel_tol=1e-4, abs_tol=1e-6) + if not same: + problems.append(f"{key} is {have} in the file but {want} was requested") + if stored_max_length is not None and "max_length_mm" in req and not math.isclose( + float(stored_max_length), float(max_length_mm), rel_tol=1e-4 + ): + problems.append(f"max length is {stored_max_length} mm in the file but {max_length_mm} mm was requested") + for key, label in (("transient_mask_path", "transient WM mask"), ("absorb_mask_path", "absorbing mask")): + if req.get(key): + problems.append(f"a {label} can't be applied to prebuilt transitions") + if problems: + raise ValueError( + f"{Path(source).name} holds prebuilt transitions with fixed settings: " + + "; ".join(problems) + + ". Match the node's settings to the file, or point the node at the subject's fODF to " + "build new transitions." + ) + + +def _is_transitions_odx(path) -> bool: + """True for an ODX written by mpat (it carries the chain's stencil arrays), False for a plain fODF ODX.""" + import zipfile + + p = Path(path) + if p.is_dir(): + return any((p / "groups").glob("mpat_Q_ptr.*")) + try: + with zipfile.ZipFile(p) as z: + return any(n.startswith("groups/mpat_Q_ptr") for n in z.namelist()) + except zipfile.BadZipFile: + return False + + +def _mittens_maps(sh_rows: np.ndarray, ijk: np.ndarray, shape, affine: np.ndarray, zooms, cfg): + """MITTENS transition maps (``MAP_KEYS``) for voxels ``ijk`` with fODF SH rows ``sh_rows``. + Returns ``(ijk, {key: values})`` for the voxels MITTENS fitted.""" import mittens from mittens.io import OdfData - from .chain import Chain, ChainConfig + n_coef = int(sh_rows.shape[1]) + sym_order = int(round((-3.0 + np.sqrt(1.0 + 8.0 * n_coef)) / 2.0)) + if (sym_order + 1) * (sym_order + 2) // 2 == n_coef: + sh_order, full_basis = sym_order, False + else: + sh_order, full_basis = int(round(np.sqrt(n_coef) - 1.0)), True + odf_data = OdfData.from_sh( + sh_rows, ijk, tuple(shape), affine, sh_order=sh_order, sh_basis="descoteaux07", full_basis=full_basis + ) + step_mm = float(cfg.step * min(zooms)) + sigma_rad = max(np.deg2rad(cfg.curv_sigma), 0.05) + model = mittens.TransitionModel( + step_mm=step_mm, + angle_max=cfg.angle, + turning="vmf" if cfg.curv_sigma > 0.0 else "flat", + persistence_length_mm=float(step_mm * sigma_rad**2), + tau=cfg.stop_mass, + tau0=cfg.stop_mass, + odf_power=cfg.fod_power, + ) + fit = model.fit(odf_data) + maps = dict(fit.maps()) + maps["kl_single"] = fit.kl_single + clean = { + k: np.nan_to_num(np.asarray(maps[k], dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0) for k in MAP_KEYS + } + return np.asarray(fit.ijk), clean + + +def cmd_build_transitions(req_path: str) -> None: + """Execute ``build_transitions`` and emit ``RESULT ``.""" + + from .chain import Chain from .fixels import segment_lobes from .solve import overlength_states, prepare_launches, segment_bundles @@ -423,6 +561,7 @@ def cmd_build_transitions(req_path: str) -> None: out_dir.mkdir(parents=True, exist_ok=True) _emit_progress(1, 6) + cfg, max_length_mm = _requested_config(req) # Fast path 0: Did the user point working_dir or odx_path directly at a precomputed # mpat_transitions_*.npz (or *_transitions_dwimap.odx) archive? @@ -432,6 +571,9 @@ def cmd_build_transitions(req_path: str) -> None: if Path(direct_cand).is_file() and str(direct_cand).endswith(".npz"): z_try = np.load(direct_cand) if "Q_ptr" in z_try.files and "L_seeds" in z_try.files and "shape" in z_try.files: + if "cfg_json" not in z_try.files: + raise ValueError(f"{Path(direct_cand).name} does not record the settings it was built with") + _check_prebuilt(direct_cand, json.loads(str(z_try["cfg_json"])), None, req, cfg, max_length_mm) _emit_progress(5, 6) volume_paths, shape, affine, n_wm, n_states, n_trans = _export_volumes_from_cached_state( z_try, out_dir @@ -454,61 +596,59 @@ def cmd_build_transitions(req_path: str) -> None: json.dump(result, fh, indent=2) print(f"RESULT {json.dumps(result)}", flush=True) return - elif str(direct_cand).endswith((".odx", ".odxd")): + elif str(direct_cand).endswith((".odx", ".odxd")) and _is_transitions_odx(direct_cand): + # Transitions written by mpat: reuse the chain as built. A plain fODF ODX falls through + # to the full build below. from .transitions import load_transitions_odx - try: - chain_odx, extras = load_transitions_odx(direct_cand, return_extras=True) - except Exception: # noqa: BLE001 - chain_odx, extras = None, None - if chain_odx is not None and extras is not None and "launches" in extras: - _emit_progress(5, 6) - affine = extras["affine"] - shape = chain_odx.shape - dpv = extras.get("dpv") or {} - volume_paths = {} - for map_key, fallback_key in ( - ("codi_double", "codi"), - ("codi_single", "codi"), - ("coasy", "coasy"), - ("p_terminate_double", "p_absorb"), - ("p_terminate_single", "p_absorb"), - ("total_amplitude", "p_absorb"), - ("kl_single", "codi"), - ): - vals = dpv.get(map_key) - if vals is None: - vals = dpv.get(fallback_key, np.zeros(chain_odx.t_lin.size, dtype=np.float32)) - vol = chain_odx.to_volume(np.asarray(vals, dtype=np.float32).ravel()) - volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") - dead_mean = dpv.get( - "dead_mean", - chain_odx.dead.reshape(-1, chain_odx.nb).mean(axis=1).astype(np.float32), - ) - volume_paths["chain_dead"] = _save_nifti( - chain_odx.to_volume(np.asarray(dead_mean, dtype=np.float32).ravel()), - affine, - out_dir / "chain_dead.nii", - ) - _emit_progress(6, 6) - elapsed = time.perf_counter() - t_start - fp_h = str((extras["header"].get("mpat") or {}).get("fingerprint", "")) - result = { - "state_path": str(Path(direct_cand).resolve()), - "fp_hash": fp_h, - "dims": list(shape), - "voxel_to_ras": affine.tolist(), - "volumes": volume_paths, - "summary": ( - f"Loaded ODX [{Path(direct_cand).name}]: " - f"{chain_odx.t_lin.size:,} WM voxels ({chain_odx.n_states:,} states, " - f"{chain_odx.n_transitions / 1e6:.1f}M transitions) in {elapsed:.1f}s" - ), - } - with open(out_dir / "transitions_result.json", "w") as fh: - json.dump(result, fh, indent=2) - print(f"RESULT {json.dumps(result)}", flush=True) - return + name = Path(direct_cand).name + chain_odx, extras = load_transitions_odx(direct_cand, return_extras=True) + if "launches" not in extras: + raise ValueError(f"{name} has no seed launches; rewrite it with mpat run --save-transitions") + if extras.get("sh_rows") is None: + raise ValueError(f"{name} has no fODF SH coefficients to compute the transition maps from") + mpat_meta = extras["header"].get("mpat") or {} + _check_prebuilt( + direct_cand, mpat_meta.get("config") or {}, mpat_meta.get("max_length_mm"), req, cfg, max_length_mm + ) + _emit_progress(4, 6) + affine = extras["affine"] + shape = chain_odx.shape + # The same MITTENS maps the full build computes, from the fODF stored in the ODX + # (white-matter voxels only: that is all the ODX keeps). + wm_ijk = np.stack(np.unravel_index(chain_odx.t_lin, chain_odx.pshape), 1) - 1 + map_ijk, maps = _mittens_maps(extras["sh_rows"], wm_ijk, shape, affine, extras["zooms"], chain_odx.cfg) + volume_paths = {} + for map_key, vals in maps.items(): + vol = np.zeros(shape, dtype=np.float32) + vol[tuple(map_ijk.T)] = vals + volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") + dpv = extras.get("dpv") or {} + dead_mean = dpv.get("dead_mean") + if dead_mean is None: + dead_mean = chain_odx.dead.reshape(-1, chain_odx.nb).mean(axis=1) + volume_paths["chain_dead"] = _save_nifti( + chain_odx.to_volume(np.asarray(dead_mean, dtype=np.float32).ravel()), + affine, + out_dir / "chain_dead.nii", + ) + _emit_progress(6, 6) + elapsed = time.perf_counter() - t_start + result = { + "state_path": str(Path(direct_cand).resolve()), + "fp_hash": str(mpat_meta.get("fingerprint", "")), + "dims": list(shape), + "voxel_to_ras": affine.tolist(), + "volumes": volume_paths, + "summary": ( + f"Loaded ODX [{name}]: {chain_odx.t_lin.size:,} WM voxels ({chain_odx.n_states:,} states, " + f"{chain_odx.n_transitions / 1e6:.1f}M transitions) in {elapsed:.1f}s" + ), + } + with open(out_dir / "transitions_result.json", "w") as fh: + json.dump(result, fh, indent=2) + print(f"RESULT {json.dumps(result)}", flush=True) + return wm_threshold = float(req.get("wm_threshold", 0.4)) sh, affine, zooms, transient, absorb, dseg, wmgm = _discover_subject_inputs( @@ -516,15 +656,31 @@ def cmd_build_transitions(req_path: str) -> None: req.get("odx_path"), wm_threshold=wm_threshold, ) - shape = tuple(int(d) for d in transient.shape) + shape = tuple(int(d) for d in sh.shape[:3]) + fodf_mask = np.any(sh != 0, axis=-1) - # Apply optional user-wired transient or absorbing masks + # Optional user-wired transient (white-matter) mask + t_override = None if req.get("transient_mask_path") and Path(req["transient_mask_path"]).exists(): t_override = _resample_mask_to_grid(nib.load(req["transient_mask_path"]), shape, affine) - if t_override.any(): - transient = t_override & np.any(sh != 0, axis=-1) - absorb[transient] = 0 - absorb[(absorb == 0) & np.any(sh != 0, axis=-1) & ~transient] = 1 + if not t_override.any(): + t_override = None + if transient is None: + if t_override is None: + raise ValueError( + "No tissue maps were found for this fODF (pyAFQ pve_internal, desc-mpat_dseg, or a staged " + "subject .npz). Wire a Transient WM Mask into the node, or point it at the subject's " + "pyAFQ folder." + ) + edge = fodf_mask & ~ndi.binary_erosion(fodf_mask) + transient = t_override & fodf_mask & ~edge + absorb = np.zeros(shape, dtype=np.int8) + absorb[fodf_mask & ~transient] = 1 + absorb[edge] = 3 + elif t_override is not None: + transient = t_override & fodf_mask + absorb[transient] = 0 + absorb[(absorb == 0) & fodf_mask & ~transient] = 1 if req.get("absorb_mask_path") and Path(req["absorb_mask_path"]).exists(): a_override = _resample_mask_to_grid(nib.load(req["absorb_mask_path"]), shape, affine) @@ -534,27 +690,6 @@ def cmd_build_transitions(req_path: str) -> None: _emit_progress(2, 6) - preset = str(req.get("preset", "standard")).lower() - angle_deg = float(req.get("angle_deg", 35.0)) - step_vox = float(req.get("step_vox", 1.0)) - double_odf = bool(req.get("double_odf", True)) - fod_thresh = float(req.get("fod_thresh", 0.08 if preset == "ptt" else 0.05)) - fod_power = float(req.get("fod_power", 1.5 if preset == "ptt" else 1.0)) - stop_mass_tau = float(req.get("stop_mass_tau", 1e-4 if preset == "ptt" else 0.0)) - curv_sigma_deg = float(req.get("curv_sigma_deg", 18.0 if preset == "ptt" else 0.0)) - probe_radius_vox = float(req.get("probe_radius_vox", 0.5 if preset == "ptt" else 0.0)) - max_length_mm = float(req.get("max_length_mm", 250.0)) - - cfg = ChainConfig( - angle=angle_deg, - step=step_vox, - double_odf=double_odf, - stop_mass=stop_mass_tau, - fod_thresh=fod_thresh, - fod_power=fod_power, - curv_sigma=curv_sigma_deg, - probe_radius=probe_radius_vox, - ) fp_hash = _compute_transitions_hash(cfg.key(), max_length_mm, sh, affine, transient, absorb) hashed_filename = f"mpat_transitions_{fp_hash}.npz" @@ -616,60 +751,17 @@ def cmd_build_transitions(req_path: str) -> None: return # Full build path: - # 1. Compute MITTENS v2 transition probability maps across the active mask - min_zoom = float(min(zooms)) - step_mm = float(step_vox * min_zoom) - turning = "vmf" if curv_sigma_deg > 0.0 else "flat" - sigma_rad = max(np.deg2rad(curv_sigma_deg), 0.05) - persistence_mm = float(step_mm * (sigma_rad ** 2)) - - odf_mask = (transient | (absorb == 1) | (absorb == 3)) & np.any(sh != 0, axis=-1) + # 1. MITTENS v2 transition probability maps across the fODF voxels that walkers use + odf_mask = (transient | (absorb == 1) | (absorb == 3)) & fodf_mask ijk_odf = np.argwhere(odf_mask) - n_coef = int(sh.shape[-1]) - sh_order_sym = int(round((-3.0 + np.sqrt(1.0 + 8.0 * n_coef)) / 2.0)) - if (sh_order_sym + 1) * (sh_order_sym + 2) // 2 == n_coef: - sh_order = sh_order_sym - full_basis = False - else: - sh_order = int(round(np.sqrt(n_coef) - 1.0)) - full_basis = True - odf_data = OdfData.from_sh( - sh[tuple(ijk_odf.T)], - ijk_odf, - shape, - affine, - sh_order=sh_order, - sh_basis="descoteaux07", - full_basis=full_basis, - ) - t_model = mittens.TransitionModel( - step_mm=step_mm, - angle_max=angle_deg, - turning=turning, - persistence_length_mm=persistence_mm, - tau=stop_mass_tau, - tau0=stop_mass_tau, - odf_power=fod_power, - ) - t_res = t_model.fit(odf_data) - m_maps = dict(t_res.maps()) - m_maps["kl_single"] = t_res.kl_single + map_ijk, maps = _mittens_maps(sh[tuple(ijk_odf.T)], ijk_odf, shape, affine, zooms, cfg) volume_paths: Dict[str, str] = {} - mit_arrays: Dict[str, np.ndarray] = {"mit_ijk": np.asarray(t_res.ijk, dtype=np.int32)} - for map_key in ( - "codi_double", - "codi_single", - "coasy", - "p_terminate_double", - "p_terminate_single", - "total_amplitude", - "kl_single", - ): - vals = np.nan_to_num(np.asarray(m_maps[map_key], dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0) + mit_arrays: Dict[str, np.ndarray] = {"mit_ijk": map_ijk.astype(np.int32)} + for map_key, vals in maps.items(): mit_arrays[f"mit_{map_key}"] = vals vol = np.zeros(shape, dtype=np.float32) - vol[tuple(t_res.ijk.T)] = vals + vol[tuple(map_ijk.T)] = vals volume_paths[map_key] = _save_nifti(vol, affine, out_dir / f"{map_key}.nii") _emit_progress(3, 6) @@ -796,10 +888,8 @@ def _reconstruct_state(state_path: str): """Fast O(1) reconstruction of ``(chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms)`` from ``mpat_transitions_*.npz`` or ``*_transitions_dwimap.odx`` without rebuilding geometry or ODF integrals. """ - from . import kernel as K from .chain import Chain, ChainConfig from .fixels import Lobes, _sh_fingerprint, segment_lobes - from .geometry import build_geometry from .solve import Launches if str(state_path).endswith((".odx", ".odxd")): @@ -913,6 +1003,68 @@ class _GeoProxy: return chain, launches, default_seed_ok, sh_rows, lobes, whole_dc, affine, zooms +def _stream_backward(streamer, chain, it, res, total, term, colsign, n_kinds, log_tol) -> None: + """Stream a backward-solve frame: the completion wavefront blended with the + waypoint-conditioned completion probability so far.""" + if streamer is None or not (it == 1 or it % 2 == 0): + return + nc, nb, Nt = chain.ncomp, chain.nb, chain.t_lin.size + w_step = np.clip(term[::nc, :n_kinds].sum(1).reshape(Nt, nb).mean(1), 0.0, None) + w_max = float(w_step.max()) + if w_max > 1e-20: + w_step = w_step / w_max + b_cond = np.clip((total[::nc] @ colsign).reshape(Nt, nb).mean(1), 0.0, None) + b_max = float(b_cond.max()) + b_vis = 0.60 * (b_cond / b_max) + 0.40 * w_step if b_max > 1e-20 else w_step + streamer.emit_transient_values(b_vis, phase=1, step=it, residual=res, force=True) + frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 + _emit_progress(int(round(frac * 100)), 200) + if streamer.pace_sec > 0.0: + time.sleep(streamer.pace_sec) + + +def _stream_forward(streamer, chain, it, res, total, term, beta, colsign, log_tol) -> None: + """Stream a forward-solve frame: the bundle density so far blended with this step's wavefront.""" + if streamer is None or not (it == 1 or it % 2 == 0): + return + from . import kernel as K + + nc, nb, Nt, Ns = chain.ncomp, chain.nb, chain.t_lin.size, chain.n_states + beta_c = beta if beta.flags.c_contiguous else np.ascontiguousarray(beta) + + def density(x): + x = x if x.flags.c_contiguous else np.ascontiguousarray(x) + return np.clip(K.paired_density(x, beta_c, colsign, Ns, nc).reshape(Nt, nb).sum(1), 0.0, None) + + d_tot, d_wave = density(total), density(term) + t_max, w_max = float(d_tot.max()), float(d_wave.max()) + if t_max > 1e-20 and w_max > 1e-20: + d_vis = (0.70 * (d_tot / t_max) + 0.30 * (d_wave / w_max)) * t_max + else: + d_vis = d_tot + streamer.emit_transient_values(d_vis, phase=2, step=it, residual=res, force=True) + frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 + _emit_progress(100 + int(round(frac * 95)), 200) + if streamer.pace_sec > 0.0: + time.sleep(streamer.pace_sec) + + +def _ends_outside_absorbers(chain, spec: Dict[str, Any]) -> bool: + """True when a start/end ROI touches no valid absorbing voxel (an ROI inside white matter). + Only the custom-region solver can end walks there.""" + from .chain import VALID_ENDS + + a_valid = np.isin(chain.a_class, np.asarray(VALID_ENDS)) + for key in ("start", "end"): + m = spec.get(key) + if m is not None and np.any(m): + padded = np.zeros(chain.pshape, dtype=bool) + padded[1:-1, 1:-1, 1:-1] = m + if not np.any(padded.ravel()[chain.a_lin] & a_valid): + return True + return False + + def _solve_bundle_with_custom_regions( chain, launches, @@ -921,10 +1073,12 @@ def _solve_bundle_with_custom_regions( no_end_mask: Optional[np.ndarray], tol: float = 1e-6, accel: Any = "mr", - use_cascade: bool = True, streamer: Optional[LiveDensityStreamer] = None, ): - """Solve a bundle specification with support for: + """Solve a bundle whose regions mpat.solve can't express: absorption inside white matter + (``term_mask``, or start/end ROIs that touch no valid absorbing voxel) and ``no_end_mask``. + Bundles without them go through :func:`mpat.solve.segment_bundles`, as in ``mpat run``. + Supports: - ``include`` (waypoint ROIs), - ``exclude`` (avoid ROIs + outside of limiting_mask), - ``start`` / ``end`` (endpoint ROIs), @@ -1027,30 +1181,11 @@ def _padded(m: np.ndarray) -> np.ndarray: mask = p.mask.copy() r_rhs *= mask - Nt = chain.t_lin.size colsign = p.signs[p.xcol] log_tol = float(np.log10(max(tol, 1e-12))) def _on_bwd_step(it: int, res: float, total: np.ndarray, term: np.ndarray) -> None: - if streamer is not None and (it == 1 or it % 2 == 0): - # Wave front at power iteration step t from start & end ROIs (columns 0..nK) - w_step = np.clip(term[::nc, : p.nK].sum(1).reshape(Nt, nb).mean(1), 0.0, None) - w_max = float(w_step.max()) - if w_max > 1e-20: - w_step = w_step / w_max - # Waypoint-conditioned accumulated backward hitting probability - b_cond = np.clip((total[::nc] @ colsign).reshape(Nt, nb).mean(1), 0.0, None) - b_max = float(b_cond.max()) - if b_max > 1e-20: - b_cond = b_cond / b_max - b_vis = 0.60 * b_cond + 0.40 * w_step - else: - b_vis = w_step - streamer.emit_transient_values(b_vis, phase=1, step=it, residual=res, force=True) - frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 - _emit_progress(int(round(frac * 100)), 200) - if getattr(streamer, "pace_sec", 0.0) > 0.0: - time.sleep(streamer.pace_sec) + _stream_backward(streamer, chain, it, res, total, term, colsign, p.nK, log_tol) bwd_accel = False if (streamer is not None and getattr(streamer, "pace_sec", 0.0) > 0.0) else accel beta, info_b = _solve( @@ -1109,28 +1244,7 @@ def _on_bwd_step(it: int, res: float, total: np.ndarray, term: np.ndarray) -> No beta_c = np.ascontiguousarray(beta) def _on_fwd_step(it: int, res: float, total: np.ndarray, term: np.ndarray) -> None: - if streamer is not None and (it == 1 or it % 2 == 0): - d_tot = np.clip( - K.paired_density(np.ascontiguousarray(total), beta_c, colsign, Ns, nc).reshape(Nt, nb).sum(1), - 0.0, - None, - ) - d_wave = np.clip( - K.paired_density(np.ascontiguousarray(term), beta_c, colsign, Ns, nc).reshape(Nt, nb).sum(1), - 0.0, - None, - ) - t_max = float(d_tot.max()) - w_max = float(d_wave.max()) - if t_max > 1e-20 and w_max > 1e-20: - d_vis = (0.70 * (d_tot / t_max) + 0.30 * (d_wave / w_max)) * t_max - else: - d_vis = d_tot - streamer.emit_transient_values(d_vis, phase=2, step=it, residual=res, force=True) - frac = float(np.clip(np.log10(max(res, 1e-12)) / log_tol, 0.0, 1.0)) if log_tol < 0 else 0.5 - _emit_progress(100 + int(round(frac * 95)), 200) - if getattr(streamer, "pace_sec", 0.0) > 0.0: - time.sleep(streamer.pace_sec) + _stream_forward(streamer, chain, it, res, total, term, beta_c, colsign, log_tol) # When live streaming is active, run the forward pass unaccelerated (accel=False) # so the Markov chain steps smoothly t=1,2,3,... and animates the bundle growth. @@ -1207,6 +1321,7 @@ def cmd_solve_bundle(req_path: str) -> None: from .afq import seal_26 as apply_seal_26 from .branches import extract_branch_arbor, extract_flux_streamlines, write_trx from .quantify import quantify_bundle + from .solve import segment_bundles t_start = time.perf_counter() with open(req_path, "r") as fh: @@ -1277,24 +1392,25 @@ def cmd_solve_bundle(req_path: str) -> None: if m.any(): no_end_mask = m - # Optional midline exclusion rule - midline_raw = req.get("midline_exclusion", "auto") - if isinstance(midline_raw, bool): - midline_mode = "auto" if midline_raw else "none" - else: - midline_mode = str(midline_raw).lower() - if midline_mode == "true": - midline_mode = "auto" - elif midline_mode == "false": - midline_mode = "none" + # Optional midline exclusion: keep a one-sided bundle in its hemisphere. True picks the side + # the way mpat.run does (the name, "Left ..." / "..._L", else the ROI centres); "left" / + # "right" force it. + midline_raw = req.get("midline_exclusion", False) + midline_mode = str(midline_raw).strip().lower() if midline_raw not in (None, False, True) else midline_raw + if midline_mode in ("true", "on", "auto"): + midline_mode = True + elif midline_mode in ("false", "off", "none", ""): + midline_mode = False midline_tol_mm = float(req.get("midline_tol_mm", 0.0)) bundle_name = str(req.get("bundle_name") or "Bundle") - if midline_mode in ("left", "right") or ( - midline_mode == "auto" - and any(tok in bundle_name.lower() for tok in ("left", "right", "_l", "_r")) - ): + if midline_mode: + from .afq import _is_left + xyz_x = nib.affines.apply_affine(affine, np.indices(shape).reshape(3, -1).T)[:, 0].reshape(shape) - is_left = midline_mode == "left" or bundle_name.lower().startswith("left") or bundle_name.lower().endswith("_l") or "left" in bundle_name.lower() + if midline_mode in ("left", "right"): + is_left = midline_mode == "left" + else: + is_left = _is_left(bundle_name, {"include": include_masks, "start": start_mask, "end": end_mask}, xyz_x) mid_exc = (xyz_x > midline_tol_mm) if is_left else (xyz_x < -midline_tol_mm) exclude_mask = mid_exc if exclude_mask is None else (exclude_mask | mid_exc) @@ -1310,8 +1426,6 @@ def cmd_solve_bundle(req_path: str) -> None: tol = float(req.get("solver_tol") or req.get("tol") or 1e-6) accel_str = str(req.get("solver_accel") or req.get("accel") or "mr").lower() accel: Any = False if accel_str in ("none", "false", "") else accel_str - use_cascade = bool(req.get("use_cascade", True)) - explicit_stream = bool(req.get("stream_mmap_path")) stream_mmap_path = req.get("stream_mmap_path") or str(out_dir / "live_density.mmap") streamer: Optional[LiveDensityStreamer] = None @@ -1321,17 +1435,38 @@ def cmd_solve_bundle(req_path: str) -> None: except Exception: streamer = None - res = _solve_bundle_with_custom_regions( - chain, - active_launches, - spec, - term_mask=term_mask, - no_end_mask=no_end_mask, - tol=tol, - accel=accel, - use_cascade=use_cascade, - streamer=streamer, - ) + if term_mask is not None or no_end_mask is not None or _ends_outside_absorbers(chain, spec): + res = _solve_bundle_with_custom_regions( + chain, + active_launches, + spec, + term_mask=term_mask, + no_end_mask=no_end_mask, + tol=tol, + accel=accel, + streamer=streamer, + ) + else: + # The same solver mpat run uses. Live streaming runs it unaccelerated so the frames + # advance one step at a time. + log_tol = float(np.log10(max(tol, 1e-12))) + + def on_step(st) -> None: + if st.phase == "backward": + _stream_backward(streamer, chain, st.it, st.res, st.total, st.term, st.colsign, st.n_kinds, log_tol) + else: + _stream_forward(streamer, chain, st.it, st.res, st.total, st.term, st.beta, st.colsign, log_tol) + + pacing = streamer is not None and streamer.pace_sec > 0.0 + res = segment_bundles( + chain, + [spec], + active_launches, + tol=tol, + accel=False if pacing else accel, + on_step=on_step if streamer is not None else None, + )[bundle_name] + res.interior_endpoints_t = None _emit_progress(3, 5) qb = quantify_bundle( @@ -1507,7 +1642,6 @@ def cmd_precompute_cli(argv: List[str]) -> int: target_dir = Path(a.out_dir).resolve() if a.out_dir else (inp if inp.is_dir() else inp.parent) target_dir.mkdir(parents=True, exist_ok=True) - is_ptt = a.preset == "ptt" with tempfile.TemporaryDirectory(prefix="mpat_precompute_") as tmp: req = { "out_dir": tmp, @@ -1517,15 +1651,20 @@ def cmd_precompute_cli(argv: List[str]) -> int: "preset": a.preset, "angle_deg": a.angle_deg, "step_vox": a.step_vox, - "double_odf": not a.single_odf and (not is_ptt), - "fod_thresh": a.fod_thresh if a.fod_thresh is not None else (0.08 if is_ptt else 0.05), - "fod_power": a.fod_power if a.fod_power is not None else (2.0 if is_ptt else 1.0), - "stop_mass_tau": a.stop_mass_tau if a.stop_mass_tau is not None else (0.25 if is_ptt else 0.0), - "curv_sigma_deg": a.curv_sigma_deg if a.curv_sigma_deg is not None else (22.5 if is_ptt else 0.0), - "probe_radius_vox": a.probe_radius_vox if a.probe_radius_vox is not None else (0.35 if is_ptt else 0.0), + "double_odf": not a.single_odf, "max_length_mm": a.max_length_mm, "wm_threshold": a.wm_threshold, } + # Unset options take the preset's defaults (those of mpat.run) in _requested_config. + for key, value in ( + ("fod_thresh", a.fod_thresh), + ("fod_power", a.fod_power), + ("stop_mass_tau", a.stop_mass_tau), + ("curv_sigma_deg", a.curv_sigma_deg), + ("probe_radius_vox", a.probe_radius_vox), + ): + if value is not None: + req[key] = value req_file = Path(tmp) / "req.json" req_file.write_text(json.dumps(req, indent=2)) cmd_build_transitions(str(req_file)) diff --git a/tests/test_trxviz_bridge.py b/tests/test_trxviz_bridge.py index 63732ac..a23f778 100644 --- a/tests/test_trxviz_bridge.py +++ b/tests/test_trxviz_bridge.py @@ -4,6 +4,7 @@ import nibabel as nib import numpy as np +import pytest from mpat.trxviz_bridge import cmd_build_transitions, cmd_solve_bundle @@ -134,6 +135,15 @@ def test_trxviz_bridge_transitions_and_custom_rois(tmp_path: Path): assert res_direct["state_path"] == res_trans["state_path"] assert "Loaded [mpat_transitions_" in res_direct["summary"] + # Prebuilt transitions keep their settings: asking for others is an error, not silently ignored + req_other = tmp_path / "req_other.json" + req_other.write_text( + json.dumps({"out_dir": str(tmp_path / "other"), "working_dir": res_trans["state_path"], + "preset": "ptt", "angle_deg": 60.0}) + ) + with pytest.raises(ValueError, match="angle"): + cmd_build_transitions(str(req_other)) + # Prepare start, end, include, avoid, and interior absorption ROI masks start_mask = np.zeros((nx, ny, nz), dtype=np.uint8) start_mask[1, 3:-3, 1:-1] = 1 @@ -244,3 +254,32 @@ def test_trxviz_bridge_transitions_and_custom_rois(tmp_path: Path): ep_vol3 = np.asarray(nib.load(res_s3["volumes"]["endpoints"]).dataobj) # Verify walkers absorbed inside the interior term_mask (i=6..7) assert float(ep_vol3[6:8, 3:-3, 1:-1].sum()) > 0.5 + + +def test_trxviz_bridge_inputs_are_not_guessed(tmp_path: Path): + from mpat.trxviz_bridge import _discover_subject_inputs + + nx, ny, nz = 8, 6, 4 + affine = np.diag([2.0, 2.0, 2.0, 1.0]) + sh = np.zeros((nx, ny, nz, 45), dtype=np.float32) + sh[1:-1, 1:-1, 1:-1] = _sh([(1.0, 0.0, 0.0)]) + transient = np.zeros((nx, ny, nz), dtype=bool) + transient[2:-2, 2:-2, 1:-1] = True + absorb = np.where(sh.any(-1) & ~transient, 1, 0).astype(np.int8) + + # A folder's chain cache (sorted first here) is not mistaken for the staged subject + folder = tmp_path / "subject" + folder.mkdir() + np.savez(folder / "sub-01_desc-chain_cache.npz", Q_ptr=np.zeros(3)) + np.savez(folder / "sub-01_staged.npz", sh=sh, affine=affine, zooms=np.array([2.0, 2.0, 2.0]), + transient=transient, absorb=absorb) + assert np.array_equal(_discover_subject_inputs(str(folder), None)[3], transient) + + # An fODF without tissue maps is an error, not a guess at which voxels are white matter + bare = tmp_path / "bare" + bare.mkdir() + nib.save(nib.Nifti1Image(sh, affine), str(bare / "sub-01_model-csd_dwimap.nii.gz")) + req = tmp_path / "req.json" + req.write_text(json.dumps({"out_dir": str(tmp_path / "out"), "working_dir": str(bare)})) + with pytest.raises(ValueError, match="No tissue maps"): + cmd_build_transitions(str(req))