Repository navigation
Add PTT transitions, branch arbors, transitions I/O and a TRXViz bridge - #18
Merged
Merged
Conversation
- 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.
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_<hash>.npz. Flux streamlines and branch arbors are written as TRX, and extraction failures are reported in the result instead of leaving an empty bundle.
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.
- 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.
- 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.
Keep both sides' new run() options: main's viewer colormap (viz_colormap, --colormap) and this branch's PTT, arbor, SIFT2 and save-transitions options.
Collaborator
|
sorry I undercut this with some ipyniivue changes, if its ready to merge, I can rebase and merge for you |
Collaborator
|
I also pushed one last commit directly to main just now changing default colormap from turbo to actc, i just really wanted to make that change ASAP so people's first experience with the software wouldn't be those ugly isosurfaces |
Brings in the actc default colour map.
Collaborator
Author
|
this should be good to go! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch adds the pieces two downstream users need from MPAT:
desc-transitions_dwimap.odx/.nii.gz).mpat.trxviz_bridge, the subprocess its MPAT nodes call to build transitions and solve a bundle, streaming the solve as it converges so the bundle can be watched forming.qsirecon currently pins MPAT to
af64577, which has none of these options. After this lands, its pin can move to this branch's merge commit.What's in it
mpat run/ CLI options (afq.py,cli.py)--pttswitches to parallel-transport transition defaults (fod_thresh=0.08,fod_power=1.5,curv_sigma=18,probe_radius=0.5,stop_mass=1e-4). Each can also be set on its own with--step,--stop-mass,--fod-thresh,--fod-power,--curv-sigmaand--probe-radius.--sift2calibrates seed launch weights with path-consistent SIFT2 (sift2_optimize_launches) before bundles are solved.--arbor/--arbor-brancheswrite a branch arbor per bundle (desc-arbor.trx,.json,.tsv).--save-transitions {odx,nifti,both}persists the chain's transition probabilities.Transitions I/O (
transitions.py,chain.py)save_transitions_odx/load_transitions_odxstore a chain as an ODX archive: the 26-neighbour stencil, absorbing classes, seed launches, fixel lobes, whole-brain class densities, overlength survival and the fODF SH. A saved chain reloads without the original fODF NIfTI. The header records the chain config and the max length used for overlength states.save_transitions_nifti/load_transitions_niftiwrite and read a 4-D(X, Y, Z, 26)transition NIfTI plus CoDI/CoAsy maps.Chain.save_odx,Chain.load_odx,Chain.save_niftiandChain.from_niftiwrap these.Chain.build(cache=...)also accepts an.odxcache path.marginal_transition_metricscomputes per-voxel CoDI and CoAsy from a chain.Branch arbors and flux streamlines (
branches.py)extract_branch_arbortraces a bundle's trunk and cortical branches along cross-section ridges of its AFD map.extract_flux_streamlinesintegrates RK4 streamlines through the bundle's reactive flux field (BundleResult.flux26), seeded along the arbor and across the bundle's AFD support.write_trx,write_arbor(s),write_isosurface_gifti,write_trxviz_projectandrender_trxvizexport the results.render_trxvizfindstrxviz-clithroughTRXVIZ_CLIorPATH.Solver (
solve.py)segment_bundles(..., on_step=...)calls back with aSolveStep(phase, iteration, residual, solution so far, current wavefront, column signs, and the backward solution during the forward phase) after every iteration. The TRXViz bridge uses this to stream frames; nothing changes when it isn't passed.solve_seriesand_solvepasson_stepthrough.TRXViz bridge (
trxviz_bridge.py)python -m mpat.trxviz_bridge {build_transitions,solve_bundle} <request.json>reads a request written by TRXViz. It reportsPROGRESSlines and finishes with aRESULTJSON line.build_transitionsaccepts four kinds of input:.npz;.nii.gz,.odx,.fib.gz);mpat_transitions_<hash>.npzor a transitions.odx).Other behaviour:
mpat_transitions_<hash>.npz, keyed on the config, max length, fODF, affine and tissue classes..odx, the maps are computed from the fODF stored in the file, which covers white-matter voxels only.pve_internal,desc-mpat_dseg, or a staged.npz) needs a transient white-matter mask from the caller; tissue classes are not guessed from the fODF.solve_bundleapplies TRXViz's ROIs to the cached chain:afq._is_left: from the name, else from the ROI centres.segment_bundles, the same solvermpat runuses. A small custom solver remains only for whatmpat.solvecan't express: absorption inside white matter (aterm_mask, or start/end ROIs that touch no valid absorbing voxel) and no-end masks.STREAM_FRAMEline for each, so TRXViz can animate the backward and forward passes.quantify_bundle), extracts the branch arbor and flux streamlines into one TRX, and writes the AFD, density, TDI, harmonic coordinate, coherence, branching and endpoint maps. Extraction failures are reported in the result'swarningsand summary.Smaller changes
fields.endpoint_patchesandafq.tissue_labelsfall back to SciPy when scikit-image can't be imported.kernel.pyand the package__init__defaultNUMBA_THREADING_LAYERtoworkqueue.Behaviour notes for reviewers
main.afd_tract_metricsstill divides bundle visitation by whole-brain visitation. An earlier version of this branch regularised the denominator, and that was reverted.mpat.transitions; they don't go through MITTENS'sTransitionResultI/O.odxcomes in throughmittens-dmri, which requiresodx>=0.3.2. Nothing reaches for a localodx-rscheckout or adds tosys.path.Testing
pytest tests: 51 passed, 2 skipped (Python 3.12,odx0.3.3 from PyPI,mittens-dmri2.0.0a1).tests/test_transitions_io.pycovers ODX and NIfTI transition round trips, and loading a chain from them.tests/test_trxviz_bridge.pybuilds transitions on a synthetic phantom, then checks:.npzin a folder;mpat run --ptt --save-transitions odx), with the same ROIs driven throughsolve_bundlefrom TRXViz:mpat run's without live streaming, and 0.999997 with it. Total density is within 0.2%, inside the 1e-5 solver tolerance:mpat runsolved the arcuate grouped with another bundle, so it stops at a slightly different point..odxare distinct maps, and a request for a different angle than the file was built with is refused.