Source code for mpat.afq

"""MPAT on top of pyAFQ.  Everything except the Markov chain comes from a pyAFQ
``ParticipantAFQ`` (or each participant of a ``GroupAFQ``): the fODF pyAFQ tracks on, the
tissue PVE and brain mask, the white/grey-matter interface (seeds), the bundle
definitions, and their ROIs warped to the subject.  Outputs go to ``<output_dir>/mpat``
(``mpat-moments`` with spatial moments), next to pyAFQ's own, or to ``out_dir`` (pyAFQ's
derivatives are then only read).
"""
from __future__ import annotations

import csv
import json
import logging
import os
import re
import time
from pathlib import Path

import nibabel as nib
import numpy as np

from .chain import ABSORB_CLASSES, Chain, ChainConfig
from .geometry import visitation_odf
from .solve import Clock, overlength_states, prepare_launches, segment_bundles

log = logging.getLogger("mpat")
WM_THRESHOLD = 0.4   # pyAFQ's tracker stops where WM PVE <= gm_threshold (0.4)
ODF_FLOOR = 1e-3     # visitation ODFs are written where the density reaches this x its peak


def _on_grid(img, ref, order=1):
    """img on ref's grid: linear as pyAFQ's tracker does (dipy.align.resample), or nearest
    neighbour (order=0) for masks."""
    from dipy.align import resample
    from nibabel.processing import resample_from_to

    data = np.asarray(img.dataobj, np.float32)
    if img.shape[:3] == ref.shape[:3] and np.allclose(img.affine, ref.affine, atol=1e-3):
        return data
    if order == 0:
        return np.asarray(resample_from_to(nib.Nifti1Image(data, img.affine), (ref.shape[:3], ref.affine),
                                           order=0).dataobj, np.float32)
    vols = [data] if data.ndim == 3 else [data[..., i] for i in range(data.shape[-1])]
    out = [np.asarray(resample(v, np.zeros(ref.shape[:3], np.float32), moving_affine=img.affine,
                               static_affine=ref.affine).get_fdata(), np.float32) for v in vols]
    return out[0] if data.ndim == 3 else np.stack(out, -1)


HOLE_WARN = 0.01   # warn when this fraction of the fODF region is all-zero holes inside it


[docs] def tissue_labels(sh_img, pve_img, brain_mask_img=None): """As pyAFQ's tracker: walkers move where WM PVE > 0.4 inside the fODF mask; the mask's inner boundary counts as grey matter ("edge", so fibres leaving the field end validly); other in-mask voxels are GM (GM PVE >= CSF PVE), which absorbs walkers, or CSF, which walkers never enter (zero transition probability). White matter that cannot reach any ending -- a pocket walled in by CSF and the edge of the fODF field (in a tumour, say) -- would trap walkers seeded in it forever and stall the solves: it is taken out of the walk (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 scipy import ndimage as ndi mask = np.any(np.asarray(sh_img.dataobj) != 0, axis=-1) if brain_mask_img is not None: mask &= _on_grid(brain_mask_img, sh_img) > 0.5 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 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 " "ringed by edge voxels where walkers end, so bundles may come out near zero. Check " "the fODF fit (a stale or partial model file, a failed fit, NaN / zero signal)", holes, 100 * holes / mask.sum()) elif holes: log.info("%d voxels inside the fODF region have an all-zero fODF", holes) 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 absorb[mask & ~transient & (gm < csf)] = 2 absorb[edge] = 3 # white matter with no way to an ending (walkers step to any of the 26 neighbours) cube = np.ones((3, 3, 3), bool) lab, n = ndi.label(transient, cube) trapped = np.zeros(mask.shape, bool) if n: ends = ndi.binary_dilation((absorb == 1) | (absorb == 3), cube) reach = np.zeros(n + 1, bool) reach[np.unique(lab[ends & transient])] = True trapped = transient & ~reach[lab] if trapped.any(): sizes = np.bincount(lab[trapped]) sizes = np.sort(sizes[sizes > 0])[::-1] log.info("isolated white matter: %d voxels in %d pockets with no way to grey matter or the " "edge (largest %d voxels) are left out of the walk (dseg 5)", trapped.sum(), len(sizes), sizes[0]) transient = transient & ~trapped absorb[trapped] = 2 dseg = np.where(transient, 1, np.where(absorb > 0, absorb + 1, 0)).astype(np.uint8) dseg[trapped] = 5 return transient, absorb, dseg
[docs] def seal_26(mask): """Make a thin ROI impassable for 26-connected walks. Streamlines cannot slip through a one-voxel sheet; walkers stepping diagonally can. Adding the sheet's 6-neighbours closes those gaps.""" from scipy import ndimage return ndimage.binary_dilation(mask, ndimage.generate_binary_structure(3, 1))
def _subject_thalamus(name, k, roi, thalamus, x, tol): """``roi``, or the subject's thalamus on its side if ``roi`` is the template's thalamus.""" from scipy.ndimage import distance_transform_edt either = thalamus["left"] | thalamus["right"] if not either.any(): log.warning("%s %s: SynthSeg found no thalamus on this grid; keeping the template's ROI", name, k) return roi near = distance_transform_edt(~either) <= max(tol, 1) centre = tuple(np.round(np.argwhere(roi).mean(0)).astype(int)) frac = float(near[roi].mean()) if frac < 0.5 and not either[centre]: if frac >= 0.1: # thalamus-ish but not taken: say so, so it can be checked log.info("%s %s: %.0f%% on the subject's thalamus, centre outside it: kept the template's ROI", name, k, 100 * frac) return roi side = "left" if x[roi].mean() < 0 else "right" log.info("%s %s: the template thalamus (%.0f%% on the subject's) -> SynthSeg's %s thalamus " "(%d voxels, was %d)", name, k, 100 * frac, side, thalamus[side].sum(), roi.sum()) return thalamus[side].copy()
[docs] def bundle_specs(afq, ref_img, transient, names=None, thalamus=None, no_midline=(), midline_tol=None, fornix=True): """bundle_specs_iter as a list (every bundle's ROIs at once).""" return list(bundle_specs_iter(afq, ref_img, transient, names, thalamus, no_midline, midline_tol, fornix))
def mni_box(box, bd, mapping, ref_img): """An MNI box {x: (lo, hi), y: ..., z: ...} (mm) on ``ref_img``'s grid, warped as pyAFQ warps its template ROIs.""" import AFQ.utils.volume as auv tpl = bd.resample_to tpl = nib.load(tpl) if isinstance(tpl, (str, Path)) else tpl xyz = nib.affines.apply_affine(tpl.affine, np.indices(tpl.shape[:3]).reshape(3, -1).T) m = np.ones(len(xyz), bool) for i, k in enumerate("xyz"): lo, hi = box[k] m &= (xyz[:, i] >= lo) & (xyz[:, i] <= hi) warped = auv.transform_roi(m.reshape(tpl.shape[:3]).astype(np.float64), mapping, True) return _on_grid(nib.Nifti1Image(np.asarray(warped, np.float32), ref_img.affine), ref_img, order=0) > 0 def bundle_specs_iter(afq, ref_img, transient, names=None, thalamus=None, no_midline=(), midline_tol=None, fornix=True, hypo_file=None, parc_file=None): """MPAT bundle specs from pyAFQ's bundle dictionary and MPAT's rules (mpat.bundles): include / exclude ROIs (sealed), start / end ROIs grown by pyAFQ's ``dist_to_atlas``, and the other hemisphere excluded for bundles that may not cross the midline. Other pyAFQ criteria (curvature, length, cleaning) are streamline-based and do not apply. Yields one bundle at a time, each warped only when it is asked for, so a run holds the ROIs of the bundles it is solving and no others. no_midline bundle names whose cross_midline=False is ignored (no other-hemisphere exclusion) midline_tol overrides the midline_tol rule of the bundles that have one (the corticospinal tracts); None: the rules' own fornix False: drop the fornix box (mpat.bundles.FORNIX_BOX_MNI) from the exclusions (the anterior thalamic radiations as pyAFQ defines them) parc_file where SynthSeg with its cortical parcels and hypothalamus is kept (written on first need), when a bundle's SynthSeg ROIs use cortical parcels (or the hypothalamus and no hypo_file has it) hypo_file where SynthSeg with the hypothalamus is kept, when a bundle's SynthSeg ROIs use the hypothalamus (the fornix) and pyAFQ's SynthSeg lacks it (_synthseg_on_grid) thalamus {"left": mask, "right": mask} on ``ref_img``'s grid (SynthSeg's): a start / end ROI that is the template's thalamus -- at least half of it within ``dist_to_atlas`` of a thalamus, or its centre inside one -- is replaced by the subject's thalamus on its side (unless the bundle's rule says thalamus="template"). The thalamus is grey matter, where walkers end, so a template thalamus warped a few mm off would make most real endings invalid.""" from scipy.ndimage import distance_transform_edt from .bundles import FORNIX_BOX_MNI, rules, synthseg_values bd, mapping = afq.export("bundle_dict"), afq.export("mapping") dist = afq.export("segmentation_params").get("dist_to_atlas", 4) R = ref_img.affine[:3, :3] tol = int(dist / np.mean(np.diag(np.linalg.cholesky(R.T @ R)))) # pyAFQ's tolerance_mm_to_vox x = nib.affines.apply_affine(ref_img.affine, np.indices(transient.shape).reshape(3, -1).T)[:, 0] x = x.reshape(transient.shape) boxes, seg, seg_has = {}, None, set() def box(b): key = tuple(sorted((k, tuple(v)) for k, v in b.items())) if key not in boxes: boxes[key] = seal_26(mni_box(b, bd, mapping, ref_img)) log.info("MNI box %s: %d voxels on this grid", dict(b), int(boxes[key].sum())) return boxes[key] for name in (names or list(bd)): r = rules(bd, name) rois = bd.transform_rois(name, mapping, ref_img) arr = lambda img: _on_grid(img, ref_img, order=0) > 0 # noqa: E731 spec = dict(name=name, include=[seal_26(arr(m)) for m in rois.get("include", [])]) spec["include"] += [box(b) for b in r["include_mni_boxes"]] exc = [seal_26(arr(m)) for m in rois.get("exclude", [])] exc += [box(b) for b in r["exclude_mni_boxes"] if fornix or dict(b) != FORNIX_BOX_MNI] spec["exclude_rois"] = np.any(exc, axis=0) if exc else None # without the hemisphere (for display) for k in ("start", "end"): labels = r[f"{k}_synthseg"] if labels: values = synthseg_values(labels) if seg is None or not _extras(values) <= seg_has: seg = _synthseg_on_grid(afq, ref_img, values, hypo_file=hypo_file, parc_file=parc_file) seg_has = _extras(np.unique(seg)) roi = np.isin(seg, values) if not roi.any(): log.warning("%s %s: SynthSeg labels %s are empty on this grid", name, k, labels) log.info("%s %s: SynthSeg %s (%d voxels)", name, k, ", ".join(map(str, labels)), int(roi.sum())) elif k in rois: roi = arr(rois[k]) if thalamus is not None and r["thalamus"] == "synthseg" and roi.any(): roi = _subject_thalamus(name, k, roi, thalamus, x, tol) else: continue k_tol = tol if labels and r["synthseg_tol_mm"] is not None: # SynthSeg ends: their own growth k_tol = int(r["synthseg_tol_mm"] / np.mean(np.diag(np.linalg.cholesky(R.T @ R)))) spec[k] = roi if k_tol <= 0 else distance_transform_edt(~roi) - 0.5 <= k_tol # pyAFQ's endpoint test if bd[name].get("cross_midline") is False and name in no_midline: log.info("%s: no midline exclusion (no_midline)", name) elif bd[name].get("cross_midline") is False: t = r["midline_tol"] if midline_tol is None or not r["midline_tol"] else midline_tol left = _is_left(name, spec, x) exc.append(x > t if left else x < -t) log.info("%s: kept to the %s hemisphere (other side excluded past %g mm)", name, "left" if left else "right", t) spec["exclude"] = np.any(exc, axis=0) if exc else None yield spec HYPOTHALAMUS = (102, 103) # SynthSegLabels.LEFT_ / RIGHT_HYPOTHALAMUS def _is_left(name, spec, x): """Which hemisphere a one-sided bundle belongs to: its name ("Left ..." / "Right ..."), else its include ROIs, else its start / end ROIs, each ROI counted once (its centre). Not pooled voxels: a big midline end ROI shared by both sides (the corticospinal tracts' brainstem) would outvote the waypoints and put a bundle on the wrong side.""" n = name.lower() if n.startswith("left") or n.endswith("_l") or n.endswith(" l"): return True if n.startswith("right") or n.endswith("_r") or n.endswith(" r"): return False for rois in (spec["include"], [spec[k] for k in ("start", "end") if spec.get(k) is not None]): c = [x[m].mean() for m in rois if m.any()] if c: return float(np.mean(c)) < 0 return True CORTEX_PARCELS = range(34, 102) # SynthSegLabels.CTX_LH_BANKSSTS .. CTX_RH_INSULA (Desikan-Killiany) def _extras(values): """SynthSeg's extra models that labels ``values`` need: subset of {"hypothalamus", "cortex"}.""" v = {int(x) for x in values} return ({"hypothalamus"} if v & set(HYPOTHALAMUS) else set()) | \ ({"cortex"} if v & set(CORTEX_PARCELS) else set()) def _has(img, extras): """Does the label image hold the labels of these extra models?""" return _extras(np.unique(np.asarray(img.dataobj))) >= set(extras) def parc_file_of(stem): return f"{stem}_model-synthseg2parc_dseg.nii.gz" def _synthseg_on_grid(afq, ref_img, values=(), hypo_file=None, parc_file=None): """pyAFQ's SynthSeg labels on ``ref_img``'s grid, holding the labels ``values`` need. pyAFQ's own SynthSeg run has neither the hypothalamus (102 / 103) nor the cortical parcels (34-101). When ``values`` need one that pyAFQ's segmentation lacks, an earlier rerun is reused (``hypo_file``: hypothalamus only; ``parc_file``: both), or else SynthSeg is rerun on pyAFQ's T1 with both extra models and written to ``parc_file`` (synthseg_parcellated). pyAFQ's own segmentation and tissue are left as they are.""" need = _extras(values) seg = afq.export("synthseg_model") seg = nib.load(seg) if isinstance(seg, str) else seg if need and not _has(seg, need): seg = None if need == {"hypothalamus"} and hypo_file and Path(hypo_file).exists() and _has(nib.load(hypo_file), need): seg = nib.load(hypo_file) log.info("SynthSeg with hypothalamus: %s", hypo_file) if seg is None: seg = synthseg_parcellated(afq, parc_file) lab = np.rint(_on_grid(seg, ref_img, order=0)).astype(np.int32) return lab[..., 0] if lab.ndim == 4 else lab def synthseg_parcellated(afq, path=None): """SynthSeg 2 with its cortical parcellation and hypothalamus models on pyAFQ's T1 (AFQ.nn.synthseg.run_synthseg, parc_cortex and parc_hypothalamus): read from ``path`` if it is there and complete, else run (once; several minutes on a CPU) and written there.""" full = {"hypothalamus", "cortex"} if path is not None and Path(path).exists(): img = nib.load(path) if _has(img, full): log.info("SynthSeg with cortical parcels and hypothalamus: %s", path) return img log.warning("%s lacks cortical parcels or the hypothalamus; rerunning SynthSeg", path) from AFQ.nn.synthseg import run_synthseg from AFQ.tasks.utils import check_onnxruntime ort = check_onnxruntime("SynthSeg 2.0 (parcellation / hypothalamus)", "Or give these bundles template ROIs instead of SynthSeg labels.") try: onnx_kwargs = afq.export("onnx_kwargs") except Exception: # noqa: BLE001 (older pyAFQ) onnx_kwargs = {} t1 = afq.kwargs["t1_file"] # an input, not an export log.info("running SynthSeg with its cortical parcellation and hypothalamus models on %s " "(pyAFQ's SynthSeg has neither; once per subject)", t1) t0 = time.time() img = run_synthseg(ort, nib.load(t1), "synthseg2", onnx_kwargs, parc_cortex=True, parc_hypothalamus=True) img = nib.Nifti1Image(np.asarray(img.dataobj).astype(np.int16), img.affine) for e in sorted(full): if not _has(img, {e}): log.warning("SynthSeg's %s model found no %s labels", e, e) if path is not None: Path(path).parent.mkdir(parents=True, exist_ok=True) nib.save(img, path) log.info("SynthSeg with cortical parcels and hypothalamus written to %s (%.0fs)", path, time.time() - t0) return img def synthseg_cst_for_pyafq(afq, bd, moments=False, out_dir=None): """``bd`` (already pyafq_bd'd) with pyAFQ's own versions of the SynthSeg corticospinal tracts (mpat.bundles.synthseg_cst_bd): their start / end masks from SynthSeg's parcellation (synthseg_parcellated: run if it is not there yet) written on the DWI grid in MPAT's folder, as subject-space ROIs pyAFQ's recognition reads (endpoints only, exact_endpoints: not grown by dist_to_atlas, as MPAT's synthseg_tol_mm 0).""" from .bundles import synthseg_cst_labels, synthseg_values out = mpat_dir(afq, moments, out_dir) out.mkdir(parents=True, exist_ok=True) stem = str(out / Path(afq.kwargs["base_fname"]).name) seg = synthseg_parcellated(afq, parc_file_of(stem)) ref_path = afq.export("b0") ref = nib.load(ref_path) ref = nib.Nifti1Image(np.zeros(ref.shape[:3], np.uint8), ref.affine) lab = np.rint(_on_grid(seg, ref, order=0)).astype(np.int32) lab = lab[..., 0] if lab.ndim == 4 else lab bd.resample_subject_to = ref for side in ("Left", "Right"): name = f"{side} Corticospinal" entry = dict(cross_midline=False, space="subject", exact_endpoints=True) # no 4 mm growth, as in MPAT for k, labels in zip(("start", "end"), synthseg_cst_labels(side)): f = f"{stem}_bundle-{side}Corticospinal_desc-synthseg{k}pyafq_mask.nii.gz" m = np.isin(lab, synthseg_values(labels)).astype(np.uint8) nib.save(nib.Nifti1Image(m, ref.affine), f) log.info("%s %s for pyAFQ: %s (%d voxels)", name, k, f, int(m.sum())) entry[k] = f bd[name] = entry return bd def _subject_thalami(afq, sh_img): """{"left", "right"} SynthSeg thalami on the fODF grid.""" from AFQ.nn.synthseg import SynthSegLabels lab = _synthseg_on_grid(afq, sh_img) return {"left": lab == int(SynthSegLabels.LEFT_THALAMUS), "right": lab == int(SynthSegLabels.RIGHT_THALAMUS)} def _thalami_if_synthseg(afq, sh_img, synthseg_thalamus): """SynthSeg's thalami when pyAFQ's tissue comes from SynthSeg (``pve`` unset, the default "synthseg", or a built-in method that includes it), else None; logged.""" pve = afq.kwargs.get("pve") from_synthseg = pve is None or (isinstance(pve, str) and "synthseg" in pve.lower()) use = synthseg_thalamus and from_synthseg why = "--mni-thalamus" if not synthseg_thalamus else f"pve={pve if isinstance(pve, str) else type(pve).__name__}" log.info("thalamic start / end ROIs: %s", "SynthSeg's thalami wherever the template's thalamus is used" if use else f"the template's ({why})") return _subject_thalami(afq, sh_img) if use else None def roi_specs(afq, sh_img, transient, stem, bundles=None, thalamus=None, no_midline=(), midline_tol=None, fornix=True): """bundle_specs_iter, writing each bundle's ROI masks as it goes: start / end, the include ROIs (labelled 1, 2, ... in pyAFQ's order) and the exclude ROIs (without the other hemisphere, which cross_midline=False bundles exclude too).""" for spec in bundle_specs_iter(afq, sh_img, transient, bundles, thalamus=thalamus, no_midline=no_midline, midline_tol=midline_tol, fornix=fornix, hypo_file=f"{stem}_model-synthseg2hypo_dseg.nii.gz", parc_file=parc_file_of(stem)): b = f"{stem}_bundle-{re.sub(r'[^A-Za-z0-9]', '', spec['name'])}" save = lambda m, desc: nib.save(nib.Nifti1Image(np.asarray(m, np.uint8), sh_img.affine), # noqa: E731 f"{b}_desc-{desc}_mask.nii.gz") for k in ("start", "end"): if spec.get(k) is not None: save(spec[k], k) if spec["include"]: lab = np.zeros(transient.shape, np.uint8) for i, m in enumerate(spec["include"], 1): lab[m & (lab == 0)] = i save(lab, "include") exc = spec.pop("exclude_rois", None) if exc is not None: save(exc, "exclude") yield spec def write_rois(afq, bundles=None, moments=False, synthseg_thalamus=True, no_midline=(), page=True, midline_tol=None, out_dir=None, fornix=True): """Write the ROI masks of a finished run's bundles (start / end / include / exclude) without solving anything, and a viewer page showing them (bundles with no streamlines included). Returns the page's path (or None).""" from .core import bundle_files from .viewer import save_html sh_img = nib.load(afq.export(f"{afq.export('tracking_params')['odf_model'].lower()}_params")) transient, _, _ = tissue_labels(sh_img, nib.load(afq.export("pve_internal")), nib.load(afq.export("brain_mask"))) out = mpat_dir(afq, moments, out_dir) stem = str(out / Path(afq.kwargs["base_fname"]).name) done = bundle_files(out) names = list(bundles or afq.export("bundle_dict")) run_names = [n for n in names if re.sub(r"[^A-Za-z0-9]", "", n) in done] if len(run_names) < len(names): log.warning("no run outputs for %s: their ROIs are not written", [n for n in names if n not in run_names]) thal = _thalami_if_synthseg(afq, sh_img, synthseg_thalamus) for spec in roi_specs(afq, sh_img, transient, stem, run_names, thal, no_midline, midline_tol, fornix): log.info("%s: ROI masks written", spec["name"]) if not page or not run_names: return None return save_html(f"{stem}_desc-mpat_rois.html", str(out), bundles=[re.sub(r"[^A-Za-z0-9]", "", n) for n in run_names], rois=True) def write_viz(afq, bundles=None, moments=False, out_dir=None, rois=False, colormap=None): """Rewrite a finished run's figures (the collage and the viewer pages, as ``run(viz=True)`` writes them) from its outputs on disk, solving nothing -- e.g. after a viewer update. The collage and the all-bundles page always show every bundle with outputs; ``bundles`` (pyAFQ names) limits which per-bundle pages are rewritten (default: all). colormap: see visualize. Returns the folder.""" out = mpat_dir(afq, moments, out_dir) stem = str(out / Path(afq.kwargs["base_fname"]).name) every = bundles_on_disk(afq, out) if not every: raise ValueError(f"no MPAT outputs under {out}") names = every if bundles: want = [re.sub(r"[^A-Za-z0-9]", "", n) for n in bundles] names = [n for n in want if n in every] if len(names) < len(want): log.warning("no run outputs for %s", [n for n in want if n not in every]) sh_path = afq.export(f"{afq.export('tracking_params')['odf_model'].lower()}_params") try: t1 = afq.export("t1_masked") except Exception: # noqa: BLE001 -- the collage falls back to the tissue labels t1 = None visualize(out, stem, names, sh_path, t1=t1, rois=rois, colormap=colormap, all_bundles=every) return out def bundles_on_disk(afq, out): """Every bundle with MPAT outputs under ``out`` (file names, e.g. LeftArcuate): in the bundle dictionary's order, then any others.""" from .core import bundle_files done = bundle_files(out) try: order = [re.sub(r"[^A-Za-z0-9]", "", n) for n in afq.export("bundle_dict")] except Exception: # noqa: BLE001 order = [] return [n for n in order if n in done] + sorted(set(done) - set(order)) def visualize(out, stem, bundles, fodf=None, t1=None, rois=False, colormap=None, all_bundles=None): """The run's figures: a MIP collage of the bundles, a viewer page with all of them (densities and cores), and a page per bundle with its glyphs (and the fODF, if given); ``rois``: the pages also show each bundle's include / exclude ROIs. ``colormap``: NiiVue colour map of the density on every page (default actc; e.g. "turbo", "hot"; "bundle": one hue per bundle). ``all_bundles``: the bundles of the collage and the all-bundles page (default ``bundles``); per-bundle pages are written for ``bundles``. Failures are logged, not raised: the bundles are already on disk.""" from .collage import write_collage from .core import bundle_files from .viewer import save_html every = list(all_bundles or bundles) jobs = [("collage", lambda: write_collage(out, f"{stem}_desc-mpat_collage.png", every, t1=t1)), ("viewer", lambda: save_html(f"{stem}_desc-mpat_view.html", out, bundles=every, rois=rois, colormap=colormap))] files = bundle_files(out) for b in bundles: if b in files: # glyphs from 1e-2 of the peak (the slider can raise it); keeps pages small jobs.append((f"{b} viewer", lambda b=b: save_html( f"{files[b]['prefix']}_desc-view.html", out, bundles=[b], glyphs=True, fodf=fodf, glyph_range=1e-2, rois=rois, colormap=colormap))) for what, job in jobs: try: log.info("%s: %s", what, job()) except Exception as err: # noqa: BLE001 log.warning("%s not written: %s", what, err) def mpat_dir(afq, moments=False, out_dir=None): """Where MPAT's outputs go: ``out_dir`` if given, else <pyAFQ output_dir>/mpat (mpat-moments).""" if out_dir: return Path(out_dir) return Path(afq.kwargs["output_dir"]) / ("mpat-moments" if moments else "mpat") GiB = 1024 ** 3 AUTO_FRACTION, AUTO_HEADROOM = 0.8, 10 * GiB # max_mem="auto": min(80% of the limit, limit - 10 GB) def memory_limit(): """(bytes this process may use, where that came from): the smallest of its cgroup's memory limits (what SLURM and containers enforce), SLURM's request, and physical memory.""" found = [] try: for line in open("/proc/self/cgroup"): hid, ctrl, path = line.rstrip("\n").split(":", 2) if hid == "0" and ctrl == "": # cgroup v2 files = ["memory.max"] root = "/sys/fs/cgroup" elif "memory" in ctrl.split(","): # cgroup v1 files = ["memory.limit_in_bytes"] root = "/sys/fs/cgroup/memory" else: continue p = Path(path) for d in [p, *p.parents]: # the job's cgroup and its parents for f in files: try: v = (Path(root) / d.relative_to("/") / f).read_text().strip() except OSError: continue if v.isdigit() and int(v) < 1 << 60: found.append((int(v), f"cgroup {d}")) except OSError: pass env = os.environ if env.get("SLURM_MEM_PER_NODE", "").isdigit(): found.append((int(env["SLURM_MEM_PER_NODE"]) * 1024 ** 2, "SLURM_MEM_PER_NODE")) elif env.get("SLURM_MEM_PER_CPU", "").isdigit(): cpus = env.get("SLURM_CPUS_ON_NODE") or env.get("SLURM_CPUS_PER_TASK") or "1" if cpus.isdigit(): found.append((int(env["SLURM_MEM_PER_CPU"]) * 1024 ** 2 * int(cpus), "SLURM_MEM_PER_CPU")) try: found.append((os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES"), "physical memory")) except (ValueError, OSError, AttributeError): pass return min(found) if found else (None, "unknown") def memory_in_use(): """Resident memory of this process (bytes; 0 if unknown).""" try: for line in open("/proc/self/status"): if line.startswith("VmRSS:"): return int(line.split()[1]) * 1024 except OSError: pass return 0 def _budget(max_mem, chain, launches): """max_mem as segment_bundles takes it (bytes for the chain, the launches and the solve columns). "auto": min(80% of the memory limit, limit - 10 GB), at least half the limit, less what the process already holds besides the chain and the launches (pyAFQ's data, the fODF, ...). An explicit size is used as given, with a warning above the limit.""" limit, src = memory_limit() held = memory_in_use() other = max(held - chain.nbytes - launches.nbytes, 0) if isinstance(max_mem, str) and max_mem.strip().lower() == "auto": if limit is None: raise ValueError("max_mem='auto': cannot tell this machine's memory limit; give a size") total = max(min(AUTO_FRACTION * limit, limit - AUTO_HEADROOM), 0.5 * limit) budget = total - other log.info("memory: limit %.1f GB (%s), MPAT may use %.1f GB; %.1f GB already held besides the chain " "(%.1f GB) and launches (%.1f GB) -> %.1f GB budget", limit / GiB, src, total / GiB, other / GiB, chain.nbytes / GiB, launches.nbytes / GiB, budget / GiB) return budget b = _bytes(max_mem) if limit is not None and b + other > limit: log.warning("max_mem %.1f GB plus the %.1f GB already held exceeds this job's memory limit " "(%.1f GB, %s): it may be killed; try max_mem='auto'", b / GiB, other / GiB, limit / GiB, src) return b def write_fixels(chain, sh, results, launches, path, affine, tol, max_mem, on_trapped=None, lobes=None, whole=None): """The subject's fixels and each bundle's expected streamlines through them (mpat.fixels), as an MRtrix fixel directory at ``path``: ``<bundle>_streamlines``, ``all_streamlines`` (the unconditioned chain: every walk from every seed, no ROIs), ``<bundle>_share`` (of all walks through the fixel) and ``<bundle>_share_of_bundles`` (of the solved bundles').""" from .fixels import fixel_streamlines, segment_lobes, write_fixel_directory t0 = time.time() ijk = np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1 rows = sh[tuple(ijk.T)] if lobes is None: lobes = segment_lobes(rows, chain.geo) if whole is None: whole = segment_bundles(chain, [dict(name="whole brain")], launches, tol=tol, max_mem=max_mem, on_trapped=on_trapped)["whole brain"] n_all, _ = fixel_streamlines(whole.density_class, rows, chain.geo, lobes) data = {"all_streamlines": n_all} per = {re.sub(r"[^A-Za-z0-9]", "", name): fixel_streamlines(res.density_class, rows, chain.geo, lobes)[0] for name, res in results.items()} n_bundles = sum(per.values()) frac = lambda a, b: np.divide(a, b, out=np.zeros_like(a), where=b > 0) # noqa: E731 for key, n_b in per.items(): data[f"{key}_streamlines"] = n_b data[f"{key}_share"] = frac(n_b, n_all) # of all walks through the fixel data[f"{key}_share_of_bundles"] = frac(n_b, n_bundles) # of the solved bundles' walks write_fixel_directory(path, lobes, ijk, affine, chain.shape, data) log.info("fixels: %d in %d voxels, %d bundles -> %s (%.0fs)", lobes.n_fixels, len(ijk), len(results), path, time.time() - t0) return lobes, data def _bytes(x): if isinstance(x, str): m = re.fullmatch(r"\s*([\d.]+)\s*([kmgt]?)b?\s*", x.lower()) if not m: raise ValueError(f"cannot read memory size {x!r} (e.g. '16GB')") return float(m.group(1)) * 1024 ** "kmgt".find(m.group(2)) * (1024 if m.group(2) else 1) return float(x)
[docs] 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, viz_colormap=None, 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) n_proc threads max_mem memory budget, bytes, e.g. "16GB", or "auto" (default): sets how many bundles share each solve. "auto" reads the job's limit (cgroup / SLURM / physical), keeps min(80%, limit - 10 GB) of it and subtracts what is already held bundles pyAFQ bundle names (default: all in the bundle dictionary) moments spatial first moments (narrower, more accurate bundles; ~5x slower) tol remaining walker mass at which the solves stop (relative) angle maximum turn per one-voxel hop (degrees) double_odf weight each hop by the fODF where it lands (False: singleODF, like pyAFQ's first-order probabilistic tracker) cores also write each bundle's ridge-path core (mpat.core) viz also write a MIP collage of all bundles (PNG), a viewer page of all bundles (densities and cores; both of every bundle in the output folder, so a run of some bundles keeps the others), and one page per bundle with its visitation-ODF glyphs and the fODF (mpat.viewer.save_html). Pages load NiiVue from a CDN. viz_rois the viewer pages also show each bundle's include / exclude ROIs viz_colormap NiiVue colour map of the density on the per-bundle viewer pages (default actc; e.g. "turbo", "hot"), the all-bundles page included ("bundle": one hue per bundle) no_midline bundle names whose cross_midline=False is ignored (no other-hemisphere exclusion) midline_tol mm past the midline the corticospinal tracts may go before the other hemisphere is excluded (default: their rule, 10; 0: a strict cut); every other one-sided bundle follows its own rule (mpat.bundles; default a strict cut at x = 0) max_length soft maximum streamline length (mm; 0: none). Before any bundle is solved, direction states from which most walkers would still be walking after this long -- traps where they circle, unable to turn out under the angle limit -- become invalid ends for every bundle (mpat.solve.overlength_states); the survival per voxel is written to <stem>_desc-overlength_map.nii.gz out_dir write MPAT's outputs here instead of <pyAFQ output_dir>/mpat (mpat-moments); pyAFQ's derivatives are only read. For a GroupAFQ: <out_dir>/sub-<s>/ses-<t> fornix the anterior thalamic radiations exclude the fornix / septum on the midline (FORNIX_BOX_MNI; False: as pyAFQ defines them) verbose log timing inside the solves (ms per power step: matrix product / mask and sum); the time per stage is logged at the end anyway synthseg_thalamus with pyAFQ's SynthSeg tissue (pve unset or "synthseg"), a template start / end ROI that is the thalamus is replaced by SynthSeg's thalamus (see bundle_specs) flux also write each bundle's edge flux (mpat.fields): the expected streamline steps from every voxel into each of its 26 neighbours, and the flux through each voxel. Not with moments. The fields themselves are not kept here; use ``segment_bundles(keep_fields=True)`` to work with them. fixels also write an MRtrix fixel directory, <stem>_desc-mpat_fixels/ (mpat.fixels): the subject's fixels from the fODF, and per fixel each bundle's expected streamlines through it (<bundle>_streamlines), the streamlines of the unconditioned chain (all_streamlines: every walk from every seed, no ROIs, one extra solve), the bundle's share of them (<bundle>_share) and its share of the solved bundles' streamlines (<bundle>_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 (<stem>_bundle-<Name>_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 <stem>_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, viz_colormap=viz_colormap, 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)} numba.set_num_threads(max(1, min(int(n_proc), numba.config.NUMBA_NUM_THREADS))) t0 = time.time() clock = Clock() with clock("pyAFQ inputs"): sh_path = afq.export(f"{afq.export('tracking_params')['odf_model'].lower()}_params") sh_img = nib.load(sh_path) pve_img, bm_img = nib.load(afq.export("pve_internal")), nib.load(afq.export("brain_mask")) with clock("tissue labels"): transient, absorb, dseg = tissue_labels(sh_img, pve_img, bm_img) out = mpat_dir(afq, moments, out_dir) out.mkdir(parents=True, exist_ok=True) stem = str(out / Path(afq.kwargs["base_fname"]).name) nib.save(nib.Nifti1Image(dseg, sh_img.affine), f"{stem}_desc-mpat_dseg.nii.gz") # pyAFQ's tissue from SynthSeg: its thalami stand in for the template's thalamic ROIs with clock("pyAFQ inputs"): thal = _thalami_if_synthseg(afq, sh_img, synthseg_thalamus) def specs(): # each bundle's ROIs warped just before its group is solved, its ROI masks written then # (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, 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"): chain = Chain.build(sh, sh_img.header.get_zooms()[:3], transient, absorb, cfg, cache=f"{stem}_desc-chain_cache.npz") 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 log.info("soft maximum streamline length %.0f mm (%d steps): %d of %d direction states, in %d voxels, " "keep most walkers longer than that and end them invalidly (%.0fs)", max_length, T, kill.sum(), kill.size, int(kill.reshape(-1, chain.nb).any(1).sum()), time.time() - t1_) clock.add("soft max length", time.perf_counter() - t_ol) with clock("seed launches (prepare)"): launches = prepare_launches(chain, seeds) chain.release_pmfs() rows = [] n_trapped = [0] def trapped(what, names, vol): # where the mass a stalled solve could not finish sits: open it over the T1 n_trapped[0] += 1 f = f"{stem}_desc-trapped{what}{n_trapped[0]}_map.nii.gz" nib.save(nib.Nifti1Image(vol, sh_img.affine), f) peak = nib.affines.apply_affine(sh_img.affine, np.unravel_index(np.argmax(vol), vol.shape)) log.warning("%s solve of %s did not finish: the mass left (%.1e of the start) is mapped in %s; " "most of it at (%.0f, %.0f, %.0f) mm", what, ", ".join(names), vol.sum(), f, *peak) budget = _budget(max_mem, chain, launches) from .fixels import segment_lobes 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, max_length_mm=max_length, ) 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}" sp = np.zeros(chain.shape, np.float32) np.add.at(sp, tuple(res.seed_vox.T), res.seed_prob) maps = dict(seedprob=(sp, "probmap"), density=(chain.to_volume(res.density_t), "map"), endpoints=(chain.to_volume(res.endpoints_a, "absorbing"), "map")) d = res.density_t keep = np.flatnonzero(d >= ODF_FLOOR * d.max()) if d.max() > 0 else np.zeros(0, np.int64) ijk = tuple((np.stack(np.unravel_index(chain.t_lin[keep], chain.pshape), 1) - 1).T) coef = visitation_odf(res.density_class[keep], sh[ijk], chain.geo) odf = np.zeros(chain.shape + coef.shape[1:], np.float32) odf[ijk] = coef maps["visitodf"] = (odf, "dwimap") qb = None if getattr(res, "flux26", None) is not None or res.fields is not None: qb = quantify_bundle(chain, res, whole.density_class, sh_rows, sh_img.affine, lobes=lobes, compute_boundary_conductance=False) maps["afd"] = (chain.to_volume(qb.voxel_afd_t), "map") maps["tdimm"] = (chain.to_volume(qb.tdi_mm_t), "map") maps["qharmonic"] = (chain.to_volume(qb.q_harmonic_t), "map") maps["coherence"] = (chain.to_volume(qb.flux_coherence_t), "map") maps["keff"] = (chain.to_volume(qb.branching_k_eff_t), "map") res.info["quantification"] = qb.summary res.start_mask = None res.end_mask = None if res.fields is not None: f26 = res.fields.edge_flux() maps["throughflux"] = (chain.to_volume(res.fields.through_flux(f26)), "map") f26vol = np.zeros(chain.shape + (26,), np.float32) f26vol[tuple((np.stack(np.unravel_index(chain.t_lin, chain.pshape), 1) - 1).T)] = f26 maps["edgeflux"] = (f26vol, "map") res.info["flux_conservation"] = {k: v for k, v in res.fields.conservation(f26).items() if not isinstance(v, np.ndarray)} res.fields = None for desc, (vol, suffix) in maps.items(): nib.save(nib.Nifti1Image(vol, sh_img.affine), f"{b}_desc-{desc}_{suffix}.nii.gz") with open(f"{b}_desc-summary.json", "w") as fh: json.dump(dict(bundle=res.name, config=cfg.key(), result=res.info, valid_ends=[ABSORB_CLASSES[c] for c in (1, 3)], density="expected steps of bundle streamlines in each voxel, all seeds", afd="AFD-calibrated intra-axonal bundle density per voxel (steradians, analytical SIFT2)", tdimm="expected physical chord length traversed per voxel (mm)", qharmonic="harmonic committor coordinate in [0, 1] along the reactive flux graph", coherence="reactive flux directional coherence in [0, 1] per voxel", keff="effective outgoing neighbour branching exp(H) in [1, 26] per voxel", endpoints="expected bundle endpoints per voxel (two per streamline)", visitodf="the walkers' directions per voxel: SH (descoteaux07, legacy, " "lmax 8), expected visits per steradian", seedprob="P(the streamline seeded here belongs to the bundle)", **({"throughflux": "expected bundle-streamline steps leaving each voxel", "edgeflux": "the same per neighbour: 26 volumes, mpat.geometry.OFFSETS order"} if flux else {})), fh, indent=1) i = res.info row = dict(bundle=res.name, expected_streamlines=round(i["expected_bundle_streamlines"], 4)) if qb is not None: row.update( mean_length_mm=qb.summary["mean_streamline_length_mm"], afd_volume_mm3=qb.summary["tract_afd_volume_mm3"], afd_area_mm2=qb.summary["effective_afd_area_mm2"], median_cut_flux=qb.summary["median_cut_flux"], ) row.update(columns=i["n_columns"], backward_steps=i["backward"]["iterations"], forward_steps=i["forward"]["iterations"], seconds=i["seconds"]) rows.append(row) log.info("%s: %.2f expected streamlines", res.name, i["expected_bundle_streamlines"]) results = segment_bundles(chain, specs(), launches, tol=tol, max_mem=budget, on_result=write, on_trapped=trapped, verbose=verbose, clock=clock, keep_fields=flux) if fixels: with clock("fixels"): write_fixels(chain, sh, results, launches, f"{stem}_desc-mpat_fixels", sh_img.affine, tol, budget, on_trapped=trapped, lobes=lobes, whole=whole) with open(f"{stem}_desc-mpat_table.tsv", "w", newline="") as fh: w = csv.DictWriter(fh, fieldnames=list(rows[0]), delimiter="\t") w.writeheader() w.writerows(rows) if cores: 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: t1 = afq.export("t1_masked") except Exception: # noqa: BLE001 -- the collage falls back to the tissue labels t1 = None visualize(out, stem, [re.sub(r"[^A-Za-z0-9]", "", n) for n in results], sh_path, t1=t1, rois=viz_rois, colormap=viz_colormap, all_bundles=bundles_on_disk(afq, out)) clock.add("viz", time.perf_counter() - t_viz) clock.report("MPAT time per stage", time.time() - t0) log.info("MPAT: %d bundles in %.0fs -> %s", len(results), time.time() - t0, out) return results