Source code for mpat.geometry

"""Directions, turning cone and within-voxel paths (MITTENS v2), and fODFs on them (DIPY).

MITTENS enumerates every hop sequence a fiber can take inside a voxel before it exits
into one of the 26 neighbours, with the exact volume of start points that realise it.
MPAT adds what MITTENS's first-order model does not need: the last hop's direction class
(the walker's memory, carried into the next voxel) and each path's box of start points
(the spatial-moment closure).
"""
from __future__ import annotations

from dataclasses import dataclass

import mittens
import numpy as np
from mittens.io import default_sphere

OFFSETS = np.asarray(mittens.neighbor_offsets(), np.int64)  # (26, 3), lexicographic
PMF_THRESHOLD = 0.05      # sphere values below this x max are zeroed (pyAFQ's tracker)
PEAK_THRESHOLD = 0.25     # seed peaks: relative threshold, min separation (pyAFQ's tracker)
PEAK_SEPARATION = 45.0


@dataclass
class Geometry:
    vertices: np.ndarray   # (V, 3) signed directions, voxel axes
    cone_ptr: np.ndarray   # CSR: directions within the turning angle of each direction
    cone_idx: np.ndarray
    p_vol: np.ndarray      # (P,) start volume of each path (fraction of the voxel)
    p_dirs: np.ndarray     # (P, Lmax) hop directions, -1 padded
    p_len: np.ndarray      # (P,)
    p_nbr: np.ndarray      # (P,) exit neighbour
    p_disp: np.ndarray     # (P, 3) total displacement, voxel units
    lo: np.ndarray         # (P, 3) box of start points in [0, 1]^3
    hi: np.ndarray
    vbin: np.ndarray       # (V,) direction class (nearest of the 26 neighbour directions)
    bin_ptr: np.ndarray    # CSR: vertices of each class
    bin_idx: np.ndarray
    p_trip: np.ndarray     # (P,) index of the path's (first hop, neighbour, last class) triple
    d1_ptr: np.ndarray     # triples sorted by first hop: CSR over directions
    t_nbr: np.ndarray
    t_bin: np.ndarray
    nb: int = 26
    # Preorder prefix tree over hop sequences (for O(1) zero-ODF subtree skipping)
    u_dir: np.ndarray = None
    u_parent: np.ndarray = None
    u_d1: np.ndarray = None
    u_skip: np.ndarray = None
    u_eptr: np.ndarray = None
    e_vol: np.ndarray = None
    e_nbr: np.ndarray = None
    e_trip: np.ndarray = None
    e_orig: np.ndarray = None
    # Optional PTT (Parallel Transport Tractography) curvature & co-circularity weights
    cone_w: np.ndarray = None
    u_curv_w: np.ndarray = None
    u_pt_dir: np.ndarray = None

    @property
    def n_dirs(self):
        return self.vertices.shape[0]

    def antipode(self):
        return np.argmin(self.vertices @ self.vertices.T, axis=1)


def _build_prefix_tree(p_dirs, p_len, p_vol, p_nbr, p_trip, vertices=None, curv_sigma=0.0):
    """Compile flat path emissions into a preorder prefix tree over hop sequences."""
    P = p_dirs.shape[0]
    children = [{}]
    node_dir = [-1]
    node_parent = [-1]
    node_d1 = [-1]
    node_emiss = [[]]

    for p in range(P):
        L = int(p_len[p])
        cur = 0
        d1 = int(p_dirs[p, 0])
        for i in range(L):
            d = int(p_dirs[p, i])
            ch = children[cur].get(d)
            if ch is None:
                ch = len(children)
                children[cur][d] = ch
                children.append({})
                node_dir.append(d)
                node_parent.append(cur)
                node_d1.append(d1)
                node_emiss.append([])
            cur = ch
        node_emiss[cur].append(p)

    n_nodes = len(children) - 1
    u_dir = np.empty(n_nodes, np.int64)
    u_parent = np.empty(n_nodes, np.int64)
    u_d1 = np.empty(n_nodes, np.int64)
    u_skip = np.empty(n_nodes, np.int64)
    u_eptr = np.zeros(n_nodes + 1, np.int64)
    e_orig = np.empty(P, np.int64)

    old_to_pre = np.full(len(children), -1, np.int64)
    stack = [(children[0][d], False) for d in sorted(children[0].keys(), reverse=True)]
    pre_idx = 0
    emiss_idx = 0
    while stack:
        nid, exiting = stack.pop()
        if exiting:
            u_skip[old_to_pre[nid]] = pre_idx
            continue
        u = pre_idx
        pre_idx += 1
        old_to_pre[nid] = u
        u_dir[u] = node_dir[nid]
        par = node_parent[nid]
        u_parent[u] = -1 if par == 0 else old_to_pre[par]
        u_d1[u] = node_d1[nid]
        for p in node_emiss[nid]:
            e_orig[emiss_idx] = p
            emiss_idx += 1
        u_eptr[u + 1] = emiss_idx
        stack.append((nid, True))
        for d in sorted(children[nid].keys(), reverse=True):
            stack.append((children[nid][d], False))

    u_curv_w = np.ones(n_nodes, np.float64)
    u_pt_dir = u_dir.copy()
    if vertices is not None and curv_sigma > 0.0:
        sig_rad = np.deg2rad(float(curv_sigma))
        inv_2s2 = 0.5 / max(sig_rad * sig_rad, 1e-12)
        for u in range(n_nodes):
            par = u_parent[u]
            if par >= 0:
                u_prev = vertices[u_dir[par]]
                u_cur = vertices[u_dir[u]]
                theta = np.arccos(np.clip(np.dot(u_prev, u_cur), -1.0, 1.0))
                w = np.exp(-theta * theta * inv_2s2)
                gpar = u_parent[par]
                if gpar >= 0:
                    # Co-circularity: penalise change in curvature vector (suppress S-wiggles)
                    u_gprev = vertices[u_dir[gpar]]
                    dk = (u_cur - u_prev) - (u_prev - u_gprev)
                    w *= np.exp(-np.dot(dk, dk) * inv_2s2)
                u_curv_w[u] = w
                # Parallel-transported geodesic continuation direction into neighbour voxel
                u_first = vertices[u_d1[u]]
                c_dot = np.dot(u_first, u_cur)
                v_refl = 2.0 * c_dot * u_cur - u_first
                v_extrap = 0.5 * u_cur + 0.5 * v_refl
                u_pt_dir[u] = int(np.argmax(vertices @ v_extrap))

    return (u_dir, u_parent, u_d1, u_skip, u_eptr,
            np.ascontiguousarray(p_vol[e_orig]),
            np.ascontiguousarray(p_nbr[e_orig]),
            np.ascontiguousarray(p_trip[e_orig]),
            e_orig,
            u_curv_w,
            u_pt_dir)


def class_chord_lengths(geo: Geometry, zooms=None):
    """Expected inter-voxel step length (in voxel units if ``zooms is None``, else in mm)
    for each of the 26 direction classes, weighted by path volume over each class's cone."""
    nbr_disp = OFFSETS.astype(np.float64)
    if zooms is not None:
        nbr_disp = nbr_disp * np.abs(np.asarray(zooms, float))[None, :]
    nbr_len = np.linalg.norm(nbr_disp, axis=1)
    p_len = nbr_len[geo.p_nbr]
    V = geo.n_dirs
    d1 = geo.p_dirs[:, 0]
    vol_d1 = np.bincount(d1, weights=geo.p_vol, minlength=V)
    len_d1 = np.bincount(d1, weights=geo.p_vol * p_len, minlength=V)
    out = np.zeros(geo.nb)
    for b in range(geo.nb):
        es = geo.bin_idx[geo.bin_ptr[b]:geo.bin_ptr[b + 1]]
        w_tot = l_tot = 0.0
        for e in es:
            ds = geo.cone_idx[geo.cone_ptr[e]:geo.cone_ptr[e + 1]]
            w_tot += vol_d1[ds].sum()
            l_tot += len_d1[ds].sum()
        out[b] = l_tot / max(w_tot, 1e-30)
    return out


[docs] def build_geometry(zooms, angle_max=35.0, step_vox=1.0, curv_sigma=0.0) -> Geometry: """Paths for hops of ``step_vox`` voxels (of the smallest voxel side) turning less than ``angle_max`` degrees, on DSI Studio's 642-direction sphere; anisotropic voxels are exact.""" V = np.ascontiguousarray(default_sphere(), np.float64) zooms = np.abs(np.asarray(zooms, float)) table = mittens.PathTable(V, float(step_vox * zooms.min()), float(angle_max), np.diag(zooms)) e = table.emissions() dirs = np.asarray(e["chain"], np.int64) length = (dirs >= 0).sum(1) nbr = np.asarray(e["neighbor"], np.int64) vol = np.asarray(e["volume"], np.float64) disp = np.asarray(table.displacements(), np.float64)[np.maximum(dirs, 0)] # (P, L, 3) disp[dirs < 0] = 0.0 cum = np.cumsum(disp, axis=1) total = cum[np.arange(len(dirs)), length - 1] # start points x in [0,1]^3 stay inside for every hop but the last, which lands in o inner = np.where((np.arange(dirs.shape[1])[None, :] < (length - 1)[:, None])[..., None], cum, 0.0) o = OFFSETS[nbr].astype(np.float64) lo = np.maximum(np.maximum(0.0, (-inner).max(1)), o - total) hi = np.minimum(np.minimum(1.0, (1.0 - inner).min(1)), o + 1.0 - total) if not np.allclose(np.clip(hi - lo, 0, None).prod(1), vol, rtol=1e-9, atol=1e-14): raise RuntimeError("path start boxes disagree with MITTENS's path volumes") ip, ix, _ = table.turning_matrix() cone_ptr = np.asarray(ip, np.int64) cone_idx = np.asarray(ix, np.int64) cone_w = np.ones(cone_idx.size, np.float64) if curv_sigma > 0.0: sig_rad = np.deg2rad(float(curv_sigma)) inv_2s2 = 0.5 / max(sig_rad * sig_rad, 1e-12) for d0 in range(len(V)): k0, k1 = cone_ptr[d0], cone_ptr[d0 + 1] dots = np.clip(V[cone_idx[k0:k1]] @ V[d0], -1.0, 1.0) thetas = np.arccos(dots) cone_w[k0:k1] = np.exp(-thetas * thetas * inv_2s2) bins = OFFSETS / np.linalg.norm(OFFSETS, axis=1, keepdims=True) vbin = np.argmax(V @ bins.T, axis=1).astype(np.int64) bin_idx = np.argsort(vbin, kind="stable").astype(np.int64) bin_ptr = np.concatenate([[0], np.cumsum(np.bincount(vbin, minlength=26))]).astype(np.int64) last = dirs[np.arange(len(dirs)), length - 1] key = dirs[:, 0] * (26 * 26) + nbr * 26 + vbin[last] ukey, trip = np.unique(key, return_inverse=True) d1 = ukey // (26 * 26) trip = trip.astype(np.int64) tree = _build_prefix_tree(dirs, length, vol, nbr, trip, vertices=V, curv_sigma=curv_sigma) u_dir, u_parent, u_d1, u_skip, u_eptr, e_vol, e_nbr, e_trip, e_orig, u_curv_w, u_pt_dir = tree return Geometry(V, cone_ptr, cone_idx, vol, dirs, length, nbr, total, lo, hi, vbin, bin_ptr, bin_idx, trip, np.searchsorted(d1, np.arange(len(V) + 1)).astype(np.int64), ((ukey // 26) % 26).astype(np.int64), (ukey % 26).astype(np.int64), 26, u_dir, u_parent, u_d1, u_skip, u_eptr, e_vol, e_nbr, e_trip, e_orig, cone_w, u_curv_w, u_pt_dir)
def _sh_basis(vertices, n_coef): """(n_coef, V) so that sf = sh @ B: DIPY's descoteaux07 basis (legacy), symmetric or full, as pyAFQ's tracker evaluates its (a)ODFs.""" from dipy.core.sphere import Sphere from dipy.reconst.shm import sh_to_sf_matrix sym = (-3.0 + np.sqrt(1.0 + 8.0 * n_coef)) / 2.0 full = not float(sym).is_integer() order = int(round(np.sqrt(n_coef) - 1)) if full else int(round(sym)) return np.asarray(sh_to_sf_matrix(Sphere(xyz=vertices), sh_order_max=order, full_basis=full, return_inv=False), np.float64)
[docs] def pmf_and_cone_mass(sh_rows, geo: Geometry, chunk=20000, fod_thresh=PMF_THRESHOLD, fod_power=1.0, cyl_nbr=None, probe_radius=0.0): """X: fODF on the sphere, clipped at 0, values below ``fod_thresh`` x max zeroed, raised to ``fod_power`` (PTT dataSupportExponent), normalised to sum 1 per voxel; Y: X summed over each cone (weighted by ``geo.cone_w``).""" import scipy.sparse as sps from . import kernel as K B = _sh_basis(geo.vertices, sh_rows.shape[1]) X = np.empty((sh_rows.shape[0], geo.n_dirs), np.float32) for s in range(0, sh_rows.shape[0], chunk): sf = np.maximum(np.asarray(sh_rows[s:s + chunk], np.float64) @ B, 0.0) sf[sf < fod_thresh * sf.max(1, keepdims=True)] = 0.0 if fod_power != 1.0: np.power(sf, float(fod_power), out=sf, where=sf > 0.0) tot = sf.sum(1, keepdims=True) X[s:s + chunk] = np.divide(sf, tot, out=np.zeros_like(sf), where=tot > 0) if probe_radius > 0.0 and cyl_nbr is not None and len(X) > 0: offs = OFFSETS.astype(np.float64) offs_n2 = (offs ** 2).sum(1)[:, None] o_par = np.abs(offs @ geo.vertices.T) # (26, V) o_perp2 = np.maximum(offs_n2 - o_par ** 2, 0.0) # (26, V) r2 = max(float(probe_radius) ** 2, 1e-6) W = np.exp(-0.5 * o_perp2 / r2 - 0.5 * (o_par ** 2) / 1.0) # Keep top 6 cylinder neighbours per direction top_n = np.argsort(W, axis=0)[-6:].T.copy() # (V, 6) top_w = np.take_along_axis(W.T, top_n, axis=1).copy() # (V, 6) X = K._cylindrical_probe_filter(X, np.asarray(cyl_nbr, np.int32), top_n.astype(np.int32), top_w.astype(np.float32), float(fod_thresh)) cw = geo.cone_w if geo.cone_w is not None else np.ones(geo.cone_idx.size) C = sps.csr_matrix((cw, geo.cone_idx, geo.cone_ptr), shape=(geo.n_dirs,) * 2) Y = np.asarray(C @ X.T.astype(np.float64)).T.astype(np.float32) if len(X) else X.copy() return X, Y
def vertex_visits(density_class, sh_rows, geo: Geometry): """Expected visits per sphere direction, (n, V): a voxel's visits by direction class (density_class, (n, 26)) spread over the class's directions as the chain assumes, q ~ X Y (kernel.class_q, with its fallbacks), from the fODF there (sh_rows, (n, ncoef)). Rows sum to the voxel's visits. Not symmetrised: a direction is the walker's heading.""" import scipy.sparse as sps V = geo.n_dirs cls = sps.csr_matrix((np.ones(V), (np.arange(V), geo.vbin)), shape=(V, geo.nb)) X, Y = pmf_and_cone_mass(sh_rows, geo) X, Y = X.astype(np.float64), Y.astype(np.float64) q = np.zeros_like(X) todo = np.ones((len(X), geo.nb), bool) for w in (X * Y, Y, np.ones_like(X)): # class_q's fallbacks tot = np.asarray(cls.T @ w.T).T # (n, 26) use = todo & (tot > 0) q += np.where(use[:, geo.vbin], w / np.where(tot > 0, tot, 1)[:, geo.vbin], 0) todo &= ~use return np.asarray(density_class, np.float64)[:, geo.vbin] * q
[docs] def visitation_odf(density_class, sh_rows, geo: Geometry, sh_order=8, chunk=20000): """A bundle's visitation ODF: the directions its walkers travel in each voxel, as SH coefficients in the fODF's basis (DIPY descoteaux07, legacy, symmetric). density_class (n, 26): expected visits by direction class, per voxel; sh_rows (n, ncoef): the fODF there. Within a class the direction is spread as the chain assumes, q ~ X Y (kernel.class_q; vertex_visits). The ODF is antipodally symmetrised and in expected visits per steradian, so it integrates to the voxel's density (c_00 = density / (2 sqrt(pi))).""" from dipy.core.sphere import Sphere from dipy.reconst.shm import sh_to_sf_matrix _, inv = sh_to_sf_matrix(Sphere(xyz=geo.vertices), sh_order_max=sh_order, return_inv=True) anti = geo.antipode() out = np.zeros((len(sh_rows), inv.shape[1]), np.float32) for s in range(0, len(sh_rows), chunk): f = vertex_visits(density_class[s:s + chunk], sh_rows[s:s + chunk], geo) c = (0.5 * (f + f[:, anti])) @ inv # exact integral (the sphere's vertices do not cover equal solid angles) c00 = f.sum(1) / (2 * np.sqrt(np.pi)) out[s:s + chunk] = c * np.divide(c00, c[:, 0], out=np.zeros_like(c00), where=c[:, 0] > 0)[:, None] return out
def seed_peaks(pmf, geo: Geometry): """Vertex indices of the fODF peaks of one voxel (DIPY's peak finder; pyAFQ's thresholds).""" from dipy.core.sphere import Sphere from dipy.direction.peaks import peak_directions if not hasattr(geo, "_dipy_sphere"): geo._dipy_sphere = Sphere(xyz=geo.vertices) _, _, idx = peak_directions(np.asarray(pmf, np.float64), geo._dipy_sphere, relative_peak_threshold=PEAK_THRESHOLD, min_separation_angle=PEAK_SEPARATION, is_symmetric=False) return np.asarray(idx, np.int64)