From d1c8192ec513a0201ded49564a26eb8284bbb808 Mon Sep 17 00:00:00 2001 From: Howard Chiu <137316255+chiuhoward@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:11:40 -0800 Subject: [PATCH 1/4] [ENH] Single-shell 3-tissue CSD (SS3T) via cs_dmri Adds ss3t_params (odf_model="SS3TCSD"): Dhollander responses, SS3T-CSD and mtnormalise from cs_dmri on pyAFQ's data, gtab and brain mask. The WM fODF is projected from cs_dmri's tournier07 basis onto descoteaux07; GM and CSF signal fractions are written alongside. Optional extra pyAFQ[ss3t]. Co-Authored-By: Claude Opus 5.5 (1M context) --- AFQ/tasks/data.py | 91 ++++++++++++++++++++++++++++++++ AFQ/tests/test_api.py | 24 +++++++++ AFQ/tractography/tractography.py | 3 +- docs/source/references.bib | 9 ++++ setup.cfg | 3 ++ 5 files changed, 129 insertions(+), 1 deletion(-) diff --git a/AFQ/tasks/data.py b/AFQ/tasks/data.py index 27f984c6..45a59833 100644 --- a/AFQ/tasks/data.py +++ b/AFQ/tasks/data.py @@ -855,6 +855,96 @@ def rumba_params( ] +@immlib.calc("ss3tcsd_params", "ss3tcsd_gm", "ss3tcsd_csf") +@as_file( + suffix=[ + "_model-ss3tcsd_param-wm_dwimap.nii.gz", + "_model-ss3tcsd_param-gm_dwimap.nii.gz", + "_model-ss3tcsd_param-csf_dwimap.nii.gz", + ], + subfolder="models", +) +@as_img +def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order=8): + """ + full path to a nifti file containing + parameters for the SS3T CSD white matter fit, + full path to a nifti file containing + parameters for the SS3T CSD gray matter fit, + full path to a nifti file containing + parameters for the SS3T CSD cerebrospinal fluid fit + + Parameters + ---------- + ss3t_sh_order : int, optional. + Spherical harmonic order to use for the SS3T CSD fit. + Default: 8 + + References + ---------- + .. [1] T. Dhollander and A. Connelly. A novel iterative approach + to reap the benefits of multi-tissue CSD from just + single-shell (+b=0) diffusion MRI data. ISMRM (2016), p. 3010 + """ + try: + import cs_dmri + except ImportError as err: + raise ImportError( + "SS3T CSD requires cs_dmri: pip install 'pyAFQ[ss3t]'" + ) from err + citations.add("dhollander2016novel") + + dwi = cs_dmri.DWI(data, gtab, mask=nib.load(brain_mask).get_fdata()) + responses = dwi.estimate_responses(lmax_wm=ss3t_sh_order) + logger.info("Fitting Single-Shell 3-Tissue CSD model...") + ss3t_fit = ( + cs_dmri.SS3TModel( + dwi.gtab, responses, lmax_wm=ss3t_sh_order, bvec_frame="image" + ) + .fit(dwi) + .mtnormalise() + ) + + # cs_dmri fits in the tournier07 basis; project onto descoteaux07 + sh_order = shm.order_from_ncoef(ss3t_fit.wm.shape[-1]) + sphere = get_sphere(name="repulsion724") + B = shm.sh_to_sf_matrix( + sphere, + sh_order_max=sh_order, + basis_type="tournier07", + legacy=False, + return_inv=False, + ) + _, invB = shm.sh_to_sf_matrix(sphere, sh_order_max=sh_order) + + def _get_meta(desc, sh_order, response): + return dict( + Model=dict( + Description=( + "Single-Shell 3-Tissue (SS3T) " + "Constrained Spherical Deconvolution (CSD)" + ), + URL="https://github.com/PennLINC/cs_dmri", + ), + Description=desc, + NonNegativity="constrained", + OrientationEncoding=dict( + EncodingAxis=3, + Reference="xyz", + SphericalHarmonicBasis="descoteaux", + SphericalHarmonicDegree=sh_order, + Type="sh", + ), + ResponseFunction=dict(Coefficients=response.coeffs.tolist(), Type="zonal"), + ) + + return [ + (ss3t_fit.wm @ (B @ invB), _get_meta("White matter", sh_order, responses.wm)), + (ss3t_fit.gm, _get_meta("Gray matter", 0, responses.gm)), + (ss3t_fit.csf, _get_meta("Cerebro-spinal fluid", 0, responses.csf)), + ] + + @immlib.calc("opdt_params", "opdt_gfa") @as_file( suffix=[ @@ -1529,6 +1619,7 @@ def get_data_plan(kwargs): dki_cp, dki_cs, rumba_params, + ss3t_params, csd_params, get_bundle_dict, ] diff --git a/AFQ/tests/test_api.py b/AFQ/tests/test_api.py index ff1f4434..215fb22c 100644 --- a/AFQ/tests/test_api.py +++ b/AFQ/tests/test_api.py @@ -14,7 +14,9 @@ import numpy.testing as npt import pandas as pd import pytest +from dipy.data import get_sphere from dipy.io.streamline import load_tractogram +from dipy.reconst.shm import order_from_ncoef, sh_to_sf from dipy.segment.metric import mdf from pandas.testing import assert_series_equal from pcollections._lazy import LazyError @@ -369,6 +371,28 @@ def test_AFQ_data(): assert len(os.listdir(op.join(myafq.afq_path, "sub-01", "ses-01", "dwi"))) == 0 +def test_AFQ_ss3t(): + """ + Test if SS3T CSD fODF peaks agree with CSD's in white matter + """ + pytest.importorskip("cs_dmri") + _, bids_path, _ = get_temp_hardi() + myafq = GroupAFQ( + bids_path=bids_path, + dwi_preproc_pipeline="vistasoft", + t1_preproc_pipeline="freesurfer", + ) + wm = nib.load(myafq.export("dti_fa")["01"]).get_fdata() > 0.5 + sphere = get_sphere(name="repulsion724") + peaks = [] + for model in ["ss3tcsd_params", "csd_params"]: + sh = nib.load(myafq.export(model)["01"]).get_fdata()[wm] + sf = sh_to_sf(sh, sphere, sh_order_max=order_from_ncoef(sh.shape[-1])) + peaks.append(sphere.vertices[np.argmax(sf, -1)]) + agreement = np.mean(np.abs(np.sum(peaks[0] * peaks[1], -1))) + npt.assert_array_less(0.9, agreement) + + def test_AFQ_seed_array(): """ Test if API can run with an array of seeds passed in diff --git a/AFQ/tractography/tractography.py b/AFQ/tractography/tractography.py index 5ef74c38..ed931bba 100644 --- a/AFQ/tractography/tractography.py +++ b/AFQ/tractography/tractography.py @@ -112,7 +112,8 @@ def track( The maximum length (mm) in a streamline. Default: 500 odf_model : str or Definition, optional Can be either a string or Definition. If a string, it must be one of - {"DTI", "CSD", "DKI", "GQ", "RUMBA", "MSMT_AODF", "CSD_AODF", "MSMTCSD"}. + {"DTI", "CSD", "DKI", "GQ", "RUMBA", "MSMT_AODF", "CSD_AODF", "MSMTCSD", + "SS3TCSD"}. If a Definition, we assume it is a definition of a file containing Spherical Harmonics coefficients. Default: "CSD_AODF" diff --git a/docs/source/references.bib b/docs/source/references.bib index 1d66a28f..e133de71 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -457,6 +457,15 @@ @article{jeurissen2014multi publisher={Elsevier} } +@inproceedings{dhollander2016novel, + title={A novel iterative approach to reap the benefits of multi-tissue {CSD} from just single-shell (+b=0) diffusion {MRI} data}, + author={Dhollander, Thijs and Connelly, Alan}, + booktitle={Proceedings of the International Society for Magnetic Resonance in Medicine}, + volume={24}, + pages={3010}, + year={2016} +} + @article{smith2012anatomically, title={Anatomically-constrained tractography: improved diffusion MRI streamlines tractography through effective use of anatomical information}, author={Smith, Robert E and Tournier, Jacques-Donald and Calamante, Fernando and Connelly, Alan}, diff --git a/setup.cfg b/setup.cfg index a05b4889..7442ca6c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -92,6 +92,8 @@ aws = boto3>=1.14.0 nn = onnxruntime +ss3t = + cs_dmri gpu = cuslines[cu13]==2.2.3 onnxruntime-gpu @@ -104,3 +106,4 @@ all = %(afqbrowser)s %(aws)s %(nn)s + %(ss3t)s From c8492cc8b5a86f904ca47a9a730adaa8ec61e3a2 Mon Sep 17 00:00:00 2001 From: Howard Chiu <137316255+chiuhoward@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:14:38 -0800 Subject: [PATCH 2/4] Name the optional extra after the package: pyAFQ[cs_dmri] Co-Authored-By: Claude Opus 5.5 (1M context) --- AFQ/tasks/data.py | 2 +- setup.cfg | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AFQ/tasks/data.py b/AFQ/tasks/data.py index 45a59833..b9bf487b 100644 --- a/AFQ/tasks/data.py +++ b/AFQ/tasks/data.py @@ -890,7 +890,7 @@ def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order=8): import cs_dmri except ImportError as err: raise ImportError( - "SS3T CSD requires cs_dmri: pip install 'pyAFQ[ss3t]'" + "SS3T CSD requires cs_dmri: pip install 'pyAFQ[cs_dmri]'" ) from err citations.add("dhollander2016novel") diff --git a/setup.cfg b/setup.cfg index 7442ca6c..0b9dfa29 100644 --- a/setup.cfg +++ b/setup.cfg @@ -92,7 +92,7 @@ aws = boto3>=1.14.0 nn = onnxruntime -ss3t = +cs_dmri = cs_dmri gpu = cuslines[cu13]==2.2.3 @@ -106,4 +106,4 @@ all = %(afqbrowser)s %(aws)s %(nn)s - %(ss3t)s + %(cs_dmri)s From 04208ba3f8baf66d8af6672aa9956546c248de4f Mon Sep 17 00:00:00 2001 From: Howard Chiu <137316255+chiuhoward@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:16:47 -0800 Subject: [PATCH 3/4] Use ss3t_sh_order_max, as csd/opdt/csa do Co-Authored-By: Claude Opus 5.5 (1M context) --- AFQ/tasks/data.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AFQ/tasks/data.py b/AFQ/tasks/data.py index b9bf487b..54abde7c 100644 --- a/AFQ/tasks/data.py +++ b/AFQ/tasks/data.py @@ -865,7 +865,7 @@ def rumba_params( subfolder="models", ) @as_img -def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order=8): +def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order_max=8): """ full path to a nifti file containing parameters for the SS3T CSD white matter fit, @@ -876,7 +876,7 @@ def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order=8): Parameters ---------- - ss3t_sh_order : int, optional. + ss3t_sh_order_max : int, optional. Spherical harmonic order to use for the SS3T CSD fit. Default: 8 @@ -895,11 +895,11 @@ def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order=8): citations.add("dhollander2016novel") dwi = cs_dmri.DWI(data, gtab, mask=nib.load(brain_mask).get_fdata()) - responses = dwi.estimate_responses(lmax_wm=ss3t_sh_order) + responses = dwi.estimate_responses(lmax_wm=ss3t_sh_order_max) logger.info("Fitting Single-Shell 3-Tissue CSD model...") ss3t_fit = ( cs_dmri.SS3TModel( - dwi.gtab, responses, lmax_wm=ss3t_sh_order, bvec_frame="image" + dwi.gtab, responses, lmax_wm=ss3t_sh_order_max, bvec_frame="image" ) .fit(dwi) .mtnormalise() From 27203fb198e4e423ec34899bad2d984a6460e0d6 Mon Sep 17 00:00:00 2001 From: Howard Chiu <137316255+chiuhoward@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:38:44 -0800 Subject: [PATCH 4/4] Test the tournier07 -> descoteaux07 conversion exactly Replace the end-to-end SS3T vs CSD peak-agreement test in test_api.py with a unit test in test_csd.py that checks the projection against cs_dmri's own export of an SS3T fit to DIPY's descoteaux07 basis. Co-Authored-By: Claude Opus 5.5 (1M context) --- AFQ/tasks/data.py | 35 +++++++++++++++++++++++------------ AFQ/tests/test_api.py | 24 ------------------------ AFQ/tests/test_csd.py | 39 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 36 deletions(-) diff --git a/AFQ/tasks/data.py b/AFQ/tasks/data.py index 54abde7c..a6a5996a 100644 --- a/AFQ/tasks/data.py +++ b/AFQ/tasks/data.py @@ -855,6 +855,24 @@ def rumba_params( ] +def _tournier07_to_descoteaux07(sh): + """ + Project SH coefficients in the tournier07 basis (MRtrix3's, which + cs_dmri fits in) onto the legacy descoteaux07 basis pyAFQ uses + """ + sh_order = shm.order_from_ncoef(sh.shape[-1]) + sphere = get_sphere(name="repulsion724") + B = shm.sh_to_sf_matrix( + sphere, + sh_order_max=sh_order, + basis_type="tournier07", + legacy=False, + return_inv=False, + ) + _, invB = shm.sh_to_sf_matrix(sphere, sh_order_max=sh_order) + return sh @ (B @ invB) + + @immlib.calc("ss3tcsd_params", "ss3tcsd_gm", "ss3tcsd_csf") @as_file( suffix=[ @@ -905,17 +923,7 @@ def ss3t_params(gtab, data, brain_mask, citations, ss3t_sh_order_max=8): .mtnormalise() ) - # cs_dmri fits in the tournier07 basis; project onto descoteaux07 - sh_order = shm.order_from_ncoef(ss3t_fit.wm.shape[-1]) - sphere = get_sphere(name="repulsion724") - B = shm.sh_to_sf_matrix( - sphere, - sh_order_max=sh_order, - basis_type="tournier07", - legacy=False, - return_inv=False, - ) - _, invB = shm.sh_to_sf_matrix(sphere, sh_order_max=sh_order) + sh_order = ss3t_fit.lmax_wm def _get_meta(desc, sh_order, response): return dict( @@ -939,7 +947,10 @@ def _get_meta(desc, sh_order, response): ) return [ - (ss3t_fit.wm @ (B @ invB), _get_meta("White matter", sh_order, responses.wm)), + ( + _tournier07_to_descoteaux07(ss3t_fit.wm), + _get_meta("White matter", sh_order, responses.wm), + ), (ss3t_fit.gm, _get_meta("Gray matter", 0, responses.gm)), (ss3t_fit.csf, _get_meta("Cerebro-spinal fluid", 0, responses.csf)), ] diff --git a/AFQ/tests/test_api.py b/AFQ/tests/test_api.py index 215fb22c..ff1f4434 100644 --- a/AFQ/tests/test_api.py +++ b/AFQ/tests/test_api.py @@ -14,9 +14,7 @@ import numpy.testing as npt import pandas as pd import pytest -from dipy.data import get_sphere from dipy.io.streamline import load_tractogram -from dipy.reconst.shm import order_from_ncoef, sh_to_sf from dipy.segment.metric import mdf from pandas.testing import assert_series_equal from pcollections._lazy import LazyError @@ -371,28 +369,6 @@ def test_AFQ_data(): assert len(os.listdir(op.join(myafq.afq_path, "sub-01", "ses-01", "dwi"))) == 0 -def test_AFQ_ss3t(): - """ - Test if SS3T CSD fODF peaks agree with CSD's in white matter - """ - pytest.importorskip("cs_dmri") - _, bids_path, _ = get_temp_hardi() - myafq = GroupAFQ( - bids_path=bids_path, - dwi_preproc_pipeline="vistasoft", - t1_preproc_pipeline="freesurfer", - ) - wm = nib.load(myafq.export("dti_fa")["01"]).get_fdata() > 0.5 - sphere = get_sphere(name="repulsion724") - peaks = [] - for model in ["ss3tcsd_params", "csd_params"]: - sh = nib.load(myafq.export(model)["01"]).get_fdata()[wm] - sf = sh_to_sf(sh, sphere, sh_order_max=order_from_ncoef(sh.shape[-1])) - peaks.append(sphere.vertices[np.argmax(sf, -1)]) - agreement = np.mean(np.abs(np.sum(peaks[0] * peaks[1], -1))) - npt.assert_array_less(0.9, agreement) - - def test_AFQ_seed_array(): """ Test if API can run with an array of seeds passed in diff --git a/AFQ/tests/test_csd.py b/AFQ/tests/test_csd.py index 82baa3d4..6bfc6619 100644 --- a/AFQ/tests/test_csd.py +++ b/AFQ/tests/test_csd.py @@ -6,6 +6,7 @@ import numpy as np import numpy.testing as npt import pytest +from dipy.reconst import shm from dipy.reconst.shm import calculate_max_order from AFQ.models import csd @@ -82,3 +83,41 @@ def test_afod(): ) npt.assert_allclose(aodf_pyafq, aodf_scilpy, atol=1e-6) + + +def test_tournier07_to_descoteaux07(): + """ + The projection matches, on the sphere, cs_dmri's own export of an SS3T + fit to DIPY's descoteaux07 basis + """ + cs = pytest.importorskip("cs_dmri") + from dipy.io.peaks import load_pam + + from AFQ.tasks.data import _tournier07_to_descoteaux07 + + shape, lmax = (5, 5, 4), 8 + rng = np.random.default_rng(0) + wm = rng.normal(size=shape + (45,)).astype(np.float32) + responses = cs.ResponseSet( + wm=cs.TissueResponse( + np.array([[3.5, 0, 0, 0, 0], [1.2, -0.6, 0.2, -0.05, 0.01]]), lmax + ), + gm=cs.TissueResponse(np.array([[3.0], [1.0]]), 0), + csf=cs.TissueResponse(np.array([[4.0], [0.3]]), 0), + ) + # on a RAS+ grid cs_dmri's world frame is the image frame + fit = cs.SS3TFit( + wm=wm, + gm=np.full(shape, 0.05, np.float32), + csf=np.full(shape, 0.02, np.float32), + lmax_wm=lmax, + mask=np.ones(shape, bool), + affine=np.diag([2.0, 2.0, 2.0, 1.0]), + frame="world", + responses=responses, + ) + with nbtmp.InTemporaryDirectory() as tmpdir: + fit.export(op.join(tmpdir, "fit.pam5")) + ref = load_pam(op.join(tmpdir, "fit.pam5")).shm_coeff + B, _ = shm.sh_to_sf_matrix(dpd.get_sphere(name="symmetric362"), sh_order_max=lmax) + npt.assert_allclose(_tournier07_to_descoteaux07(wm) @ B, ref @ B, atol=1e-4)