"""Bundle cores: the cross-section ridge path of a MPAT density map.
A core is a single curve through the bundle, from one end to the other, that stays on the
density ridge -- the most visited voxels of each cross-section -- including through bends.
Method (parameter-free apart from where the ends are; two shortest-path searches):
1. Anchors. Each end of the bundle is anchored at the white-matter voxel nearest the
centroid of the walkers' endpoints at that end, weighted by the endpoint density
(``endpoints_map``) -- or, with ``anchor="mode"``, nearest the endpoint density's peak
(smoothed over a voxel), where most walkers end, which a broad or curved ending ROI (an
eye, a gyrus) pulls the centroid away from. Which endpoints belong to which end, and so
which end is node 0, follows pyAFQ's orientation of streamlines: the start ROI is the first
end and the end ROI the last (the other endpoints are the other end when the bundle has
only one of them); otherwise the endpoints nearer the first include ROI are the first end
and those nearer the last the last; otherwise the two hemispheres; otherwise two clusters
of the endpoints.
2. A first most-probable path: Dijkstra on the 26-neighbour voxel graph with cost
-log(density / peak) per mm. It finds the right corridor but cuts corners, because
every step below the peak costs something.
3. Cross-sections. Every voxel joins the cross-section of the first path's voxel nearest
to it (nearest in the same density metric, so cross-sections follow the bundle).
4. The ridge path: Dijkstra again with cost -log(density / max density of its own
cross-section). That cost is zero on each cross-section's maximum, so the path is not
penalised for length while it follows the ridge, and bends are no longer cut.
5. Gaussian smoothing (``smooth`` voxels along the path) and resampling to ``n_nodes``
equally spaced nodes, oriented from the start end to the other end.
"""
from __future__ import annotations
import glob
import json
import logging
import os.path as op
import re
from dataclasses import dataclass, field
import nibabel as nib
import numpy as np
log = logging.getLogger("mpat")
OFFS = np.array([(i, j, k) for i in (-1, 0, 1) for j in (-1, 0, 1) for k in (-1, 0, 1)
if (i, j, k) != (0, 0, 0)])
@dataclass
class Core:
xyz: np.ndarray # (n_nodes, 3) world mm, from the start end to the other
density: np.ndarray # (n_nodes,) density / bundle peak at each node (trilinear)
length_mm: float
ends: str # how the two ends were defined
info: dict = field(default_factory=dict)
first_xyz: np.ndarray = None # the plain most-probable path (step 2), same smoothing
def _resample(xyz, n):
s = np.r_[0, np.cumsum(np.linalg.norm(np.diff(xyz, axis=0), axis=1))]
if s[-1] == 0:
return np.repeat(xyz[:1], n, 0)
t = np.linspace(0, s[-1], n)
return np.stack([np.interp(t, s, xyz[:, k]) for k in range(3)], 1)
def _graph(cost_vox, keep, vox_mm):
import scipy.sparse as sps
idx = np.argwhere(keep)
n = len(idx)
lin = -np.ones(keep.shape, np.int64)
lin[tuple(idx.T)] = np.arange(n)
c = cost_vox[tuple(idx.T)]
rows, cols, w = [], [], []
for o in OFFS:
nb = idx + o
ok = np.all((nb >= 0) & (nb < keep.shape), 1)
j = np.full(n, -1, np.int64)
j[ok] = lin[tuple(nb[ok].T)]
m = j >= 0
rows.append(np.flatnonzero(m))
cols.append(j[m])
# +1e-9: a tiny length tie-break, so zero-cost ridges still give a shortest path
w.append(np.linalg.norm(o) * vox_mm * 0.5 * (c[m] + c[j[m]]) + 1e-9)
G = sps.csr_matrix((np.concatenate(w), (np.concatenate(rows), np.concatenate(cols))),
shape=(n, n))
return G, idx, lin
def _path(G, src, dst):
from scipy.sparse.csgraph import dijkstra
dist, pred, _ = dijkstra(G, indices=src, min_only=True, return_predecessors=True)
t = dst[np.argmin(dist[dst])]
if not np.isfinite(dist[t]):
raise ValueError("the two ends are not connected through the bundle")
p = [t]
while pred[p[-1]] >= 0:
p.append(pred[p[-1]])
return np.array(p[::-1])
def _anchor(ep, roi, body, how="centroid"):
"""Body voxel nearest the endpoint-weighted centroid (``how="centroid"``) or the smoothed
endpoint-density peak (``"mode"``) of the endpoints in ``roi``."""
w = np.where(roi, ep, 0.0)
if w.sum() <= 0:
w = roi.astype(float)
if how == "mode":
from scipy.ndimage import gaussian_filter
sm = np.where(roi, gaussian_filter(w, 1.0), -np.inf)
c = np.array(np.unravel_index(np.argmax(sm), sm.shape), float)
elif how == "centroid":
ijk = np.argwhere(w > 0)
c = (ijk * w[tuple(ijk.T)][:, None]).sum(0) / w[tuple(ijk.T)].sum()
else:
raise ValueError(f"anchor must be 'centroid' or 'mode', not {how!r}")
cand = np.argwhere(body)
return cand[np.argmin(((cand - c) ** 2).sum(1))]
def split_ends(ep, affine, start=None, end=None, include=None):
"""Two boolean masks of endpoint voxels, first end then last end of the bundle, and a
description. ``include``: the include ROIs labelled 1, 2, ... in pyAFQ's order (MPAT
``include_mask``)."""
from scipy.ndimage import distance_transform_edt
has = ep > 0
if start is not None and end is not None and (has & start).any() and (has & end).any():
return has & start, has & end, "start and end ROIs"
if start is not None and (has & start).any() and (has & ~start).any():
return has & start, has & ~start, "start ROI vs all other endpoints"
if end is not None and (has & end).any() and (has & ~end).any():
return has & ~end, has & end, "all other endpoints vs end ROI"
if include is not None and include.max() > 1:
vox = np.sqrt((affine[:3, :3] ** 2).sum(0))
first = has & (distance_transform_edt(include != 1, vox) <
distance_transform_edt(include != include.max(), vox))
if first.any() and (has & ~first).any():
return first, has & ~first, "first vs last include ROI"
ijk = np.argwhere(has)
if len(ijk) < 2:
raise ValueError(f"{len(ijk)} endpoint voxel(s): no two ends to split")
w = ep[tuple(ijk.T)]
xyz = nib.affines.apply_affine(affine, ijk)
left = xyz[:, 0] < 0
if min(w[left].sum(), w[~left].sum()) > 0.1 * w.sum():
a = np.zeros(ep.shape, bool)
a[tuple(ijk[left].T)] = True
return a, has & ~a, "left vs right hemisphere"
# two weighted clusters, seeded at the extremes of the principal axis
c = (xyz * w[:, None]).sum(0) / w.sum()
u = np.linalg.svd((xyz - c) * np.sqrt(w)[:, None], full_matrices=False)[2][0]
proj = (xyz - c) @ u
cen = np.stack([xyz[np.argmin(proj)], xyz[np.argmax(proj)]])
for _ in range(20):
lab = ((xyz[:, None] - cen[None]) ** 2).sum(-1).argmin(1)
cen = np.stack([(xyz[lab == k] * w[lab == k, None]).sum(0) / max(w[lab == k].sum(), 1e-300)
for k in (0, 1)])
a = np.zeros(ep.shape, bool)
a[tuple(ijk[lab == 0].T)] = True
return a, has & ~a, "two endpoint clusters"
[docs]
def bundle_core(density, affine, endpoints, start=None, end=None, n_nodes=100, floor=1e-6,
body=1e-2, smooth=1.5, anchor="centroid", include=None):
"""Cross-section ridge path of one bundle (see module docstring).
density, endpoints 3-D arrays on the same grid (MPAT ``density_map``, ``endpoints_map``)
start, end optional boolean endpoint ROIs (MPAT ``start_mask``, ``end_mask``)
include optional include ROIs labelled 1, 2, ... in pyAFQ's order (MPAT ``include_mask``)
floor voxels with density below floor x peak are left out of the graph
body anchors are placed on voxels with density >= body x peak
anchor "centroid" (default) or "mode": where in each end's endpoints to anchor
"""
from scipy.ndimage import gaussian_filter1d, label, map_coordinates
from scipy.sparse.csgraph import dijkstra
d = np.clip(np.nan_to_num(np.asarray(density, float)), 0, None)
ep = np.clip(np.nan_to_num(np.asarray(endpoints, float)), 0, None)
if d.max() <= 0:
raise ValueError("empty density map")
dn = d / d.max()
vox_mm = float(np.abs(np.linalg.det(affine[:3, :3])) ** (1 / 3))
S_roi, E_roi, how = split_ends(ep, affine, start, end, include)
keep = dn > floor
lab, _ = label(keep, np.ones((3, 3, 3)))
core_lab = lab[np.unravel_index(np.argmax(dn), dn.shape)]
keep = lab == core_lab # the component holding the peak
bod = keep & (dn >= body)
s_vox, e_vox = _anchor(ep, S_roi, bod, anchor), _anchor(ep, E_roi, bod, anchor)
cost1 = np.where(keep, -np.log(np.where(keep, dn, 1.0)), 0.0)
G, idx, lin = _graph(cost1, keep, vox_mm)
src, dst = np.array([lin[tuple(s_vox)]]), np.array([lin[tuple(e_vox)]])
p0 = _path(G, src, dst)
dist, _, owner = dijkstra(G, indices=p0, min_only=True, return_predecessors=True)
dv = d[tuple(idx.T)]
ok = np.isfinite(dist)
mx = np.zeros(len(idx))
np.maximum.at(mx, owner[ok], dv[ok])
rel = np.zeros(len(idx))
rel[ok] = dv[ok] / mx[owner[ok]]
cost2 = np.zeros(d.shape)
cost2[tuple(idx.T)] = np.where(ok, -np.log(np.maximum(rel, 1e-300)), 50.0)
G2, idx2, lin2 = _graph(cost2, keep, vox_mm)
p = _path(G2, src, dst)
def curve(vox):
c = nib.affines.apply_affine(affine, vox.astype(float))
if smooth and len(c) > 2:
c = gaussian_filter1d(c, smooth, axis=0, mode="nearest")
return _resample(c, n_nodes)
xyz, first = curve(idx2[p]), curve(idx[p0])
ijk = nib.affines.apply_affine(np.linalg.inv(affine), xyz)
dens = map_coordinates(dn, ijk.T, order=1, mode="nearest")
length = float(np.linalg.norm(np.diff(xyz, axis=0), axis=1).sum())
L0 = float(np.linalg.norm(np.diff(first, axis=0), axis=1).sum())
info = dict(anchor=anchor, n_graph_voxels=int(len(idx)), first_path_length_mm=round(L0, 1),
start_anchor_vox=s_vox.tolist(), end_anchor_vox=e_vox.tolist(),
min_node_density=float(dens.min()), median_node_density=float(np.median(dens)))
return Core(xyz, dens, length, how, info, first)
def write_core(core, prefix, ref, extra=None):
"""``<prefix>_desc-core_path.tsv`` (nodes) and ``<prefix>_desc-core.trx`` (one streamline, on
the grid of ``ref``, a nibabel image such as the density map)."""
from dipy.io.stateful_tractogram import Space, StatefulTractogram
from dipy.io.streamline import save_tractogram
tsv = f"{prefix}_desc-core_path.tsv"
with open(tsv, "w") as fh:
fh.write("node\tx_mm\ty_mm\tz_mm\tdensity_rel_peak\n")
for i, (p, v) in enumerate(zip(core.xyz, core.density)):
fh.write(f"{i}\t{p[0]:.3f}\t{p[1]:.3f}\t{p[2]:.3f}\t{v:.6g}\n")
trx = f"{prefix}_desc-core.trx"
save_tractogram(StatefulTractogram([core.xyz.astype(np.float32)], ref, Space.RASMM), trx,
bbox_valid_check=False)
with open(f"{prefix}_desc-core.json", "w") as fh:
json.dump(dict(method="cross-section ridge path (mpat.core)", ends=core.ends,
n_nodes=int(len(core.xyz)), length_mm=round(core.length_mm, 1),
**core.info, **(extra or {})), fh, indent=1)
return tsv, trx
def bundle_files(folder):
"""{bundle: {prefix, density, endpoints, start, end, include, exclude, odf}} for the MPAT outputs under
``folder`` (None where a file is missing)."""
out = {}
for f in sorted(glob.glob(op.join(folder, "**", "*_desc-density_map.nii.gz"), recursive=True)):
m = re.search(r"_bundle-(.+?)_desc-density_map", op.basename(f))
if not m:
continue
pre = f[: -len("_desc-density_map.nii.gz")]
get = lambda k: (pre + f"_desc-{k}.nii.gz") if op.exists(pre + f"_desc-{k}.nii.gz") else None # noqa: E731
out[m.group(1)] = dict(prefix=pre, density=f, afd=get("afd_map"), tdimm=get("tdimm_map"),
qharmonic=get("qharmonic_map"), coherence=get("coherence_map"),
keff=get("keff_map"), endpoints=get("endpoints_map"),
start=get("start_mask"), end=get("end_mask"), include=get("include_mask"),
exclude=get("exclude_mask"), odf=get("visitodf_dwimap"))
return out
[docs]
def write_cores(folder, n_nodes=100, anchor="centroid"):
"""Compute and save the core of every bundle under ``folder`` (MPAT outputs)."""
for name, f in bundle_files(folder).items():
if f["endpoints"] is None:
continue
img = nib.load(f["density"])
load = lambda k: (np.asarray(nib.load(f[k]).dataobj) > 0) if f[k] else None # noqa: E731
try:
c = bundle_core(np.asarray(img.dataobj), img.affine, np.asarray(nib.load(f["endpoints"]).dataobj),
load("start"), load("end"), n_nodes, anchor=anchor,
include=np.asarray(nib.load(f["include"]).dataobj) if f["include"] else None)
except ValueError as e:
log.warning("%s: no core (%s)", name, e)
continue
write_core(c, f["prefix"], img)
log.info("core %-24s %4.0f mm, ends: %s", name, c.length_mm, c.ends)