Usage#
From Python#
MPAT runs on top of a pyAFQ
ParticipantAFQ, or every participant of a
GroupAFQ. pyAFQ computes the derivatives MPAT needs: the fODF, the tissue PVE and brain
mask, the white/grey-matter interface, and the bundle ROIs warped to the subject. MPAT then
replaces the tracking and segmentation:
from AFQ.api.participant import ParticipantAFQ
import mpat
afq = ParticipantAFQ(dwi, bval, bvec, t1, output_dir)
results = mpat.run(afq, n_proc=8, max_mem="16GB") # -> <output_dir>/mpat/
mpat.run returns {bundle name: BundleResult}, or one such dict per participant for a
GroupAFQ, and writes the files described in Outputs. The options are listed in
Options.
Any pyAFQ setting goes on the ParticipantAFQ, for example:
the fODF model (
tracking_params={"odf_model": ...})the PVE
custom bundle dictionaries, including subject-space ROIs
segmentation_params={"dist_to_atlas": ...}
Note
MPAT uses pyAFQ’s ROI-based bundle definitions: include, exclude, start and end ROIs, and whether a bundle may cross the midline. pyAFQ’s streamline-based criteria (curvature, length, cleaning) have no counterpart in an expectation and are not applied. Bundle definitions: include, exclude and endpoint ROIs says what each kind of ROI means for a streamline, what MPAT adds to pyAFQ’s definitions, and how to define a bundle of your own.
From the command line#
mpat runs pyAFQ and MPAT on one participant:
mpat sub-01_dwi.nii.gz sub-01_dwi.bval sub-01_dwi.bvec sub-01_T1w.nii.gz out/ --n-proc 8 --max-mem 16GB
The T1w image must be registered to the DWI (it is pyAFQ’s t1_file). If no odf_model is
given, the command line uses CSD. Extra ParticipantAFQ arguments go in --afq-kwargs, as
JSON or as a Python expression that gives a dict. The expression can use:
afd(AFQ.data.fetch) andabd(AFQ.api.bundle_dict)the
AFQ.definitionsimage and mapping classesnpandnib
For example, an infant run:
mpat dwi.nii.gz dwi.bval dwi.bvec T2w.nii.gz out/ --n-proc 12 --max-mem 16GB \
--afq-kwargs 'dict(reg_template_spec=afd.read_pediatric_templates()["UNCNeo-withCerebellum-for-babyAFQ"],
bundle_info=abd.baby_bd(), pve="babyseg", brain_mask_definition=BabyBrainMask())'
All flags are listed in Command line.
Lower level: your own volumes#
mpat.run is a thin layer over three calls that work on plain arrays. Use them to run MPAT
without pyAFQ, or on a phantom (as the figures in How MPAT works do):
from mpat import Chain, ChainConfig, prepare_launches, segment_bundles
chain = Chain.build(sh, zooms, transient, absorb_class, ChainConfig(angle=35, double_odf=True))
launches = prepare_launches(chain, seeds) # (S, 3) voxel indices
results = segment_bundles(chain, [dict(name="Arc", start=start_mask, end=end_mask,
include=[roi_a, roi_b], exclude=avoid)],
launches, tol=1e-10, max_mem=8e9)
density = chain.to_volume(results["Arc"].density_t)
sh: SH coefficients (DIPYdescoteaux07, symmetric or full basis).transient: the white-matter mask.absorb_class: 0 outside, 1 grey matter, 2 CSF, 3 brain edge, wherever the voxel is not white matter.