From 92a84413ba2e0d272e7741642608669bcf638052 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Thu, 15 Aug 2024 19:16:53 -0400 Subject: [PATCH 1/2] DOC: Miscellaneous improvements to references file Miscellaneous improvements to references file: - Add missing references. Renumber keys when previous author/year entries exist. - Remove duplicate "and" appearances between author names. - Fix wrong years in entry keys. - Remove `Coupe2011` entry: a duplicate of `Coupe2008`, which had the right year. - Fix URL swap between Descoteaux and Garyfallidis PhD entries. - Avoid using ticks or dashes in entry keys. Take advantage of the commit to increase style consistency: - Move fields to keep the sorting consistent. - Remove whitespaces before entry closing brackets. - Remove unnecessary double brackets to `booktitle` field in reference file. Disambiguate keys when multiple author/year/month matches exist by using the venue name. --- doc/devel/bibliography.rst | 4 +- doc/references.bib | 219 ++++++++++++++++++++++++++++--------- 2 files changed, 170 insertions(+), 53 deletions(-) diff --git a/doc/devel/bibliography.rst b/doc/devel/bibliography.rst index cd4d91249a..726886c6ac 100644 --- a/doc/devel/bibliography.rst +++ b/doc/devel/bibliography.rst @@ -18,7 +18,9 @@ The following conventions are used in that file. added after the year to distinguish them, e.g. ``Garyfallidis2012a``, ``Garyfallidis2012b``, starting with the least recent work (including works across groups). Within the same group, the least recent work is put closest - to the end of the file. + to the end of the file. Similarly, if multiple works of the same author + appeared in the same month, the name of the venue (i.e. its first letter) + is used to distinguish works, following the rules described for the year. - Strictly unnecessary (e.g. ``abstract``) or non-standard fields (``issn``) should be avoided. - Author full names (i.e. including their first names) are used, and names use diff --git a/doc/references.bib b/doc/references.bib index f50c6231a6..543580487f 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -204,7 +204,7 @@ @article{Bresenham1965 doi = {10.1147/sj.41.0025} } -@article{Canales-Rodriguez2015, +@article{CanalesRodriguez2015, author = {Erick J. Canales-Rodr\'{i}guez and Alessandro Daducci and Stamatios N. Sotiropoulos and Emmanuel Caruyer and Santiago Aja-Fern\'{a}ndez and Joaquim Radua and Jes\'{u}s M. Yurramendi Mendizabal and Yasser Iturria-Medina and Lester Melie-Garc\'{i}a and Yasser Alem\'{a}n-G\'{o}mez and Jean-Philippe Thiran and Salvador Sarr\'{o} and Edith Pomarol-Clotet and Raymond Salvador}, title = {{Spherical Deconvolution of Multichannel Diffusion MRI Data with Non-Gaussian Noise Models and Spatial Regularization}}, journal = {PLOS ONE}, @@ -216,7 +216,7 @@ @article{Canales-Rodriguez2015 url = {https://doi.org/10.1371/journal.pone.0138910} } -@article{Canales-Rodriguez2010, +@article{CanalesRodriguez2010, author = {Erick J. Canales-Rodr\'{i}guez and Yasser Iturria-Medina and Yasser Alem\'{a}n-G\'{o}mez and Lester Melie-Garc\'{i}a}, title = {{Deconvolution in diffusion spectrum imaging}}, journal = {NeuroImage}, @@ -326,6 +326,18 @@ @article{Chung2006 url = {https://doi.org/10.1016/j.neuroimage.2006.07.001} } +@article{CohenAdad2011, + author = {Julien Cohen-Adad and Maxime Descoteaux and Lawrence L. Wald}, + title = {{Quality assessment of high angular resolution diffusion imaging data using bootstrap on Q-ball reconstruction}}, + journal = {Journal of Magnetic Resonance Imaging}, + volume = {33}, + number = {5}, + pages = {1194-1208}, + year = {2011}, + doi = {10.1002/jmri.22535}, + url = {https://doi.org/10.1002/jmri.22535} +} + @article{Constantinides1997 author = {Chris D. Constantinides and Ergin Atalar and Elliot R. McVeigh}, title = {{Signal-to-noise measurements in magnitude images from NMR phased arrays}}, @@ -350,7 +362,7 @@ @article{Cook2007 url = {https://doi.org/10.1002/jmri.20905} } -@article{Correia2001, +@article{Correia2011b, author = {Marta Morgado Correia and Virginia F. J. Newcombe and Guy B. Williams}, title = {{Contrast-to-noise ratios for indices of anisotropy obtained from diffusion MRI: A study with standard clinical b-values at 3T}}, journal = {NeuroImage}, @@ -358,6 +370,7 @@ @article{Correia2001 number = {3}, pages = {1103-1115}, year = {2011}, + month = {August}, doi = {10.1016/j.neuroimage.2011.03.004}, url = {https://doi.org/10.1016/j.neuroimage.2011.03.004}, note = {Special Issue: Educational Neuroscience} @@ -391,18 +404,6 @@ @article{Coupe2012 url = {https://doi.org/10.1049/iet-ipr.2011.0161} } -@article{Coupe2011, - author = {Pierrick Coup\'{e} and Pierre Yger and Sylvain Prima and Pierre Hellier and Charles Kervrann and Christian Barillot}, - title = {{An Optimized Blockwise Nonlocal Means Denoising Filter for 3-D Magnetic Resonance Images}}, - journal = {IEEE Transactions on Medical Imaging}, - volume = {27}, - number = {4}, - pages = {425--441}, - year = {2011}, - doi = {10.1109/TMI.2008.2008967}, - url = {https://doi.org/10.1109/TMI.2008.2008967} -} - @article{Coupe2008, author = {Pierrick Coup\'{e} and Pierre Yger and Sylvain Prima and Pierre Hellier and Charles Kervrann and Christian Barillot}, title = {{An Optimized Blockwise Nonlocal Means Denoising Filter for 3-D Magnetic Resonance Images}}, @@ -411,7 +412,8 @@ @article{Coupe2008 number = {4}, pages = {425-441}, year = {2008}, - doi = {10.1109/TMI.2007.906087} + doi = {10.1109/TMI.2007.906087}, + url = {https://doi.org/10.1109/TMI.2008.2008967} } @article{Craven1979, @@ -445,7 +447,7 @@ @article{DellAcqua2007 pages = {462-472}, year = {2007}, doi = {10.1109/TBME.2006.888830} - } +} @article{Descoteaux2011, author = {Maxime Descoteaux and Rachid Deriche and Denis {Le Bihan} and Jean-Fran\c{c}ois Mangin and Cyril Poupon}, @@ -571,7 +573,7 @@ @article{Fick2018 url = {https://doi.org/10.1016/j.media.2017.09.002} } -@article{Fick2016, +@article{Fick2016b, author = {Rutger H. J. Fick and Demian Wassermann and Emmanuel Caruyer and Rachid Deriche}, title = {{MAPL: Tissue microstructure estimation using Laplacian-regularized MAP-MRI and its application to HCP data}}, journal = {NeuroImage}, @@ -630,7 +632,7 @@ @article{Garyfallidis2015 month = {August}, doi = {10.1016/j.neuroimage.2015.05.016}, url = {https://doi.org/10.1016/j.neuroimage.2015.05.016} - } +} @article{Garyfallidis2012a, author = {Eleftherios Garyfallidis and Matthew Brett and Marta M. Correia and Guy B. Williams and Ian Nimmo-Smith}, @@ -680,6 +682,20 @@ @article{Glenn2015 url = {https://doi.org/10.1002/nbm.3271} } +@article{Gorgolewski2016, + author = {Krzysztof J. Gorgolewski and Tibor Auer and Vince D. Calhoun and R. Cameron Craddock and Samir Das and Eugene P. Duff and Guillaume Flandin and Satrajit S. Ghosh and Tristan Glatard and Yaroslav O. Halchenko and Daniel A. Handwerker and Michael Hanke and David Keator and Xiangrui Li and Zachary Michael and Camille Maumet and B. Nolan Nichols and Thomas E. Nichols and John Pellman and Jean-Baptiste Poline and Ariel Rokem and Gunnar Schaefer and Vanessa Sochat and William Triplett and Jessica A. Turner and Ga{\"e}l Varoquaux and Russell A. Poldrack}, + title = {The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments}, + journal = {Scientific Data}, + volume = {3}, + number = {1}, + pages = {160044}, + year = {2016}, + month = {June}, + doi = {10.1038/sdata.2016.44}, + url = {https://doi.org/10.1038/sdata.2016.44} +} + + @article{Greene2018, author = {Clint Greene and Matt Cieslak and Scott T. Grafton}, title = {{Effect of different spatial normalization approaches on tractography and structural brain networks}}, @@ -730,6 +746,19 @@ @article{Hansen2016a url = {https://doi.org/10.1038/sdata.2016.72} } +@article{Hansen2013, + author = {Brian Hansen and Torben E. Lund and Ryan Sangill and Sune N\o{}rh\o{}j Jespersen}, + title = {{Experimentally and computationally fast method for estimation of a mean kurtosis}}, + journal = {Magnetic Resonance in Medicine}, + volume = {69}, + number = {6}, + pages = {1754-1760}, + year = {2013}, + doi = {10.1002/mrm.24743}, + url = {https://doi.org/10.1002/mrm.24743} +} + + @article{Hardin1996, author = {Ronald H. Hardin and Neil J. A. Sloane}, title = {McLaren's improved snub cube and other new spherical designs in three dimensions}, @@ -753,7 +782,7 @@ @article{Haroon2009 doi = {10.1109/TMI.2008.2006528} } -@article{Herberthson20211, +@article{Herberthson2021, author = {Magnus Herberthson and Deneb Boito and Tom Dela Haije and Aasa Feragen and Carl-Fredrik Westin and Evren {\"O}zarslan}, title = {{Q-space trajectory imaging with positivity constraints (QTI+)}}, journal = {NeuroImage}, @@ -934,7 +963,7 @@ @article{Koay2009a url = {https://doi.org/10.1016/j.jmr.2008.11.015} } -@article{Koay2006b, +@article{Koay2006c, author = {Cheng Guan Koay and Lin-Ching Chang and John D. Carew and Carlo Pierpaoli and Peter J. Basser}, title = {{A unifying theoretical and algorithmic framework for least squares methods of estimation in diffusion tensor imaging}}, journal = {Journal of Magnetic Resonance}, @@ -947,7 +976,7 @@ @article{Koay2006b url = {https://doi.org/10.1016/j.jmr.2006.06.020} } -@article{Koay2006a, +@article{Koay2006b, author = {Cheng Guan Koay and John D. Carew and Andrew L. Alexander and Peter J. Basser, and M. Elizabeth Meyerand}, title = {{Investigation of anomalous estimates of tensor-derived quantities in diffusion tensor imaging}}, journal = {Magnetic Resonance in Medicine}, @@ -960,6 +989,19 @@ @article{Koay2006a url = {https://doi.org/10.1002/mrm.20832} } +@article{Koay2006a, + author = {Cheng Guan Koay and Peter J. Basser}, + title = {{Analytically exact correction scheme for signal extraction from noisy magnitude MR signals}}, + journal = {Journal of Magnetic Resonance}, + volume = {179}, + number = {2}, + pages = {317-322}, + month = {April}, + year = {2006}, + doi = {10.1016/j.jmr.2006.01.016}, + url = {https://doi.org/10.1016/j.jmr.2006.01.016} +} + @article{LeBihan1988, author = {Denis {Le Bihan} and Eric Breton and Denis Lallemand and M. L. Aubin and Jacqueline Vignaud and Maurice Laval-Jeantet}, title = {{Separation of diffusion and perfusion in intravoxel incoherent motion MR imaging}}, @@ -1222,7 +1264,7 @@ @article{Renauld2016 url = {https://doi.org/10.1371/journal.pone.0156436} } -@article{Richie-Halford2022, +@article{RichieHalford2022, author = {Adam Richie-Halford and Matthew Cieslak and Lei Ai and Sendy Caffarra and Sydney Covitz and Alexandre R. Franco and Iliana I. Karipidis and John Kruper and Michael Milham and B\'{a}rbara Avelar-Pereira and Ethan Roy and Valerie J. Sydnor and Jason D. Yeatman and Nicholas J. Abbott and John A. E. Anderson and B. Gagana and MaryLena Bleile and Peter S. Bloomfield and Vince Bottom and Josiane Bourque and Rory Boyle and Julia K. Brynildsen and Navona Calarco and Jaime J. Castrellon and Natasha Chaku and Bosi Chen and Sidhant Chopra and Emily B. J. Coffey and Nigel Colenbier and Daniel J. Cox and James Elliott Crippen and Jacob J. Crouse and Szabolcs David and Benjamin De Leener and Gwyneth Delap and Zhi-De Deng and Jules Roger Dugre and Anders Eklund and Kirsten Ellis and Arielle Ered and Harry Farmer and Joshua Faskowitz and Jody E. Finch and Guillaume Flandin and Matthew W. Flounders and Leon Fonville and Summer B. Frandsen and Dea Garic and Patricia Garrido-V\'{a}squez and Gabriel Gonzalez-Escamilla and Shannon E. Grogans and Mareike Grotheer and David C. Gruskin and Guido I. Guberman and Edda Briana Haggerty and Younghee Hahn and Elizabeth H. Hall and Jamie L. Hanson and Yann Harel and Bruno Hebling Vieira and Meike D. Hettwer and Harriet Hobday and Corey Horien and Fan Huang and Zeeshan M. Huque and Anthony R. James and Isabella Kahhale and Sarah L. H. Kamhout and Arielle S. Keller and Harmandeep Singh Khera and Gregory Kiar and Peter Alexander Kirk and Simon H. Kohl and Stephanie A. Korenic and Cole Korponay and Alyssa K. Kozlowski and Nevena Kraljevic and Alberto Lazari and Mackenzie J. Leavitt and Zhaolong Li and Giulia Liberati and Elizabeth S. Lorenc and Annabelle Julina Lossin and Leon D. Lotter and David M. Lydon-Staley and Christopher R. Madan and Neville Magielse and Hilary A. Marusak and Julien Mayor and Amanda L. McGowan and Kahini P. Mehta and Steven Lee Meisler and Cleanthis Michael and Mackenzie E. Mitchell and Simon Morand-Beaulieu and Benjamin T. Newman and Jared A. Nielsen and Shane M. O'Mara and Amar Ojha and Adam Omary and Evren {\"O}zarslan and Linden Parkes and Madeline Peterson and Adam Robert Pines and Claudia Pisanu and Ryan R. Rich and Matthew D. Sacchet and Ashish K. Sahoo and Amjad Samara and Farah Sayed and Jonathan Thore Schneider and Lindsay S. Shaffer and Ekaterina Shatalina and Sara A. Sims and Skyler Sinclair and Jae W. Song and Griffin Stockton Hogrogian and Christian K. Tamnes and Ursula A. Tooley and Vaibhav Tripathi and Hamid B. Turker and Sofie Louise Valk and Matthew B. Wall and Cheryl K. Walther and Yuchao Wang and Bertil Wegmann and Thomas Welton and Alex I. Wiesman and Andrew G. Wiesman and Mark Wiesman and Drew E. Winters and Ruiyi Yuan and Sadie J. Zacharek and Chris Zajner and Ilya Zakharov and Gianpaolo Zammarchi and Dale Zhou and Benjamin Zimmerman and Kurt Zoner and Theodore D. Satterthwaite and Ariel Rokem and The Fibr Community Science Consortium}, title = {{An analysis-ready and quality controlled resource for pediatric brain white-matter research}}, journal = {Scientific Data}, @@ -1409,7 +1451,7 @@ @article{Tournier2004 url = {https://doi.org/10.1016/j.neuroimage.2004.07.037} } -@article{Tristan-Vega2010, +@article{TristanVega2010, author = {Antonio Trist\'{a}n-Vega and Carl-Fredrik Westin and Santiago Aja-Fern\'{a}ndez}, title = {{A new methodology for the estimation of fiber populations in the white matter of the brain with the Funk–Radon transform}}, journal = {NeuroImage}, @@ -1421,7 +1463,7 @@ @article{Tristan-Vega2010 url = {https://doi.org/10.1016/j.neuroimage.2009.09.070} } -@article{Tristan-Vega2009, +@article{TristanVega2009, author = {Antonio Trist\'{a}n-Vega and Carl-Fredrik Westin and Santiago Aja-Fern\'{a}ndez}, title = {{Estimation of fiber Orientation Probability Density Functions in High Angular Resolution Diffusion Imaging}}, journal = {NeuroImage}, @@ -1445,6 +1487,18 @@ @article{Tuch2004 url = {https://doi.org/10.1002/mrm.20279} } +@article{Veraart2016c, + author = {Jelle Veraart and Dmitry S. Novikov and Daan Christiaens and Benjamin Ades-aron and Jan Sijbers and Els Fieremans}, + title = {{Denoising of diffusion MRI using random matrix theory}}, + journal = {NeuroImage}, + volume = {142}, + pages = {394--406}, + year = {2016}, + month = {November}, + doi = {10.1016/j.neuroimage.2016.08.016}, + url = {https://doi.org/10.1016/j.neuroimage.2016.08.016} +} + @article{Veraart2016b, author = {Jelle Veraart and Els Fieremans and Dmitry S. Novikov}, title = {{Diffusion MRI noise mapping using random matrix theory}}, @@ -1459,15 +1513,16 @@ @article{Veraart2016b } @article{Veraart2016a, - author = {Jelle Veraart and Dmitry S. Novikov and Daan Christiaens and Benjamin Ades-aron and Jan Sijbers and Els Fieremans}, - title = {{Denoising of diffusion MRI using random matrix theory}}, - journal = {NeuroImage}, - volume = {142}, - pages = {394--406}, + author = {Jelle Veraart and Els Fieremans and Ileana O. Jelescu and Florian Knoll and Dmitry S. Novikov}, + title = {{Gibbs ringing in diffusion MRI}}, + journal = {Magnetic Resonance in Medicine}, + volume = {76}, + number = {1}, + pages = {301-314}, year = {2016}, - month = {November}, - doi = {10.1016/j.neuroimage.2016.08.016}, - url = {https://doi.org/10.1016/j.neuroimage.2016.08.016} + month = {July}, + doi = {10.1002/mrm.25866}, + url = {https://doi.org/10.1002/mrm.25866} } @article{Veraart2013, @@ -1517,6 +1572,18 @@ @article{Westin2016 url = {https://doi.org/10.1016/j.neuroimage.2016.02.039} } +@article{Wichmann2006, + author = {Brian A. Wichmann and Ian David Hill}, + title = {{Generating good pseudo-random numbers}}, + journal = {Computational Statistics \& Data Analysis}, + volume = {51}, + number = {3}, + pages = {1614-1622}, + year = {2006}, + doi = {10.1016/j.csda.2006.05.019}, + url = {https://doi.org/10.1016/j.csda.2006.05.019} +} + @article{Wu2008, author = {Yu-Chien Wu and Aaron S. Field and Andrew L. Alexander}, title = {{Computation of Diffusion Function Measures in $q$-Space Using Magnetic Resonance Hybrid Diffusion Imaging}}, @@ -1594,7 +1661,7 @@ @article{Zou2005 @incollection{Topgaard2016, author = {Daniel Topgaard}, title = {{NMR Methods for Studying Microscopic Diffusion Anisotropy}}, - booktitle = {{Diffusion NMR of Confined Systems: Fluid Transport in Porous Solids and Heterogeneous Materials}}, + booktitle = {Diffusion NMR of Confined Systems: Fluid Transport in Porous Solids and Heterogeneous Materials}, publisher = {The Royal Society of Chemistry}, year = {2016}, month = {December}, @@ -1615,7 +1682,7 @@ @inproceedings{Aganj2009 doi = {10.1109/ISBI.2009.5193327} } -@inproceedings{Arce-Santana2014, +@inproceedings{ArceSantana2014, author = {Edgar Arce-Santana and Daniel U. Campos-Delgado and Flavio Vigueras-G{\'o}mez and Isnardo Reducindo and Aldo R. Mej{\'i}a-Rodr{\'i}guez}, title = {{Non-rigid Multimodal Image Registration Based on the Expectation-Maximization Algorithm}}, editor = {Reinhard Klette and Mariano Rivera and Shin'ichi Satoh}, @@ -1641,13 +1708,13 @@ @inproceedings{Bruhn2005 @inproceedings{Cheng2011, author = {Jian Cheng and Tianzi Jiang and Rachid Deriche}, title = {{Theoretical Analysis and Practical Insights on EAP Estimation via a Unified HARDI Framework}}, - booktitle = {{MICCAI Workshop on Computational Diffusion MRI (CDMRI)}}, + booktitle = {MICCAI Workshop on Computational Diffusion MRI (CDMRI)}, address = {Toronto, Canada}, year = {2011}, month = {September} } -@inproceedings{Correia2011, +@inproceedings{Correia2011a, author = {Marta Morgado Correia and Guy B. Williams and Frank Yeh and Ian Nimmo-Smith and Eleftherios Garyfallidis}, title = {{Robustness of Diffusion Scalar Metrics When Estimated with Generalized Q-Sampling Imaging Acquisition Schemes}}, booktitle = {ISMRM 19th Annual Meeting \& Exhibition SMRT 20th Annual Meeting}, @@ -1655,11 +1722,12 @@ @inproceedings{Correia2011 address = {Montr\'{e}al, Canada}, volume = {}, pages = {}, - year = {2011} + year = {2011}, + month = {May} } -@inproceedings{Dell'Acqua2014, - author = {Flavio Dell'Acqua and Luis Lacerda and Marco Catani and and Andrew Simmons}, +@inproceedings{DellAcqua2014, + author = {Flavio Dell'Acqua and Luis Lacerda and Marco Catani and Andrew Simmons}, title = {{Anisotropic Power Maps: A diffusion contrast to reveal low anisotropy tissues from HARDI data}}, booktitle = {Joint Annual Meeting ISMRM-ESMRMB 2014 SMRT 23rd Annual Meeting}, organization = {International Society for Magnetic Resonance in Medicine (ISMRM)}, @@ -1676,10 +1744,10 @@ @inproceedings{Descoteaux2008a editor = {Dimitris Metaxas and Leon Axel and Gabor Fichtinger and G{\'a}bor Sz{\'e}kely}, publisher = {Springer Berlin Heidelberg}, address = {Berlin, Heidelberg}, - year = {2008}, volume = {11}, number = {Pt 2}, pages = {122--130}, + year = {2008}, doi = {10.1007/978-3-540-85990-1_15}, isbn = {978-3-540-85990-1} } @@ -1706,6 +1774,18 @@ @inproceedings{Fadnavis2020 url = {https://proceedings.neurips.cc/paper_files/paper/2020/file/bc047286b224b7bfa73d4cb02de1238d-Paper.pdf}, } +@inproceedings{Fick2016a, + author = {Rutger H. J. Fick and MArco Pizzolato and Demian Wassermann and Mauro Zucchelli and Gloria Menegaz and Rachid Deriche}, + title = {{A sensitivity analysis of q-space indices with respect to changes in axonal diameter, dispersion and tissue composition}}, + booktitle = {IEEE 13th International Symposium on Biomedical Imaging (ISBI)}, + volume = {}, + number = {}, + pages = {1241-1244}, + year = {2016}, + month = {April}, + doi = {10.1109/ISBI.2016.7493491} +} + @inproceedings{Fick2015, author = {Rutger Fick and Demian Wassermann and Marco Pizzolato and Rachid Deriche}, editor = {Sebastien Ourselin and Daniel C. Alexander and Carl-Fredrik Westin and M. Jorge Cardoso}, @@ -1772,7 +1852,7 @@ @inproceedings{Garyfallidis2010 } @inproceedings{Houde2015, - author = {Jean-Christophe Houde and Marc-Alexandre Ct-Harnois and and Maxime Descoteaux}, + author = {Jean-Christophe Houde and Marc-Alexandre Ct-Harnois and Maxime Descoteaux}, title = {{How to Avoid Biased Streamlines-Based Metrics for Streamlines with Variable Step Sizes}}, booktitle = {ISMRM 23rd Annual Meeting \& Exhibition SMRT 24th Annual Meeting}, organization = {International Society for Magnetic Resonance in Medicine (ISMRM)}, @@ -1788,12 +1868,24 @@ @inproceedings{Lee2008 booktitle = {2008 5th IEEE International Symposium on Biomedical Imaging: From Nano to Macro}, volume = {}, pages = {943-946}, - month = {May}, year = {2008}, + month = {May}, doi = {10.1109/ISBI.2008.4541153} } -@inproceedings{Meesters2016, +@inproceedings{Meesters2016b, + author = {Stephan Meesters and Gonzalo Sanguinetti and Eleftherios Garyfallidis and Jorg Portegies and Pauly Ossenblok and Remco Duits1}, + title = {{Cleaning output of tractography via fiber to bundle coherence, a new open source implementation}}, + booktitle = {The Organization for Human Brain Mapping Annual Meeting}, + organization = {Organization for Human Brain Mapping (OHBM)}, + address = {Geneva, Switzerland}, + volume = {}, + pages = {}, + year = {2016}, + month = {June} +} + +@inproceedings{Meesters2016a, author = {Stephan Meesters and Gonzalo Sanguinetti and Eleftherios Garyfallidis and Jorg Portegies and Remco Duits1}, title = {{Fast implementations of contextual PDE’s for HARDI data processing in DIPY}}, booktitle = {ISMRM 24th Annual Meeting \& Exhibition SMRT 25th Annual Meeting}, @@ -1801,7 +1893,8 @@ @inproceedings{Meesters2016 address = {Singapore}, volume = {}, pages = {}, - year = {2016} + year = {2016}, + month = {May} } @inproceedings{Nath2018 @@ -1823,7 +1916,18 @@ @inproceedings{Niethammer2006 pages = {2622-2625}, year = {2006}, doi = {10.1109/IEMBS.2006.259826} - } +} + +@inproceedings{Ozarslan2009, + author = {Evren {\"O}zarslan and Cheng Guan Koay and Timothy M. Shepherd and Stephen J. Blackband and Peter J. Basser}, + title = {{Simple harmonic oscillator based reconstruction and estimation for three-dimensional q-space MRI}}, + booktitle = {ISMRM 17th Scientific Meeting \& Exhibition SMRT 18th Annual Meeting}, + organization = {International Society for Magnetic Resonance in Medicine (ISMRM)}, + address = {Honolulu, HI, USA}, + volume = {}, + pages = {}, + year = {2009} +} @inproceedings{Ozarslan2008, author = {Evren {\"O}zarslan and Cheng Guan Koay and Peter J. Basser}, @@ -1840,7 +1944,7 @@ @inproceedings{Portegies2015a author = {Jorg Portegies and Gonzalo Sanguinetti and Stephan Meesters and Remco Duits}, editor = {Jean-Fran{\c{c}}ois Aujol and Mila Nikolova and Nicolas Papadakis}, title = {{New Approximation of a Scale Space Kernel on SE(3) and Applications in Neuroimaging}}, - booktitle = {Scale Space and Variational Methods in Computer Vision}, + booktitle = {5th International Conference on Scale Space and Variational Methods in Computer Vision}, publisher = {Springer International Publishing}, address = {Cham}, pages = {40--52}, @@ -1861,7 +1965,7 @@ @inproceedings{Rathi2011 } @inproceedings{Rheault2015, - author = {Fran\c{c}ois Rheault and Jean-Christophe Houde and and Maxime Descoteaux}, + author = {Fran\c{c}ois Rheault and Jean-Christophe Houde and Maxime Descoteaux}, title = {{Real Time Interaction with Millions of Streamlines}}, booktitle = {ISMRM 23rd Annual Meeting \& Exhibition SMRT 24th Annual Meeting}, organization = {International Society for Magnetic Resonance in Medicine (ISMRM)}, @@ -1882,7 +1986,7 @@ @inproceedings{Rokem2014 year = {2014} } -@inproceedings{Romero-Bascones2022, +@inproceedings{RomeroBascones2022, author = {David Romero-Bascones and Bramsh Qamar Chandio and Shreyas Fadnavis and Jong Sung Park and Serge Koudoro and Unai Ayala and Maitane Barrenechea and Eleftherios Garyfallidis}, title = {{BundleAtlasing: unbiased population-specific atlasing of bundles in streamline space}}, booktitle = {Joint Annual Meeting ISMRM-ESMRMB \& ISMRT 31st Annual Meeting}, @@ -1946,7 +2050,7 @@ @misc{NetoHenriques2017 } @misc{Wassermann2017, - author = {Demian Wassermann and Mathieu Santin and Anne-Charlotte Philippe and Rutger Fick and Rachid Deriche and Stephane Lehericy and and Alexandra Petiet}, + author = {Demian Wassermann and Mathieu Santin and Anne-Charlotte Philippe and Rutger Fick and Rachid Deriche and Stephane Lehericy and Alexandra Petiet}, title = {{Test-Retest qt-dMRI datasets for Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time}}, howpublished = {Zenodo}, year = {2017}, @@ -1957,6 +2061,17 @@ @misc{Wassermann2017 } %% phdthesis +@phdthesis{Amirbekian2016, + author = {Bagrat Amirbekian}, + title = {{The Modeling of White Matter Architecture and Networks Using Diffusion MRI: Methods, Tools and Applications}}, + type = {PhD thesis}, + school = {University of California San Francisco}, + address = {San Francisco, CA, USA}, + year = {2016}, + doi = {}, + url = {} +} + @phdthesis{Cheng2012, author = {Jian Cheng}, title = {{Estimation and Processing of Ensemble Average Propagator and Its Features in Diffusion MRI}}, @@ -1976,7 +2091,7 @@ @phdthesis{Descoteaux2008b address = {Valbonne, France}, year = {2007}, doi = {}, - url = {} + url = {https://theses.hal.science/tel-00457458} } @phdthesis{Garyfallidis2012b, @@ -1987,7 +2102,7 @@ @phdthesis{Garyfallidis2012b address = {Cambridge, United Kingdom}, year = {2012}, doi = {}, - url = {https://theses.hal.science/tel-00457458} + url = {} } @phdthesis{NetoHenriques2018, From 872d8b7c7dd7140e59e8a3f3169ee457b5552c5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Thu, 15 Aug 2024 01:14:03 -0400 Subject: [PATCH 2/2] DOC: Cite code base references using `sphinxcontrib-bibtex` Cite references across the code base using `sphinxcontrib-bibtex`. This also fixes references that were under wrong sections (e.g. `Notes`), references that were inaccurate, and adds them where they were missing. Make the cross-references dwell in the long description (i.e. in a separate paragraph) in cases where they were in the short description to avoid some known issues with `numpydoc` that prevent the references from being processed correctly if they dwell in this short description: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#unknown-target-name-when-using-footnote-citations-with-numpydoc Uncomment the `numpydoc` extension for the Sphinx configuration: allow to take advantage of its documentation validation features. --- dipy/align/bundlemin.pyx | 17 +- dipy/align/crosscorr.pyx | 75 +--- dipy/align/expectmax.pyx | 48 +- dipy/align/imaffine.py | 16 +- dipy/align/metrics.py | 31 +- dipy/align/parzenhist.pyx | 29 +- dipy/align/streamlinear.py | 60 +-- dipy/align/streamwarp.py | 11 +- dipy/align/sumsqdiff.pyx | 54 +-- dipy/core/geometry.py | 9 +- dipy/core/gradients.py | 20 +- dipy/core/onetime.py | 4 +- dipy/core/optimize.py | 11 +- dipy/core/rng.py | 15 +- dipy/core/sphere.py | 41 +- dipy/data/__init__.py | 9 +- dipy/data/fetcher.py | 58 ++- dipy/denoise/adaptive_soft_matching.py | 8 +- dipy/denoise/enhancement_kernel.pyx | 22 +- dipy/denoise/gibbs.py | 29 +- dipy/denoise/localpca.py | 66 +-- dipy/denoise/nlmeans.py | 9 +- dipy/denoise/nlmeans_block.pyx | 14 +- dipy/denoise/noise_estimate.py | 65 ++- dipy/denoise/non_local_means.py | 18 +- dipy/denoise/patch2self.py | 6 +- dipy/denoise/pca_noise_estimate.pyx | 19 +- dipy/denoise/shift_twist_convolution.pyx | 22 +- dipy/direction/peaks.py | 13 +- dipy/direction/ptt_direction_getter.pyx | 10 +- dipy/reconst/cross_validation.py | 6 +- dipy/reconst/csdeconv.py | 175 ++++---- dipy/reconst/cti.py | 13 +- dipy/reconst/dki.py | 502 +++++++++------------ dipy/reconst/dki_micro.py | 128 +++--- dipy/reconst/dsi.py | 57 +-- dipy/reconst/dti.py | 202 ++++----- dipy/reconst/forecast.py | 39 +- dipy/reconst/fwdti.py | 76 ++-- dipy/reconst/gqi.py | 33 +- dipy/reconst/ivim.py | 59 +-- dipy/reconst/mapmri.py | 545 ++++++++++------------- dipy/reconst/mcsd.py | 26 +- dipy/reconst/msdki.py | 141 +++--- dipy/reconst/odf.py | 10 +- dipy/reconst/qtdmri.py | 347 ++++++--------- dipy/reconst/qti.py | 36 +- dipy/reconst/rumba.py | 111 ++--- dipy/reconst/sfm.py | 55 +-- dipy/reconst/shm.py | 256 ++++------- dipy/reconst/shore.py | 103 ++--- dipy/reconst/tests/test_ivim.py | 6 +- dipy/segment/bundles.py | 57 +-- dipy/segment/clustering.py | 54 +-- dipy/segment/clustering_algorithms.pyx | 20 +- dipy/segment/fss.py | 13 +- dipy/segment/metric.py | 10 +- dipy/sims/phantom.py | 12 +- dipy/sims/voxel.py | 115 +++-- dipy/stats/analysis.py | 15 +- dipy/stats/qc.py | 9 +- dipy/stats/resampling.py | 24 +- dipy/tracking/fbcmeasures.pyx | 13 +- dipy/tracking/life.py | 17 +- dipy/tracking/local_tracking.py | 8 +- dipy/tracking/stopping_criterion.pyx | 25 +- dipy/tracking/streamline.py | 12 +- dipy/tracking/streamlinespeed.pyx | 35 +- dipy/tracking/utils.py | 18 +- dipy/viz/horizon/app.py | 19 +- dipy/workflows/align.py | 23 +- dipy/workflows/denoise.py | 78 ++-- dipy/workflows/nn.py | 4 +- dipy/workflows/reconst.py | 116 ++--- dipy/workflows/segment.py | 19 +- dipy/workflows/stats.py | 24 +- dipy/workflows/tracking.py | 14 +- dipy/workflows/viz.py | 10 +- doc/conf.py | 2 +- 79 files changed, 1828 insertions(+), 2673 deletions(-) diff --git a/dipy/align/bundlemin.pyx b/dipy/align/bundlemin.pyx index e027f0c7ad..86dd943e3a 100644 --- a/dipy/align/bundlemin.pyx +++ b/dipy/align/bundlemin.pyx @@ -22,8 +22,10 @@ cdef cnp.dtype f64_dt = np.dtype(np.float64) cdef double min_direct_flip_dist(double *a,double *b, cnp.npy_intp rows) noexcept nogil: - r""" Minimum of direct and flip average (MDF) distance [Garyfallidis12] - between two streamlines. + r""" Minimum of direct and flip average (MDF) distance between two + streamlines. + + See :footcite:p:`Garyfallidis2012a` for a definition of the distance. Parameters ---------- @@ -41,9 +43,7 @@ cdef double min_direct_flip_dist(double *a,double *b, References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ cdef: @@ -275,14 +275,11 @@ def _bundle_minimum_distance_asymmetric(double [:, ::1] static, distance metric. This means that we are weighting only one direction of the registration. Not both directions. This can be very useful when we want to register a big set of bundles to a small set of bundles. - See [Wanyan17]_. + See :footcite:p:`Wanyan2017`. References ---------- - .. [Wanyan17] Wanyan and Garyfallidis, Important new insights for the - reduction of false positives in tractograms emerge from streamline-based - registration and pruning, International Society for Magnetic Resonance in - Medicine, Honolulu, Hawai, 2017. + .. footbibliography:: """ diff --git a/dipy/align/crosscorr.pyx b/dipy/align/crosscorr.pyx index 4870d4adfd..9e489c4d41 100644 --- a/dipy/align/crosscorr.pyx +++ b/dipy/align/crosscorr.pyx @@ -136,7 +136,8 @@ def precompute_cc_factors_3d(floating[:, :, :] static, Pre-computes the separate terms of the cross correlation metric and image norms at each voxel considering a neighborhood of the given radius to efficiently compute the gradient of the metric with respect to the - deformation field [Ocegueda2016]_ [Avants2008]_ [Avants2011]_. + deformation field :footcite:p:`Ocegueda2016`, :footcite:p:`Avants2008`, + :footcite:p:`Avants2009`. Parameters ---------- @@ -160,16 +161,7 @@ def precompute_cc_factors_3d(floating[:, :, :] static, References ---------- - .. [Ocegueda2016]_ Ocegueda, O., Dalmau, O., Garyfallidis, E., Descoteaux, - M., & Rivera, M. (2016). On the computation of integrals over - fixed-size rectangles of arbitrary dimension, Pattern Recognition - Letters. doi:10.1016/j.patrec.2016.05.008 - .. [Avants2008]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. - (2008). Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - .. [Avants2011]_ Avants, B. B., Tustison, N., & Song, G. (2011). Advanced - Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ cdef: cnp.npy_intp ns = static.shape[0] @@ -358,8 +350,9 @@ def compute_cc_forward_step_3d(floating[:, :, :, :] grad_static, r"""Gradient of the CC Metric w.r.t. the forward transformation Computes the gradient of the Cross Correlation metric for symmetric - registration (SyN) [Avants2008]_ w.r.t. the displacement associated to - the moving volume ('forward' step) as in [Avants2011]_ + registration (SyN) :footcite:p:`Avants2008` w.r.t. the displacement + associated to the moving volume ('forward' step) as in + :footcite:t:`Avants2009`. Parameters ---------- @@ -382,12 +375,7 @@ def compute_cc_forward_step_3d(floating[:, :, :, :] grad_static, References ---------- - .. [Avants2008]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. - (2008). Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - .. [Avants2011]_ Avants, B. B., Tustison, N., & Song, G. (2011). Advanced - Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ cdef: cnp.npy_intp ns = grad_static.shape[0] @@ -430,8 +418,9 @@ def compute_cc_backward_step_3d(floating[:, :, :, :] grad_moving, r"""Gradient of the CC Metric w.r.t. the backward transformation Computes the gradient of the Cross Correlation metric for symmetric - registration (SyN) [Avants08]_ w.r.t. the displacement associated to - the static volume ('backward' step) as in [Avants11]_ + registration (SyN) :footcite:p:`Avants2008`. w.r.t. the displacement + associated to the static volume ('backward' step) as in + :footcite:t:`Avants2009`. Parameters ---------- @@ -454,12 +443,7 @@ def compute_cc_backward_step_3d(floating[:, :, :, :] grad_moving, References ---------- - [Avants08]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. (2008) - Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - [Avants11]_ Avants, B. B., Tustison, N., & Song, G. (2011). - Advanced Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ ftype = np.asarray(grad_moving).dtype cdef: @@ -503,9 +487,9 @@ def precompute_cc_factors_2d(floating[:, :] static, floating[:, :] moving, r"""Precomputations to quickly compute the gradient of the CC Metric Pre-computes the separate terms of the cross correlation metric - [Avants2008]_ and image norms at each voxel considering a neighborhood of - the given radius to efficiently [Avants2011]_ compute the gradient of the - metric with respect to the deformation field. + :footcite:p:`Avants2008` and image norms at each voxel considering a + neighborhood of the given radius to efficiently compute the gradient of the + metric with respect to the deformation field :footcite:p:`Avants2009`. Parameters ---------- @@ -529,12 +513,7 @@ def precompute_cc_factors_2d(floating[:, :] static, floating[:, :] moving, References ---------- - .. [Avants2008]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. - (2008). Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - .. [Avants2011]_ Avants, B. B., Tustison, N., & Song, G. (2011). Advanced - Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ ftype = np.asarray(static).dtype cdef: @@ -677,8 +656,9 @@ def compute_cc_forward_step_2d(floating[:, :, :] grad_static, r"""Gradient of the CC Metric w.r.t. the forward transformation Computes the gradient of the Cross Correlation metric for symmetric - registration (SyN) [Avants2008]_ w.r.t. the displacement associated to - the moving image ('backward' step) as in [Avants2011]_ + registration (SyN) :footcite:p:`Avants2008` w.r.t. the displacement + associated to the moving image ('backward' step) as in + :footcite:t:`Avants2009`. Parameters ---------- @@ -704,12 +684,7 @@ def compute_cc_forward_step_2d(floating[:, :, :] grad_static, References ---------- - .. [Avants2008]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. - (2008). Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - .. [Avants2011]_ Avants, B. B., Tustison, N., & Song, G. (2011). Advanced - Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ cdef: cnp.npy_intp nr = grad_static.shape[0] @@ -750,8 +725,9 @@ def compute_cc_backward_step_2d(floating[:, :, :] grad_moving, r"""Gradient of the CC Metric w.r.t. the backward transformation Computes the gradient of the Cross Correlation metric for symmetric - registration (SyN) [Avants2008]_ w.r.t. the displacement associated to - the static image ('forward' step) as in [Avants2011]_ + registration (SyN) :footcite:p:`Avants2008` w.r.t. the displacement + associated to the static image ('forward' step) as in + :footcite:t:`Avants2009`. Parameters ---------- @@ -770,12 +746,7 @@ def compute_cc_backward_step_2d(floating[:, :, :] grad_moving, References ---------- - .. [Avants2008]_ Avants, B. B., Epstein, C. L., Grossman, M., & Gee, J. C. - (2008). Symmetric Diffeomorphic Image Registration with - Cross-Correlation: Evaluating Automated Labeling of Elderly and - Neurodegenerative Brain, Med Image Anal. 12(1), 26-41. - .. [Avants2011]_ Avants, B. B., Tustison, N., & Song, G. (2011). Advanced - Normalization Tools (ANTS), 1-35. + .. footbibliography:: """ ftype = np.asarray(grad_moving).dtype cdef: diff --git a/dipy/align/expectmax.pyx b/dipy/align/expectmax.pyx index 18dd228408..c9bc85d6cc 100644 --- a/dipy/align/expectmax.pyx +++ b/dipy/align/expectmax.pyx @@ -359,13 +359,14 @@ def compute_em_demons_step_2d(floating[:,:] delta_field, floating[:,:,:] out): r"""Demons step for EM metric in 2D - Computes the demons step [Vercauteren09] for SSD-driven registration - ( eq. 4 in [Vercauteren09] ) using the EM algorithm [Arce14] to handle - multi-modality images. + Computes the demons step :footcite:p:`Vercauteren2009` for SSD-driven + registration ( eq. 4 in :footcite:p:`Vercauteren2009` ) using the EM + algorithm :footcite:p:`ArceSantana2014` to handle multi-modality images. - In this case, $\sigma_i$ in eq. 4 of [Vercauteren] is estimated using the EM - algorithm, while in the original version of diffeomorphic demons it is - estimated by the difference between the image values at each pixel. + In this case, $\sigma_i$ in eq. 4 of :footcite:p:`Vercauteren2009` is + estimated using the EM algorithm, while in the original version of + diffeomorphic demons it is estimated by the difference between the image + values at each pixel. Parameters ---------- @@ -385,7 +386,7 @@ def compute_em_demons_step_2d(floating[:,:] delta_field, the gradient of the moving image sigma_sq_x : float parameter controlling the amount of regularization. It corresponds to - $\sigma_x^2$ in algorithm 1 of Vercauteren et al.[2] + $\sigma_x^2$ in algorithm 1 of :footcite:p:`Vercauteren2009` out : array, shape (R, C, 2) the resulting demons step will be written to this array @@ -399,14 +400,7 @@ def compute_em_demons_step_2d(floating[:,:] delta_field, References ---------- - [Arce14] Arce-santana, E., Campos-delgado, D. U., & Vigueras-g, F. (2014). - Non-rigid Multimodal Image Registration Based on the - Expectation-Maximization Algorithm, (168140), 36-47. - - [Vercauteren09] Vercauteren, T., Pennec, X., Perchant, A., & Ayache, N. - (2009). Diffeomorphic demons: efficient non-parametric - image registration. NeuroImage, 45(1 Suppl), S61-72. - doi:10.1016/j.neuroimage.2008.10.040 + .. footbibliography:: """ cdef: cnp.npy_intp nr = delta_field.shape[0] @@ -455,13 +449,14 @@ def compute_em_demons_step_3d(floating[:,:,:] delta_field, floating[:,:,:,:] out): r"""Demons step for EM metric in 3D - Computes the demons step [Vercauteren09] for SSD-driven registration - ( eq. 4 in [Vercauteren09] ) using the EM algorithm [Arce14] to handle - multi-modality images. + Computes the demons step :footcite:p:`Vercauteren2009` for SSD-driven + registration ( eq. 4 in :footcite:p:`Vercauteren2009` ) using the EM + algorithm :footcite:p:`ArceSantana2014` to handle multi-modality images. - In this case, $\sigma_i$ in eq. 4 of [Vercauteren09] is estimated using - the EM algorithm, while in the original version of diffeomorphic demons - it is estimated by the difference between the image values at each pixel. + In this case, $\sigma_i$ in eq. 4 of :footcite:p:`Vercauteren2009` is + estimated using the EM algorithm, while in the original version of + diffeomorphic demons it is estimated by the difference between the image + values at each pixel. Parameters ---------- @@ -481,7 +476,7 @@ def compute_em_demons_step_3d(floating[:,:,:] delta_field, the gradient of the moving image sigma_sq_x : float parameter controlling the amount of regularization. It corresponds to - $\sigma_x^2$ in algorithm 1 of Vercauteren et al.[2]. + $\sigma_x^2$ in algorithm 1 of footcite:p:`Vercauteren2009`. out : array, shape (S, R, C, 2) the resulting demons step will be written to this array @@ -495,14 +490,7 @@ def compute_em_demons_step_3d(floating[:,:,:] delta_field, References ---------- - [Arce14] Arce-santana, E., Campos-delgado, D. U., & Vigueras-g, F. (2014). - Non-rigid Multimodal Image Registration Based on the - Expectation-Maximization Algorithm, (168140), 36-47. - - [Vercauteren09] Vercauteren, T., Pennec, X., Perchant, A., & Ayache, N. - (2009). Diffeomorphic demons: efficient non-parametric - image registration. NeuroImage, 45(1 Suppl), S61-72. - doi:10.1016/j.neuroimage.2008.10.040 + .. footbibliography:: """ cdef: cnp.npy_intp ns = delta_field.shape[0] diff --git a/dipy/align/imaffine.py b/dipy/align/imaffine.py index 460df3deb0..8a02d9badb 100644 --- a/dipy/align/imaffine.py +++ b/dipy/align/imaffine.py @@ -12,10 +12,10 @@ mapping points in the codomain to points in the domain. ParzenJointHistogram: computes the marginal and joint distributions of - intensities of a pair of images, using Parzen windows [Parzen62] - with a cubic spline kernel, as proposed by Mattes et al. [Mattes03]. - It also computes the gradient of the joint histogram w.r.t. the - parameters of a given transform. + intensities of a pair of images, using Parzen windows + :footcite:p:`Parzen1962` with a cubic spline kernel, as proposed by + :footcite:t:`Mattes2003`. It also computes the gradient of the joint + histogram w.r.t. the parameters of a given transform. MutualInformationMetric: computes the value and gradient of the mutual information metric the way `Optimizer` needs them. That is, given @@ -33,13 +33,7 @@ References ---------- -[Parzen62] E. Parzen. On the estimation of a probability density - function and the mode. Annals of Mathematical Statistics, - 33(3), 1065-1076, 1962. -[Mattes03] Mattes, D., Haynor, D. R., Vesselle, H., Lewellen, T. K., - & Eubank, W. PET-CT image registration in the chest using - free-form deformations. IEEE Transactions on Medical - Imaging, 22(1), 120-8, 2003. +.. footbibliography:: """ diff --git a/dipy/align/metrics.py b/dipy/align/metrics.py index 959a2d3956..421b986ea7 100644 --- a/dipy/align/metrics.py +++ b/dipy/align/metrics.py @@ -541,7 +541,7 @@ def compute_gauss_newton_step(self, *, forward_step=True): regularized displacement field (this step does not require post-smoothing, as opposed to the demons step, which does not include regularization). To accelerate convergence we use the multi-grid - Gauss-Seidel algorithm proposed by Bruhn and Weickert et al [Bruhn05] + Gauss-Seidel algorithm proposed by :footcite:t:`Bruhn2005`. Parameters ---------- @@ -558,10 +558,7 @@ def compute_gauss_newton_step(self, *, forward_step=True): References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ reference_shape = self.static_image.shape @@ -866,8 +863,8 @@ def compute_gauss_newton_step(self, *, forward_step=True): def compute_demons_step(self, *, forward_step=True): r"""Demons step for SSD metric - Computes the demons step proposed by Vercauteren et al.[Vercauteren09] - for the SSD metric. + Computes the demons step proposed by :footcite:t:`Vercauteren2009` for + the SSD metric. Parameters ---------- @@ -884,9 +881,7 @@ def compute_demons_step(self, *, forward_step=True): References ---------- - [Vercauteren09] Tom Vercauteren, Xavier Pennec, Aymeric Perchant, - Nicholas Ayache, "Diffeomorphic Demons: Efficient - Non-parametric Image Registration", Neuroimage 2009 + .. footbibliography:: """ sigma_reg_2 = np.sum(self.static_spacing**2) / self.dim @@ -943,7 +938,7 @@ def v_cycle_2d( by first filtering (GS-iterate) the current level, then solves for the residual at a coarser resolution and finally refines the solution at the current resolution. This scheme corresponds to the V-cycle proposed by - Bruhn and Weickert[Bruhn05]. + :footcite:t:`Bruhn2005`. Parameters ---------- @@ -977,10 +972,7 @@ def v_cycle_2d( References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining the highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ # pre-smoothing for _ in range(k): @@ -1069,8 +1061,8 @@ def v_cycle_3d( Multi-resolution Gauss-Seidel solver: solves the linear system by first filtering (GS-iterate) the current level, then solves for the residual at a coarser resolution and finally refines the solution at the current - resolution. This scheme corresponds to the V-cycle proposed by Bruhn and - Weickert [1]_. + resolution. This scheme corresponds to the V-cycle proposed by + :footcite:t:`Bruhn2005`. Parameters ---------- @@ -1104,10 +1096,7 @@ def v_cycle_3d( References ---------- - .. [1] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time performance", - 10th IEEE International Conference on Computer Vision, 2005. - ICCV 2005. + .. footbibliography:: """ # pre-smoothing for _ in range(k): diff --git a/dipy/align/parzenhist.pyx b/dipy/align/parzenhist.pyx index bdddf0f763..c66e3a2a69 100644 --- a/dipy/align/parzenhist.pyx +++ b/dipy/align/parzenhist.pyx @@ -26,12 +26,13 @@ cdef extern from "dpy_math.h" nogil: class ParzenJointHistogram: def __init__(self, nbins): r""" Computes joint histogram and derivatives with Parzen windows + :footcite:p:`Parzen1962`. Base class to compute joint and marginal probability density functions and their derivatives with respect to a transform's parameters. The smooth histograms are computed by using Parzen - windows [Parzen62] with a cubic spline kernel, as proposed by - Mattes et al. [Mattes03]. This implementation is not tied to any + windows :footcite:p:`Parzen1962` with a cubic spline kernel, as proposed + by :footcite:t:`Mattes2003`. This implementation is not tied to any optimization (registration) method, the idea is that information-theoretic matching functionals (such as Mutual Information) can inherit from this class to perform the low-level @@ -48,13 +49,7 @@ class ParzenJointHistogram: References ---------- - [Parzen62] E. Parzen. On the estimation of a probability density - function and the mode. Annals of Mathematical Statistics, - 33(3), 1065-1076, 1962. - [Mattes03] Mattes, D., Haynor, D. R., Vesselle, H., Lewellen, T. K., - & Eubank, W. PET-CT image registration in the chest using - free-form deformations. IEEE Transactions on Medical - Imaging, 22(1), 120-8, 2003. + .. footbibliography:: Notes ----- @@ -523,14 +518,12 @@ def cubic_spline(double[:] x): cdef inline double _cubic_spline(double x) nogil: r""" Cubic B-Spline evaluated at x - See eq. (3) of [Matttes03]. + + See eq. (3) of :footcite:t:`Mattes2003`. References ---------- - [Mattes03] Mattes, D., Haynor, D. R., Vesselle, H., Lewellen, T. K., - & Eubank, W. PET-CT image registration in the chest using - free-form deformations. IEEE Transactions on Medical Imaging, - 22(1), 120-8, 2003. + .. footbibliography:: """ cdef: double absx = -x if x < 0.0 else x @@ -563,14 +556,12 @@ def cubic_spline_derivative(double[:] x): cdef inline double _cubic_spline_derivative(double x) nogil: r""" Derivative of cubic B-Spline evaluated at x - See eq. (3) of [Mattes03]. + + See eq. (3) of :footcite:t:`Mattes2003`. References ---------- - [Mattes03] Mattes, D., Haynor, D. R., Vesselle, H., Lewellen, T. K., - & Eubank, W. PET-CT image registration in the chest using - free-form deformations. IEEE Transactions on Medical Imaging, - 22(1), 120-8, 2003. + .. footbibliography:: """ cdef: double absx = -x if x < 0.0 else x diff --git a/dipy/align/streamlinear.py b/dipy/align/streamlinear.py index 37f0897b58..99ea1c0366 100644 --- a/dipy/align/streamlinear.py +++ b/dipy/align/streamlinear.py @@ -76,10 +76,12 @@ def distance(self, xopt): class BundleMinDistanceMetric(StreamlineDistanceMetric): - """Bundle-based Minimum Distance aka BMD + """Bundle-based Minimum Distance aka BMD. This is the cost function used by the StreamlineLinearRegistration. + See :footcite:p:`Garyfallidis2014` for further details about the metric. + Methods ------- setup(static, moving) @@ -87,9 +89,7 @@ class BundleMinDistanceMetric(StreamlineDistanceMetric): References ---------- - .. [Garyfallidis14] Garyfallidis et al., "Direct native-space fiber - bundle alignment for group comparisons", ISMRM, - 2014. + .. footbibliography:: """ def setup(self, static, moving): @@ -315,7 +315,9 @@ def __init__( evolution=False, num_threads=None, ): - r"""Linear registration of 2 sets of streamlines [Garyfallidis15]_. + r"""Linear registration of 2 sets of streamlines. + + See :footcite:p:`Garyfallidis2015` for further details about the method. Parameters ---------- @@ -389,16 +391,7 @@ def __init__( References ---------- - .. [Garyfallidis15] Garyfallidis et al. "Robust and efficient linear - registration of white-matter fascicles in the space of streamlines", - NeuroImage, 117, 124--140, 2015 - - .. [Garyfallidis14] Garyfallidis et al., "Direct native-space fiber - bundle alignment for group comparisons", ISMRM, 2014. - - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based - registration and clustering, Neuroimage, 2017. + .. footbibliography:: """ self.x0 = self._set_x0(x0) @@ -914,8 +907,8 @@ def progressive_slr( This is a utility function that allows for example to do affine registration using Streamline-based Linear Registration (SLR) - [Garyfallidis15]_ by starting with translation first, then rigid, - then similarity, scaling and finally affine. + :footcite:p:`Garyfallidis2015` by starting with translation first, + then rigid, then similarity, scaling and finally affine. Similarly, if for example, you want to perform rigid then you start with translation first. This progressive strategy can help with finding the @@ -949,9 +942,7 @@ def progressive_slr( References ---------- - .. [Garyfallidis15] Garyfallidis et al. "Robust and efficient linear - registration of white-matter fascicles in the space of streamlines", - NeuroImage, 117, 124--140, 2015 + .. footbibliography:: """ if verbose: @@ -1054,6 +1045,9 @@ def slr_with_qbx( For efficiency, we apply the registration on cluster centroids and remove small clusters. + See :footcite:p:`Garyfallidis2014`, :footcite:p:`Garyfallidis2015` and + :footcite:p:`Garyfallidis2018` for details about the methods involved. + Parameters ---------- static : Streamlines @@ -1107,18 +1101,12 @@ def slr_with_qbx( ----- The order of operations is the following. First short or long streamlines are removed. Second, the tractogram or a random selection of the tractogram - is clustered with QuickBundles. Then SLR [Garyfallidis15]_ is applied. + is clustered with QuickBundles. Then SLR :footcite:p:`Garyfallidis2015` is + applied. References ---------- - .. [Garyfallidis15] Garyfallidis et al. "Robust and efficient linear - registration of white-matter fascicles in the space of streamlines", - NeuroImage, 117, 124--140, 2015 - .. [Garyfallidis14] Garyfallidis et al., "Direct native-space fiber - bundle alignment for group comparisons", ISMRM, 2014. - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. + .. footbibliography:: """ if rng is None: @@ -1231,13 +1219,16 @@ def groupwise_slr( verbose=False, rng=None, ): - """Function to perform unbiased groupwise bundle registration. + """Function to perform unbiased groupwise bundle registration All bundles are moved to the same space by iteratively applying halfway streamline linear registration in pairs. With each iteration, bundles get closer to each other until the procedure converges and there is no more improvement. + See :footcite:p:`Garyfallidis2014`, :footcite:p:`Garyfallidis2015` and + :footcite:p:`Garyfallidis2018`. + Parameters ---------- bundles : list @@ -1273,14 +1264,7 @@ def groupwise_slr( References ---------- - .. [Garyfallidis15] Garyfallidis et al. "Robust and efficient linear - registration of white-matter fascicles in the space of streamlines", - NeuroImage, 117, 124--140, 2015 - .. [Garyfallidis14] Garyfallidis et al., "Direct native-space fiber - bundle alignment for group comparisons", ISMRM, 2014. - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. + .. footbibliography:: """ diff --git a/dipy/align/streamwarp.py b/dipy/align/streamwarp.py index 2511903628..352be5f4fe 100755 --- a/dipy/align/streamwarp.py +++ b/dipy/align/streamwarp.py @@ -63,6 +63,8 @@ def bundlewarp( ): """Register two bundles using nonlinear method. + See :footcite:p:`Chandio2023` for further details about the method. + Parameters ---------- static : Streamlines @@ -109,8 +111,7 @@ def bundlewarp( References ---------- - .. [Chandio2023] Chandio et al. "BundleWarp, streamline-based nonlinear - registration of white matter tracts." bioRxiv (2023): 2023-01. + .. footbibliography:: """ if alpha <= 0.01: @@ -215,13 +216,11 @@ def bundlewarp_vector_filed(moving_aligned, deformed_bundle): Unitary vector directions colors : List Colors for bundle warping field vectors. Colors follow the convention - used in DTI-derived maps (e.g. color FA) [Pajevic1999]_. + used in DTI-derived maps (e.g. color FA) :footcite:p:`Pajevic1999`. References ---------- - .. [Pajevic1999] Pajevic S, Pierpaoli (1999). Color schemes to represent the - orientation of anisotropic tissues from diffusion tensor data: application - to white matter fiber tract mapping in the human brain. + .. footbibliography:: """ points_aligned, _ = unlist_streamlines(moving_aligned) points_deformed, _ = unlist_streamlines(deformed_bundle) diff --git a/dipy/align/sumsqdiff.pyx b/dipy/align/sumsqdiff.pyx index cfa82360c1..6ad1fb7809 100644 --- a/dipy/align/sumsqdiff.pyx +++ b/dipy/align/sumsqdiff.pyx @@ -167,7 +167,7 @@ cpdef double iterate_residual_displacement_field_ssd_2d( r"""One iteration of a large linear system solver for 2D SSD registration Performs one iteration at one level of the Multi-resolution Gauss-Seidel - solver proposed by Bruhn and Weickert [Bruhn05]. + solver proposed by :footcite:t:`Bruhn2005`. Parameters ---------- @@ -196,10 +196,7 @@ cpdef double iterate_residual_displacement_field_ssd_2d( References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ ftype = np.asarray(delta_field).dtype cdef: @@ -340,7 +337,7 @@ cpdef double iterate_residual_displacement_field_ssd_3d( r"""One iteration of a large linear system solver for 3D SSD registration Performs one iteration at one level of the Multi-resolution Gauss-Seidel - solver proposed by Bruhn and Weickert [Bruhn05]. + solver proposed by :footcite:t:`Bruhn2005`. Parameters ---------- @@ -369,10 +366,7 @@ cpdef double iterate_residual_displacement_field_ssd_3d( References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ ftype = np.asarray(delta_field).dtype cdef: @@ -540,7 +534,7 @@ def compute_residual_displacement_field_ssd_3d( Computes the residual displacement field corresponding to the current displacement field (given by 'disp') in the Multi-resolution - Gauss-Seidel solver proposed by Bruhn and Weickert [Bruhn]. + Gauss-Seidel solver proposed by :footcite:t:`Bruhn2005`. Parameters ---------- @@ -571,10 +565,7 @@ def compute_residual_displacement_field_ssd_3d( References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ ftype = np.asarray(delta_field).dtype cdef: @@ -655,7 +646,7 @@ cpdef compute_residual_displacement_field_ssd_2d( Computes the residual displacement field corresponding to the current displacement field in the Multi-resolution Gauss-Seidel solver proposed by - Bruhn and Weickert [Bruhn05]. + :footcite:t:`Bruhn2005`. Parameters ---------- @@ -686,10 +677,7 @@ cpdef compute_residual_displacement_field_ssd_2d( References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. + .. footbibliography:: """ ftype = np.asarray(delta_field).dtype cdef: @@ -756,7 +744,7 @@ def compute_ssd_demons_step_2d(floating[:,:] delta_field, r"""Demons step for 2D SSD-driven registration Computes the demons step for SSD-driven registration - ( eq. 4 in [Bruhn05] ) + ( eq. 4 in :footcite:p:`Bruhn2005` ) Parameters ---------- @@ -767,7 +755,7 @@ def compute_ssd_demons_step_2d(floating[:,:] delta_field, the gradient of the moving image sigma_sq_x : float parameter controlling the amount of regularization. It corresponds to - $\sigma_x^2$ in algorithm 1 of Vercauteren et al.[Vercauteren09] + $\sigma_x^2$ in algorithm 1 of :footcite:t:`Vercauteren2009`. out : array, shape (R, C, 2) if None, a new array will be created to store the demons step. Otherwise the provided array will be used. @@ -782,14 +770,7 @@ def compute_ssd_demons_step_2d(floating[:,:] delta_field, References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. - [Vercauteren09] Vercauteren, T., Pennec, X., Perchant, A., & Ayache, N. - (2009). Diffeomorphic demons: efficient non-parametric - image registration. NeuroImage, 45(1 Suppl), S61-72. - doi:10.1016/j.neuroimage.2008.10.040 + .. footbibliography:: """ cdef: cnp.npy_intp nr = delta_field.shape[0] @@ -830,7 +811,7 @@ def compute_ssd_demons_step_3d(floating[:,:,:] delta_field, r"""Demons step for 3D SSD-driven registration Computes the demons step for SSD-driven registration - ( eq. 4 in [Bruhn05] ) + ( eq. 4 in :footcite:p:`Bruhn2005` ) Parameters ---------- @@ -841,7 +822,7 @@ def compute_ssd_demons_step_3d(floating[:,:,:] delta_field, the gradient of the moving image sigma_sq_x : float parameter controlling the amount of regularization. It corresponds to - $\sigma_x^2$ in algorithm 1 of Vercauteren et al.[Vercauteren09] + $\sigma_x^2$ in algorithm 1 of :footcite:t:`Vercauteren2009`. out : array, shape (S, R, C, 2) if None, a new array will be created to store the demons step. Otherwise the provided array will be used. @@ -856,14 +837,7 @@ def compute_ssd_demons_step_3d(floating[:,:,:] delta_field, References ---------- - [Bruhn05] Andres Bruhn and Joachim Weickert, "Towards ultimate motion - estimation: combining highest accuracy with real-time - performance", 10th IEEE International Conference on Computer - Vision, 2005. ICCV 2005. - [Vercauteren09] Vercauteren, T., Pennec, X., Perchant, A., & Ayache, N. - (2009). Diffeomorphic demons: efficient non-parametric - image registration. NeuroImage, 45(1 Suppl), S61-72. - doi:10.1016/j.neuroimage.2008.10.040 + .. footbibliography:: """ cdef: cnp.npy_intp ns = delta_field.shape[0] diff --git a/dipy/core/geometry.py b/dipy/core/geometry.py index f21077a8b1..6d30661b65 100644 --- a/dipy/core/geometry.py +++ b/dipy/core/geometry.py @@ -327,7 +327,9 @@ def rodrigues_axis_rotation(r, theta): def nearest_pos_semi_def(B): - """Least squares positive semi-definite tensor estimation + """Least squares positive semi-definite tensor estimation. + + See :footcite:p:`Niethammer2006` for further details about the method. Parameters ---------- @@ -349,10 +351,7 @@ def nearest_pos_semi_def(B): References ---------- - .. [1] Niethammer M, San Jose Estepar R, Bouix S, Shenton M, Westin CF. - On diffusion tensor estimation. Conf Proc IEEE Eng Med Biol Soc. - 2006;1:2622-5. PubMed PMID: 17946125; PubMed Central PMCID: - PMC2791793. + .. footbibliography:: """ B = np.asarray(B) diff --git a/dipy/core/gradients.py b/dipy/core/gradients.py index 8a88f25b36..669d7428bd 100644 --- a/dipy/core/gradients.py +++ b/dipy/core/gradients.py @@ -788,7 +788,7 @@ def reorient_bvecs(gtab, affines, *, atol=1e-2): might cause systematic bias in rotationally invariant measures, such as FA and MD, and also cause characteristic biases in tractography, unless the gradient directions are appropriately reoriented to compensate for this - effect [Leemans2009]_. + effect :footcite:p:`Leemans2009`. Parameters ---------- @@ -808,9 +808,7 @@ def reorient_bvecs(gtab, affines, *, atol=1e-2): References ---------- - .. [Leemans2009] The B-Matrix Must Be Rotated When Correcting for - Subject Motion in DTI Data. Leemans, A. and Jones, D.K. (2009). - MRM, 61: 1336-1349 + .. footbibliography:: """ if isinstance(affines, list): affines = np.stack(affines, axis=-1) @@ -1094,14 +1092,11 @@ def _btens_to_params_2d(btens_2d, ztol): Notes ----- - Implementation following [1]. + Implementation following :footcite:t:`Topgaard2016`. References ---------- - .. [1] D. Topgaard, NMR methods for studying microscopic diffusion - anisotropy, in: R. Valiullin (Ed.), Diffusion NMR of Confined Systems: Fluid - Transport in Porous Solids and Heterogeneous Materials, Royal Society of - Chemistry, Cambridge, UK, 2016. + .. footbibliography:: """ btens_2d[abs(btens_2d) <= ztol] = 0 @@ -1234,14 +1229,11 @@ def params_to_btens(bval, bdelta, b_eta): Notes ----- - Implements eq. 7.11. p. 231 in [1]. + Implements eq. 7.11. p. 231 in :footcite:p:`Topgaard2016`. References ---------- - .. [1] D. Topgaard, NMR methods for studying microscopic diffusion - anisotropy, in: R. Valiullin (Ed.), Diffusion NMR of Confined Systems: - Fluid Transport in Porous Solids and Heterogeneous Materials, Royal - Society of Chemistry, Cambridge, UK, 2016. + .. footbibliography:: """ diff --git a/dipy/core/onetime.py b/dipy/core/onetime.py index 77eb006b08..ff318e6f52 100644 --- a/dipy/core/onetime.py +++ b/dipy/core/onetime.py @@ -35,8 +35,8 @@ -Utilities to support special Python descriptors [1,2], in particular the use of -a useful pattern for properties we call 'one time properties'. These are +Utilities to support special Python descriptors [1]_, [2]_ in particular the use +of a useful pattern for properties we call 'one time properties'. These are object attributes which are declared as properties, but become regular attributes once they've been read the first time. They can thus be evaluated later in the object's life cycle, but once evaluated they become normal, static diff --git a/dipy/core/optimize.py b/dipy/core/optimize.py index 710a9a71c5..6701303d73 100644 --- a/dipy/core/optimize.py +++ b/dipy/core/optimize.py @@ -386,7 +386,9 @@ def fit(self, X, y): class PositiveDefiniteLeastSquares: @warning_for_keywords() def __init__(self, m, *, A=None, L=None): - r"""Regularized least squares with linear matrix inequality constraints [1]_. + r"""Regularized least squares with linear matrix inequality constraints. + + See :footcite:p:`DelaHaije2020` for further details about the method. Generate a CVXPY representation of a regularized least squares optimization problem subject to linear matrix inequality constraints. @@ -419,13 +421,12 @@ def __init__(self, m, *, A=None, L=None): this type. This formulation is used here mainly to enforce polynomial - sum-of-squares constraints on various models, as described in [1]_. + sum-of-squares constraints on various models, as described in + :footcite:p:`DelaHaije2020`. References ---------- - .. [1] Dela Haije et al. "Enforcing necessary non-negativity constraints - for common diffusion MRI models using sum of squares - programming". NeuroImage 209, 2020, 116405. + .. footbibliography:: """ # Input self.A = A diff --git a/dipy/core/rng.py b/dipy/core/rng.py index 9774f17084..3c06c053a3 100644 --- a/dipy/core/rng.py +++ b/dipy/core/rng.py @@ -10,15 +10,10 @@ @warning_for_keywords() def WichmannHill2006(*, ix=100001, iy=200002, iz=300003, it=400004): - """Wichmann Hill (2006) random number generator. + """Wichmann Hill random number generator. - B.A. Wichmann, I.D. Hill, Generating good pseudo-random numbers, - Computational Statistics & Data Analysis, Volume 51, Issue 3, 1 - December 2006, Pages 1614-1622, ISSN 0167-9473, DOI: - 10.1016/j.csda.2006.05.019. - (https://www.sciencedirect.com/science/article/abs/pii/S0167947306001836) - for advice on generating many sequences for use together, and on - alternative algorithms and codes + See :footcite:p:`Wichmann2006` for advice on generating many sequences for + use together, and on alternative algorithms and codes Parameters ---------- @@ -36,6 +31,10 @@ def WichmannHill2006(*, ix=100001, iy=200002, iz=300003, it=400004): r_number : float pseudo-random number uniformly distributed between [0-1] + References + ---------- + .. footbibliography:: + Examples -------- >>> from dipy.core import rng diff --git a/dipy/core/sphere.py b/dipy/core/sphere.py index d23cdd0318..aa3d653c0c 100644 --- a/dipy/core/sphere.py +++ b/dipy/core/sphere.py @@ -641,11 +641,13 @@ def _grad_equality_constraints(vects): @warning_for_keywords() def _get_forces_alt(vects, *, alpha=2.0, **kwargs): - r"""Electrostatic-repulsion objective function. The alpha parameter - controls the power repulsion (energy varies as $1 / r^\alpha$) [1]_. For - $\alpha = 1.0$, this corresponds to electrostatic interaction energy. - The weights ensure equal importance of each shell to the objective - function [2]_ [3]_. + r"""Electrostatic-repulsion objective function. + + The alpha parameter controls the power repulsion (energy varies as + $1 / r^\alpha$) :footcite:p:`Papadakis2000`. For $\alpha = 1.0$, this + corresponds to electrostatic interaction energy. The weights ensure equal + importance of each shell to the objective function :footcite:p:`Cook2007`, + :footcite:p:`Caruyer2013`. Parameters ---------- @@ -663,15 +665,7 @@ def _get_forces_alt(vects, *, alpha=2.0, **kwargs): References ---------- - .. [1] Papadakis, N. G., et al. "Minimal gradient encoding for robust - estimation of diffusion anisotropy." Magnetic Resonance Imaging - 2000 Jul; 18(6): 671-679. - .. [2] Cook, P. A., Symms, M. Boulby, P. A., Alexander, D. C. "Optimal - acquisition orders of diffusion‐weighted MRI measurements." Journal - of Magnetic Resonance Imaging 2007 Apr; 25(5): 1051-1058. - .. [3] Caruyer, E., Lenglet, C., Sapiro, G. and Deriche, R. "Design of - multishell sampling schemes with uniform coverage in diffusion - MRI." Magnetic Resonance in Medicine 2013 Jun; 69(6): 1534-1540. + .. footbibliography:: """ @@ -696,9 +690,12 @@ def _get_forces_alt(vects, *, alpha=2.0, **kwargs): @warning_for_keywords() def _get_grad_forces_alt(vects, *, alpha=2.0, **kwargs): - """1st-order derivative of electrostatic-like repulsion energy [1]_. - The weights ensure equal importance of each shell to the objective - function [2]_ [3]_. + """1st-order derivative of electrostatic-like repulsion energy. + + The weights ensure equal importance of each shell to the objective function + :footcite:p:`Cook2007`, :footcite:p:`Caruyer2013`. + + See :footcite:p:`Papadakis2000` for more details about the definition. Parameters ---------- @@ -716,15 +713,7 @@ def _get_grad_forces_alt(vects, *, alpha=2.0, **kwargs): References ---------- - .. [1] Papadakis, N. G., et al. "Minimal gradient encoding for robust - estimation of diffusion anisotropy." Magnetic Resonance Imaging - 2000 Jul; 18(6): 671-679. - .. [2] Cook, P. A., Symms, M. Boulby, P. A., Alexander, D. C. "Optimal - acquisition orders of diffusion‐weighted MRI measurements." Journal - of Magnetic Resonance Imaging 2007 Apr; 25(5): 1051-1058. - .. [3] Caruyer, E., Lenglet, C., Sapiro, G. and Deriche, R. "Design of - multishell sampling schemes with uniform coverage in diffusion - MRI." Magnetic Resonance in Medicine 2013 Jun; 69(6): 1534-1540. + .. footbibliography:: """ diff --git a/dipy/data/__init__.py b/dipy/data/__init__.py index cbdaf4e737..d7a946425c 100644 --- a/dipy/data/__init__.py +++ b/dipy/data/__init__.py @@ -404,8 +404,9 @@ def matlab_life_results(): @warning_for_keywords() def load_sdp_constraints(model_name, *, order=None): - """Import semidefinite programming constraint matrices for different models, - generated as described for example in [1]_. + """Import semidefinite programming constraint matrices for different models. + + Generated as described for example in :footcite:p:`DelaHaije2020`. Parameters ---------- @@ -427,9 +428,7 @@ def load_sdp_constraints(model_name, *, order=None): References ---------- - .. [1] Dela Haije et al. "Enforcing necessary non-negativity constraints - for common diffusion MRI models using sum of squares programming". - NeuroImage 209, 2020, 116405. + .. footbibliography:: """ diff --git a/dipy/data/fetcher.py b/dipy/data/fetcher.py index 0c3bfcc35d..4c901ad8cd 100644 --- a/dipy/data/fetcher.py +++ b/dipy/data/fetcher.py @@ -1691,11 +1691,12 @@ def get_fnames(*, name="small_64D"): def read_qtdMRI_test_retest_2subjects(): - r"""Load test-retest qt-dMRI acquisitions of two C57Bl6 mice. These - datasets were used to study test-retest reproducibility of time-dependent - q-space indices (q$\tau$-indices) in the corpus callosum of two mice [1]. - The data itself and its details are publicly available and can be cited at - [2]. + r"""Load test-retest qt-dMRI acquisitions of two C57Bl6 mice. + + These datasets were used to study test-retest reproducibility of + time-dependent q-space indices (q$\tau$-indices) in the corpus callosum of + two mice :footcite:p:`Fick2018`. The data itself and its details are + publicly available and can be cited at :footcite:p:`Wassermann2017`. The test-retest diffusion MRI spin echo sequences were acquired from two C57Bl6 wild-type mice on an 11.7 Tesla Bruker scanner. The test and retest @@ -1721,12 +1722,7 @@ def read_qtdMRI_test_retest_2subjects(): References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. - .. [2] Wassermann, Demian, et al., "Test-Retest qt-dMRI datasets for - `Non-Parametric GraphNet-Regularized Representation of dMRI in Space - and Time'". doi:10.5281/zenodo.996889, 2017. + .. footbibliography:: """ data = [] data_names = [ @@ -2252,6 +2248,9 @@ def read_bundles_2_subjects( ): r"""Read images and streamlines from 2 subjects of the SNAIL dataset. + See :footcite:p:`Renauld2016` and :footcite:p:`Garyfallidis2015` for further + details about the dataset and processing pipeline. + Parameters ---------- subj_id : string @@ -2274,13 +2273,7 @@ def read_bundles_2_subjects( References ---------- - .. [1] Renauld, E., M. Descoteaux, M. Bernier, E. Garyfallidis, - K. Whittingstall, "Morphology of thalamus, LGN and optic radiation do not - influence EEG alpha waves", Plos One (under submission), 2015. - - .. [2] Garyfallidis, E., O. Ocegueda, D. Wassermann, - M. Descoteaux. Robust and efficient linear registration of fascicles in the - space of streamlines , Neuroimage, 117:124-140, 2015. + .. footbibliography:: """ dname = pjoin(dipy_home, "exp_bundles_and_maps", "bundles_2_subjects") @@ -2607,7 +2600,9 @@ def fetch_hcp( ): """ Fetch HCP diffusion data and arrange it in a manner that resembles the - BIDS [1]_ specification. + BIDS specification. + + See :footcite:p:`Gorgolewski2016` for details about the BIDS specification. Parameters ---------- @@ -2648,9 +2643,9 @@ def fetch_hcp( Local filenames are changed to match our expected conventions. - .. [1] Gorgolewski et al. (2016). The brain imaging data structure, - a format for organizing and describing outputs of neuroimaging - experiments. Scientific Data, 3::160044. DOI: 10.1038/sdata.2016.44. + References + ---------- + .. footbibliography:: """ # noqa: E501 if not has_boto3: raise ValueError( @@ -2830,7 +2825,11 @@ def _hbn_downloader(my_path, derivative, subjects, client): def fetch_hbn(subjects, *, path=None, include_afq=False): """ - Fetch preprocessed data from the Healthy Brain Network POD2 study [1, 2]_. + Fetch preprocessed data from the Healthy Brain Network POD2 study. + + + See :footcite:p:`Alexander2017` and :footcite:p:`RichieHalford2022` for + further details about the study and processing pipeline. Parameters ---------- @@ -2850,16 +2849,9 @@ def fetch_hbn(subjects, *, path=None, include_afq=False): dict with remote and local names of these files, path to BIDS derivative dataset - Notes - ----- - - .. [1] Alexander LM, Escalera J, Ai L, et al. An open resource for - transdiagnostic research in pediatric mental health and learning - disorders. Sci Data. 2017;4:170181. - - .. [2] Richie-Halford A, Cieslak M, Ai L, et al. An analysis-ready and - quality controlled resource for pediatric brain white-matter research. - Scientific Data. 2022;9(1):1-27. + References + ---------- + .. footbibliography:: """ diff --git a/dipy/denoise/adaptive_soft_matching.py b/dipy/denoise/adaptive_soft_matching.py index db86e3bf96..d33ba901aa 100644 --- a/dipy/denoise/adaptive_soft_matching.py +++ b/dipy/denoise/adaptive_soft_matching.py @@ -22,7 +22,7 @@ def adaptive_soft_matching(ima, fimau, fimao, sigma): filtered image with optimized non-local means using a small block (suggested:5x5), which corresponds to a "low resolution" filter. sigma : the estimated standard deviation of the Gaussian random variables - that explain the rician noise. Note: In P. Coupe et al. the + that explain the rician noise. Note: In :footcite:p:`Coupe2012` the rician noise was simulated as sqrt((f+x)^2 + (y)^2) where f is the pixel value and x and y are independent realizations of a random variable with Normal distribution, with mean=0 and @@ -36,11 +36,7 @@ def adaptive_soft_matching(ima, fimau, fimao, sigma): References ---------- - .. [Coupe11] Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins. - "Multiresolution Non-Local Means Filter for 3D MR Image - Denoising" IET Image Processing, Institution of Engineering - and Technology, - 2011 + .. footbibliography:: """ diff --git a/dipy/denoise/enhancement_kernel.pyx b/dipy/denoise/enhancement_kernel.pyx index fbceb58040..f21cdeadd7 100644 --- a/dipy/denoise/enhancement_kernel.pyx +++ b/dipy/denoise/enhancement_kernel.pyx @@ -30,6 +30,10 @@ cdef class EnhancementKernel: """ Compute a look-up table for the contextual enhancement kernel + See :footcite:p:`Meesters2016a`, :footcite:p:`Duits2011`, + :footcite:p:`Portegies2015a` and :footcite:p:`Portegies2015b` for + further details about the method. + Parameters ---------- D33 : float @@ -50,23 +54,7 @@ cdef class EnhancementKernel: References ---------- - [Meesters2016_ISMRM] S. Meesters, G. Sanguinetti, E. Garyfallidis, - J. Portegies, R. Duits. (2016) Fast implementations - of contextual PDE’s for HARDI data processing in - DIPY. ISMRM 2016 conference. - [DuitsAndFranken_IJCV] R. Duits and E. Franken (2011) Left-invariant diffusions - on the space of positions and orientations and their - application to crossing-preserving smoothing of HARDI - images. International Journal of Computer Vision, 92:231-264. - [Portegies2015] J. Portegies, G. Sanguinetti, S. Meesters, and R. Duits. - (2015) New Approximation of a Scale Space Kernel on SE(3) - and Applications in Neuroimaging. Fifth International - Conference on Scale Space and Variational Methods in - Computer Vision - [Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters, - G. Girard, and R. Duits. (2015) Improving Fiber - Alignment in HARDI by Combining Contextual PDE flow with - Constrained Spherical Deconvolution. PLoS One. + .. footbibliography:: """ # save parameters as class members diff --git a/dipy/denoise/gibbs.py b/dipy/denoise/gibbs.py index 6564003244..39d3faa712 100644 --- a/dipy/denoise/gibbs.py +++ b/dipy/denoise/gibbs.py @@ -145,7 +145,9 @@ def _gibbs_removal_1d(x, *, axis=0, n_points=3): def _weights(shape): """Computes the weights necessary to combine two images processed by - the 1D Gibbs removal procedure along two different axes [1]_. + the 1D Gibbs removal procedure along two different axes. + + See :footcite:p:`Kellner2016` for further details about the method. Parameters ---------- @@ -161,9 +163,7 @@ def _weights(shape): References ---------- - .. [1] Kellner E, Dhital B, Kiselev VG, Reisert M. Gibbs-ringing artifact - removal based on local subvoxel-shifts. Magn Reson Med. 2016 - doi: 10.1002/mrm.26054. + .. footbibliography:: """ G0 = np.zeros(shape) @@ -189,7 +189,8 @@ def _weights(shape): @warning_for_keywords() def _gibbs_removal_2d(image, *, n_points=3, G0=None, G1=None): - """Suppress Gibbs ringing of a 2D image. + """Suppress Gibbs ringing of a 2D image :footcite:p:`Kellner2016`, + :footcite:p:`NetoHenriques2018`. Parameters ---------- @@ -220,13 +221,7 @@ def _gibbs_removal_2d(image, *, n_points=3, G0=None, G1=None): References ---------- - Please cite the following articles - .. [1] Neto Henriques, R., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). https://doi.org/10.17863/CAM.29356 - .. [2] Kellner E, Dhital B, Kiselev VG, Reisert M. Gibbs-ringing artifact - removal based on local subvoxel-shifts. Magn Reson Med. 2016 - doi: 10.1002/mrm.26054. + .. footbibliography:: """ if G0 is None or G1 is None: @@ -246,6 +241,9 @@ def _gibbs_removal_2d(image, *, n_points=3, G0=None, G1=None): def gibbs_removal(vol, *, slice_axis=2, n_points=3, inplace=True, num_processes=1): """Suppresses Gibbs ringing artefacts of images volumes. + See :footcite:p:`Kellner2016` and :footcite:p:`NetoHenriques2018` for + further details about the method. + Parameters ---------- vol : ndarray ([X, Y]), ([X, Y, Z]) or ([X, Y, Z, g]) @@ -279,12 +277,7 @@ def gibbs_removal(vol, *, slice_axis=2, n_points=3, inplace=True, num_processes= References ---------- - .. [1] Neto Henriques, R., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). https://doi.org/10.17863/CAM.29356 - .. [2] Kellner E, Dhital B, Kiselev VG, Reisert M. Gibbs-ringing artifact - removal based on local subvoxel-shifts. Magn Reson Med. 2016 - doi: 10.1002/mrm.26054. + .. footbibliography:: """ nd = vol.ndim diff --git a/dipy/denoise/localpca.py b/dipy/denoise/localpca.py index 08f68e4254..9918c08e7a 100644 --- a/dipy/denoise/localpca.py +++ b/dipy/denoise/localpca.py @@ -55,14 +55,11 @@ def _pca_classifier(L, nvoxels): Notes ----- - This is based on the algorithm described in [1]_. + This is based on the algorithm described in :footcite:p:`Veraart2016c`. References ---------- - .. [1] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random matrix - theory. Neuroimage 142:394-406. - doi: 10.1016/j.neuroimage.2016.08.016 + .. footbibliography:: """ # if num_samples - 1 (to correct for mean subtraction) is less than number @@ -71,8 +68,9 @@ def _pca_classifier(L, nvoxels): L = L[-(nvoxels - 1) :] # Note that the condition expressed in the while-loop is expressed in terms - # of the variance of equation (12), not equation (11) as in [1]_. Also, - # this code implements ascending eigenvalues, unlike [1]_. + # of the variance of equation (12), not equation (11) as in + # :footcite:p:`Veraart2016c`. Also, this code implements ascending + # eigenvalues, unlike :footcite:p:`Veraart2016c`. var = np.mean(L) c = L.size - 1 r = L[c] - L[0] - 4 * np.sqrt((c + 1.0) / nvoxels) * var @@ -203,7 +201,7 @@ def genpca( sigma : float or 3D array (optional) Standard deviation of the noise estimated from the data. If no sigma is given, this will be estimated based on random matrix theory - [1]_,[2]_ + :footcite:p:`Veraart2016b`, :footcite:p:`Veraart2016c`. mask : 3D boolean array (optional) A mask with voxels that are true inside the brain and false outside of it. The function denoises within the true part and returns zeros @@ -225,8 +223,8 @@ def genpca( \tau = (\tau_{factor} \sigma)^2 $\tau_{factor}$ can be set to a predefined values (e.g. $\tau_{factor} = - 2.3$ [3]_), or automatically calculated using random matrix theory - (in case that $\tau_{factor}$ is set to None). + 2.3$ :footcite:p:`Manjon2013`), or automatically calculated using random + matrix theory (in case that $\tau_{factor}$ is set to None). return_sigma : bool (optional) If true, the Standard deviation of the noise will be returned. out_dtype : str or dtype (optional) @@ -243,17 +241,7 @@ def genpca( References ---------- - .. [1] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random matrix - theory. Neuroimage 142:394-406. - doi: 10.1016/j.neuroimage.2016.08.016 - .. [2] Veraart J, Fieremans E, Novikov DS. 2016. Diffusion MRI noise - mapping using random matrix theory. Magnetic Resonance in Medicine. - doi: 10.1002/mrm.26059. - .. [3] Manjon JV, Coupe P, Concha L, Buades A, Collins DL (2013) - Diffusion Weighted Image Denoising Using Overcomplete Local - PCA. PLoS ONE 8(9): e73021. - https://doi.org/10.1371/journal.pone.0073021 + .. footbibliography:: """ if mask is None: # If mask is not specified, use the whole volume @@ -416,7 +404,9 @@ def localpca( out_dtype=None, suppress_warning=False, ): - r"""Performs local PCA denoising according to Manjon et al. [1]_. + r"""Performs local PCA denoising. + + The method follows the algorithm in :footcite:t:`Manjon2013`. Parameters ---------- @@ -425,7 +415,7 @@ def localpca( are the diffusion gradient directions. sigma : float or 3D array (optional) Standard deviation of the noise estimated from the data. If not given, - calculate using method in [1]_. + calculate using method in :footcite:t:`Manjon2013`. mask : 3D boolean array (optional) A mask with voxels that are true inside the brain and false outside of it. The function denoises within the true part and returns zeros @@ -457,13 +447,14 @@ def localpca( \tau_{factor} can be change to adjust the relationship between the noise standard deviation and the threshold \tau. If \tau_{factor} is set to None, it will be automatically calculated using the - Marcenko-Pastur distribution [2]_. Default: 2.3 according to [1]_. + Marcenko-Pastur distribution :footcite:p:`Veraart2016c`. Default: 2.3 + according to :footcite:t:`Manjon2013`. return_sigma : bool (optional) If true, a noise standard deviation estimate based on the - Marcenko-Pastur distribution is returned [2]_. + Marcenko-Pastur distribution is returned :footcite:p:`Veraart2016c`. correct_bias : bool (optional) Whether to correct for bias due to Rician noise. This is an - implementation of equation 8 in [1]_. + implementation of equation 8 in :footcite:p:`Manjon2013`. out_dtype : str or dtype (optional) The dtype for the output array. Default: output has the same dtype as the input. @@ -478,14 +469,7 @@ def localpca( References ---------- - .. [1] Manjon JV, Coupe P, Concha L, Buades A, Collins DL (2013) - Diffusion Weighted Image Denoising Using Overcomplete Local - PCA. PLoS ONE 8(9): e73021. - https://doi.org/10.1371/journal.pone.0073021 - .. [2] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random matrix - theory. Neuroimage 142:394-406. - doi: 10.1016/j.neuroimage.2016.08.016 + .. footbibliography:: """ # check gtab is given, if sigma is not given if sigma is None and gtab is None: @@ -526,7 +510,9 @@ def mppca( suppress_warning=False, ): r"""Performs PCA-based denoising using the Marcenko-Pastur - distribution [1]_. + distribution. + + See :footcite:p:`Veraart2016c` for further details about the method. Parameters ---------- @@ -547,7 +533,7 @@ def mppca( more accurate. return_sigma : bool (optional) If true, a noise standard deviation estimate based on the - Marcenko-Pastur distribution is returned [2]_. + Marcenko-Pastur distribution is returned :footcite:p:`Veraart2016b`. out_dtype : str or dtype (optional) The dtype for the output array. Default: output has the same dtype as the input. @@ -564,13 +550,7 @@ def mppca( References ---------- - .. [1] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random matrix - theory. Neuroimage 142:394-406. - doi: 10.1016/j.neuroimage.2016.08.016 - .. [2] Veraart J, Fieremans E, Novikov DS. 2016. Diffusion MRI noise - mapping using random matrix theory. Magnetic Resonance in Medicine. - doi: 10.1002/mrm.26059. + .. footbibliography:: """ return genpca( arr, diff --git a/dipy/denoise/nlmeans.py b/dipy/denoise/nlmeans.py index 0a502be8cd..5d7aa0dfb7 100644 --- a/dipy/denoise/nlmeans.py +++ b/dipy/denoise/nlmeans.py @@ -22,7 +22,9 @@ def nlmeans( rician=True, num_threads=None, ): - r"""Non-local means for denoising 3D and 4D images [Descoteaux08]_. + r"""Non-local means for denoising 3D and 4D images. + + See :footcite:p:Descoteaux2008a` for further details about the method. Parameters ---------- @@ -52,10 +54,7 @@ def nlmeans( References ---------- - .. [Descoteaux08] Descoteaux, Maxime and Wiest-Daesslé, Nicolas and Prima, - Sylvain and Barillot, Christian and Deriche, Rachid - Impact of Rician Adapted Non-Local Means Filtering on - HARDI, MICCAI 2008 + .. footbibliography:: """ diff --git a/dipy/denoise/nlmeans_block.pyx b/dipy/denoise/nlmeans_block.pyx index 121326e0a3..54465b5da2 100644 --- a/dipy/denoise/nlmeans_block.pyx +++ b/dipy/denoise/nlmeans_block.pyx @@ -347,7 +347,10 @@ cpdef upfir(double[:, :] image, double[:] h): @cython.wraparound(False) @cython.cdivision(True) def nlmeans_block(double[:, :, :]image, double[:, :, :] mask, int patch_radius, int block_radius, double h, int rician): - """Non-Local Means Denoising Using Blockwise Averaging + """Non-Local Means Denoising Using Blockwise Averaging. + + See :footcite:p:`Coupe2008` and :footcite:p:`Coupe2012` for further details + about the method. Parameters ---------- @@ -378,14 +381,7 @@ def nlmeans_block(double[:, :, :]image, double[:, :, :] mask, int patch_radius, References ---------- - [1] P. Coupe, P. Yger, S. Prima, P. Hellier, C. Kervrann, C. Barillot, - "An Optimized Blockwise Non Local Means Denoising Filter for 3D Magnetic - Resonance Images" - IEEE Transactions on Medical Imaging, 27(4):425-441, 2008 - - [2] Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins. - "Multiresolution Non-Local Means Filter for 3D MR Image Denoising" - IET Image Processing, Institution of Engineering and Technology, 2011 + .. footbibliography:: """ diff --git a/dipy/denoise/noise_estimate.py b/dipy/denoise/noise_estimate.py index 43808a6aae..7de5b77d67 100644 --- a/dipy/denoise/noise_estimate.py +++ b/dipy/denoise/noise_estimate.py @@ -7,8 +7,14 @@ def _inv_nchi_cdf(N, K, alpha): - """Inverse CDF for the noncentral chi distribution - See [1]_ p.3 section 2.3""" + """Inverse CDF for the noncentral chi distribution. + + See :footcite:t:`Koay2009b`, p.3 section 2.3. + + References + ---------- + .. footbibliography:: + """ return gammainccinv(N * K, 1 - alpha) / K @@ -32,6 +38,9 @@ def piesno(data, N, *, alpha=0.01, step=100, itermax=100, eps=1e-5, return_mask= """ Probabilistic Identification and Estimation of Noise (PIESNO). + See :footcite:p:`Koay2009a` and :footcite:p:`Koay2009b` for further details + about the method. + Parameters ---------- data : ndarray @@ -84,16 +93,7 @@ def piesno(data, N, *, alpha=0.01, step=100, itermax=100, eps=1e-5, return_mask= References ---------- - - .. [1] Koay CG, Ozarslan E and Pierpaoli C. - "Probabilistic Identification and Estimation of Noise (PIESNO): - A self-consistent approach and its applications in MRI." - Journal of Magnetic Resonance 2009; 199: 94-103. - - .. [2] Koay CG, Ozarslan E and Basser PJ. - "A signal transformational framework for breaking the noise floor - and its applications in MRI." - Journal of Magnetic Resonance 2009; 197: 108-119. + .. footbibliography:: """ # This method works on a 2D array with repetitions as the third dimension, @@ -161,6 +161,10 @@ def _piesno_3D( ): """ Probabilistic Identification and Estimation of Noise (PIESNO). + + See :footcite:p:`Koay2009a` and :footcite:p:`Koay2009b` for further details + about the method. + This is the slice by slice version for working on a 4D array. Parameters @@ -213,16 +217,7 @@ def _piesno_3D( References ---------- - - .. [1] Koay CG, Ozarslan E and Pierpaoli C. - "Probabilistic Identification and Estimation of Noise (PIESNO): - A self-consistent approach and its applications in MRI." - Journal of Magnetic Resonance 2009; 199: 94-103. - - .. [2] Koay CG, Ozarslan E and Basser PJ. - "A signal transformational framework for breaking the noise floor - and its applications in MRI." - Journal of Magnetic Resonance 2009; 197: 108-119. + .. footbibliography:: """ if np.all(data == 0): @@ -305,8 +300,8 @@ def estimate_sigma(arr, *, disable_background_masking=False, N=0): Number of coils of the receiver array. Use N = 1 in case of a SENSE reconstruction (Philips scanners) or the number of coils for a GRAPPA reconstruction (Siemens and GE). Use 0 to disable the correction factor, - as for example if the noise is Gaussian distributed. See [1] for more - information. + as for example if the noise is Gaussian distributed. See + :footcite:p:`Koay2006a` for more information. Returns ------- @@ -317,23 +312,17 @@ def estimate_sigma(arr, *, disable_background_masking=False, N=0): ----- This function is the same as manually taking the standard deviation of the background and gives one value for the whole 3D array. - It also includes the coil-dependent correction factor of Koay 2006 - (see [1]_, equation 18) with theta = 0. - Since this function was introduced in [2]_ for T1 imaging, - it is expected to perform ok on diffusion MRI data, but might oversmooth - some regions and leave others un-denoised for spatially varying noise - profiles. Consider using :func:`piesno` to estimate sigma instead if visual - inaccuracies are apparent in the denoised result. + It also includes the coil-dependent correction factor from + :footcite:t:`Koay2006a` (see equation 18 in :footcite:p:`Koay2006a`) with + theta = 0. Since this function was introduced in :footcite:p:`Coupe2008` for + T1 imaging, it is expected to perform ok on diffusion MRI data, but might + oversmooth some regions and leave others un-denoised for spatially varying + noise profiles. Consider using :func:`piesno` to estimate sigma instead if + visual inaccuracies are apparent in the denoised result. References ---------- - .. [1] Koay, C. G., & Basser, P. J. (2006). Analytically exact correction - scheme for signal extraction from noisy magnitude MR signals. - Journal of Magnetic Resonance), 179(2), 317-22. - - .. [2] Coupe, P., Yger, P., Prima, S., Hellier, P., Kervrann, C., Barillot, - C., 2008. An optimized blockwise nonlocal means denoising filter for 3-D - magnetic resonance images, IEEE Trans. Med. Imaging 27, 425-41. + .. footbibliography:: """ k = np.zeros((3, 3, 3), dtype=np.int8) diff --git a/dipy/denoise/non_local_means.py b/dipy/denoise/non_local_means.py index 040204478d..3ebe02e204 100644 --- a/dipy/denoise/non_local_means.py +++ b/dipy/denoise/non_local_means.py @@ -8,8 +8,11 @@ def non_local_means( arr, sigma, *, mask=None, patch_radius=1, block_radius=5, rician=True ): - r"""Non-local means for denoising 3D and 4D images, using - blockwise averaging approach + r"""Non-local means for denoising 3D and 4D images, using blockwise + averaging approach. + + See :footcite:p:`Coupe2008` and :footcite:p:`Coupe2012` for further details + about the method. Parameters ---------- @@ -34,16 +37,7 @@ def non_local_means( References ---------- - - .. [Coupe08] P. Coupe, P. Yger, S. Prima, P. Hellier, C. Kervrann, C. - Barillot, An Optimized Blockwise Non Local Means Denoising - Filter for 3D Magnetic Resonance Images, IEEE Transactions on - Medical Imaging, 27(4):425-441, 2008 - - .. [Coupe11] Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins. - Adaptive Multiresolution Non-Local Means Filter for 3D MR Image - Denoising IET Image Processing, Institution of Engineering and - Technology, 2011 + .. footbibliography:: """ if not np.isscalar(sigma) and not sigma.shape == (1,): diff --git a/dipy/denoise/patch2self.py b/dipy/denoise/patch2self.py index ae32a0e5be..55e2bc26ab 100644 --- a/dipy/denoise/patch2self.py +++ b/dipy/denoise/patch2self.py @@ -175,6 +175,8 @@ def patch2self( ): """Patch2Self Denoiser. + See :footcite:p:`Fadnavis2020` for further details about the method. + Parameters ---------- data : ndarray @@ -231,9 +233,7 @@ def patch2self( References ---------- - [Fadnavis20] S. Fadnavis, J. Batson, E. Garyfallidis, Patch2Self: - Denoising Diffusion MRI with Self-supervised Learning, - Advances in Neural Information Processing Systems 33 (2020) + .. footbibliography:: """ if isinstance(patch_radius, int): diff --git a/dipy/denoise/pca_noise_estimate.pyx b/dipy/denoise/pca_noise_estimate.pyx index 14bc4dfb5e..569583d6a5 100644 --- a/dipy/denoise/pca_noise_estimate.pyx +++ b/dipy/denoise/pca_noise_estimate.pyx @@ -62,19 +62,18 @@ def pca_noise_estimate(data, gtab, *, patch_radius=1, correct_bias=True, Notes ----- - In [1]_, images are used as samples, so voxels are features, therefore - eigenvectors are image-shaped. However, [1]_ is not clear on how to use - these eigenvectors to determine the noise level, so here eigenvalues - (variance over samples explained by eigenvectors) are used to scale - the eigenvectors. Use images_as_samples=True to use this algorithm. - Alternatively, voxels can be used as samples using - images_as_samples=False. This is not the canonical algorithm of [1]_. + In :footcite:p:`Manjon2013`, images are used as samples, so voxels are + features, therefore eigenvectors are image-shaped. However, + :footcite:t:`Manjon2013` is not clear on how to use these eigenvectors + to determine the noise level, so here eigenvalues (variance over samples + explained by eigenvectors) are used to scale the eigenvectors. Use + images_as_samples=True to use this algorithm. Alternatively, voxels can + be used as samples using images_as_samples=False. This is not the + canonical algorithm of :footcite:t:`Manjon2013`. References ---------- - .. [1] Manjon JV, Coupe P, Concha L, Buades A, Collins DL "Diffusion - Weighted Image Denoising Using Overcomplete Local PCA". PLoS ONE - 8(9): e73021. doi:10.1371/journal.pone.0073021. + .. footbibliography:: """ # first identify the number of the b0 images K = gtab.b0s_mask[gtab.b0s_mask].size diff --git a/dipy/denoise/shift_twist_convolution.pyx b/dipy/denoise/shift_twist_convolution.pyx index f222e4dddc..c0b004896d 100644 --- a/dipy/denoise/shift_twist_convolution.pyx +++ b/dipy/denoise/shift_twist_convolution.pyx @@ -19,6 +19,10 @@ def convolve(odfs_sh, kernel, sh_order_max, *, test_mode=False, num_threads=None """ Perform the shift-twist convolution with the ODF data and the lookup-table of the kernel. + See :footcite:p:`Meesters2016`, :footcite:p:`Duits2011`, + :footcite:p:`Portegies2015a` and :footcite:p:`Portegies2015b` for further + details about the method. + Parameters ---------- odfs : array of double @@ -46,23 +50,7 @@ def convolve(odfs_sh, kernel, sh_order_max, *, test_mode=False, num_threads=None References ---------- - [Meesters2016_ISMRM] S. Meesters, G. Sanguinetti, E. Garyfallidis, - J. Portegies, R. Duits. (2016) Fast implementations of - contextual PDE’s for HARDI data processing in DIPY. - ISMRM 2016 conference. - [DuitsAndFranken_IJCV] R. Duits and E. Franken (2011) Left-invariant diffusions - on the space of positions and orientations and their - application to crossing-preserving smoothing of HARDI - images. International Journal of Computer Vision, 92:231-264. - [Portegies2015] J. Portegies, G. Sanguinetti, S. Meesters, and R. Duits. - (2015) New Approximation of a Scale Space Kernel on SE(3) and - Applications in Neuroimaging. Fifth International - Conference on Scale Space and Variational Methods in - Computer Vision - [Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters, G.Girard, - and R. Duits. (2015) Improving Fiber Alignment in HARDI by - Combining Contextual PDE flow with Constrained Spherical - Deconvolution. PLoS One. + .. footbibliography:: """ # convert the ODFs from SH basis to DSF diff --git a/dipy/direction/peaks.py b/dipy/direction/peaks.py index c5924365d5..2681c5e8ea 100644 --- a/dipy/direction/peaks.py +++ b/dipy/direction/peaks.py @@ -491,8 +491,9 @@ def peaks_from_model( SH coefficients (default 8). sh_basis_type : {None, 'tournier07', 'descoteaux07'} ``None`` for the default DIPY basis, - ``tournier07`` for the Tournier 2007 [2]_ basis, and - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis + ``tournier07`` for the Tournier 2007 :footcite:p:Tournier2007` basis, + and ``descoteaux07`` for the Descoteaux 2007 :footcite:p:Descoteaux2007` + basis (``None`` defaults to ``descoteaux07``). legacy: bool, optional True to use a legacy basis definition for backward compatibility @@ -523,13 +524,7 @@ def peaks_from_model( References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. + .. footbibliography:: """ if return_sh and (B is None or invB is None): diff --git a/dipy/direction/ptt_direction_getter.pyx b/dipy/direction/ptt_direction_getter.pyx index 32f6a14195..e5e9cf9d63 100644 --- a/dipy/direction/ptt_direction_getter.pyx +++ b/dipy/direction/ptt_direction_getter.pyx @@ -4,16 +4,16 @@ """ Implementation of the Parallel Transport Tractography (PTT) algorithm by -Aydogan et al., (2021). PTT Default parameter values are slightly different -then in Trekker to optimise performances. The rejection sampling +:footcite:t:`Aydogan2021`. PTT Default parameter values are slightly different +than in Trekker to optimise performances. The rejection sampling algorithm also uses fewer samples to estimate the maximum of the posterior, and fewer tries to obtain a suitable propagation candidate. Moreover, the initial tangent direction in this implementation is always obtained from the voxel-wise peaks. -Aydogan DB, Shi Y. Parallel Transport Tractography. IEEE Trans - Med Imaging. 2021 Feb;40(2):635-647. doi: 10.1109/TMI.2020.3034038. - Epub 2021 Feb 2. PMID: 33104507; PMCID: PMC7931442. +References +---------- +.. footbibliography:: """ cimport numpy as cnp diff --git a/dipy/reconst/cross_validation.py b/dipy/reconst/cross_validation.py index ed14067e22..9b478a9a72 100644 --- a/dipy/reconst/cross_validation.py +++ b/dipy/reconst/cross_validation.py @@ -58,6 +58,8 @@ def kfold_xval(model, data, folds, *model_args, **model_kwargs): It generates out-of-sample predictions for each measurement. + See :footcite:p:`Rokem2014` for further details about the method. + Parameters ---------- model : Model class instance @@ -92,9 +94,7 @@ class for which prediction is conducted. That is, the Fit object that gets References ---------- - .. [1] Rokem, A., Chan, K.L. Yeatman, J.D., Pestilli, F., Mezer, A., - Wandell, B.A., 2014. Evaluating the accuracy of diffusion models at - multiple b-values with cross-validation. ISMRM 2014. + .. footbibliography:: """ _ = model_kwargs.pop("rng", np.random.default_rng()) diff --git a/dipy/reconst/csdeconv.py b/dipy/reconst/csdeconv.py index dd49b20a19..174685b069 100644 --- a/dipy/reconst/csdeconv.py +++ b/dipy/reconst/csdeconv.py @@ -127,8 +127,8 @@ def response_from_mask(gtab, data, mask): fiber response function. In order to do this, we look for voxels with very anisotropic configurations. This information can be obtained by using csdeconv.mask_for_response_ssst() through a mask of selected voxels - (see[1]_). The present function uses such a mask to compute the ssst - response function. + (see :footcite:p:`Tournier2004`). The present function uses such a mask to + compute the ssst response function. For the response we also need to find the average S0 in the ROI. This is possible using `gtab.b0s_mask()` we can find all the S0 volumes (which @@ -142,9 +142,7 @@ def response_from_mask(gtab, data, mask): References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the - fiber orientation density function from diffusion-weighted MRI - data using spherical deconvolution + .. footbibliography:: """ return response_from_mask_ssst(gtab, data, mask) @@ -195,19 +193,24 @@ def __init__( tau=0.1, convergence=50, ): - r"""Constrained Spherical Deconvolution (CSD) [1]_. + r"""Constrained Spherical Deconvolution (CSD). + + See :footcite:p:`Tournier2007` for further details about the model. Spherical deconvolution computes a fiber orientation distribution - (FOD), also called fiber ODF (fODF) [2]_, as opposed to a diffusion ODF - as the QballModel or the CsaOdfModel. This results in a sharper angular - profile with better angular resolution that is the best object to be - used for later deterministic and probabilistic tractography [3]_. + (FOD), also called fiber ODF (fODF) :footcite:p:`Descoteaux2009`, as + opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This + results in a sharper angular profile with better angular resolution that + is the best object to be used for later deterministic and probabilistic + tractography :footcite:p:`Cote2013`. A sharp fODF is obtained because a single fiber *response* function is injected as *a priori* knowledge. The response function is often data-driven and is thus provided as input to the ConstrainedSphericalDeconvModel. It will be used as deconvolution - kernel, as described in [1]_. + kernel, as described in :footcite:p:`Tournier2007`. + + See also :footcite:p:`Tournier2012`. Parameters ---------- @@ -218,7 +221,7 @@ def __init__( ndarray and the second is the signal value for the response function without diffusion weighting (i.e. S0). This is to be able to generate a single fiber synthetic signal. The response function - will be used as deconvolution kernel ([1]_). + will be used as deconvolution kernel :footcite:p:`Tournier2007`. reg_sphere : Sphere (optional) sphere used to build the regularization B matrix. Default: 'symmetric362'. @@ -226,30 +229,21 @@ def __init__( maximal spherical harmonics order (l). Default: 8 lambda_ : float (optional) weight given to the constrained-positivity regularization part of - the deconvolution equation (see [1]_). Default: 1 + the deconvolution equation (see :footcite:p:`Tournier2007`). + Default: 1 tau : float (optional) threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 % of the mean fODF amplitude (here, 10% by default) - (see [1]_). Default: 0.1 + (see :footcite:p:`Tournier2007`). Default: 0.1. convergence : int Maximum number of iterations to allow the deconvolution to converge. References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of - the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical - deconvolution - .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and - Probabilistic Tractography Based on Complex Fibre Orientation - Distributions - .. [3] Côté, M-A., et al. Medical Image Analysis 2013. Tractometer: - Towards validation of tractography pipelines - .. [4] Tournier, J.D, et al. Imaging Systems and Technology - 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions + .. footbibliography:: """ # Initialize the parent class: SphHarmModel.__init__(self, gtab) @@ -297,7 +291,7 @@ def __init__( # scale lambda_ to account for differences in the number of # SH coefficients and number of mapped directions - # This is exactly what is done in [4]_ + # This is exactly what is done in :footcite:p:`Tournier2012` lambda_ = ( lambda_ * self.R.shape[0] @@ -373,14 +367,16 @@ class ConstrainedSDTModel(SphHarmModel): def __init__( self, gtab, ratio, reg_sphere=None, sh_order_max=8, lambda_=1.0, tau=0.1 ): - r"""Spherical Deconvolution Transform (SDT) [1]_. + r"""Spherical Deconvolution Transform (SDT) + :footcite:p:`Descoteaux2009`. The SDT computes a fiber orientation distribution (FOD) as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution. The Constrained SDTModel is similar to the Constrained CSDModel but mathematically it - deconvolves the q-ball ODF as opposed to the HARDI signal (see [1]_ - for a comparison and a thorough discussion). + deconvolves the q-ball ODF as opposed to the HARDI signal (see + :footcite:p:`Descoteaux2009` for a comparison and a thorough + discussion). A sharp fODF is obtained because a single fiber *response* function is injected as *a priori* knowledge. In the SDTModel, this response is a @@ -408,9 +404,7 @@ def __init__( References ---------- - .. [1] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and - Probabilistic Tractography Based on Complex Fibre Orientation - Distributions. + .. footbibliography:: """ SphHarmModel.__init__(self, gtab) @@ -511,7 +505,8 @@ def forward_sdt_deconv_mat(ratio, l_values, r2_term=False): term in the integral. For example, DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs. This results in using the proper analytical response function solution solving from the single-fiber ODF with the r^2 term. - This derivation is not published anywhere but is very similar to [1]_. + This derivation is not published anywhere but is very similar to + :footcite:p:`Descoteaux2008b`. Returns ------- @@ -522,7 +517,7 @@ def forward_sdt_deconv_mat(ratio, l_values, r2_term=False): References ---------- - .. [1] Descoteaux, M. PhD Thesis. INRIA Sophia-Antipolis. 2008. + .. footbibliography:: """ if np.any(l_values % 2): @@ -577,11 +572,11 @@ def _solve_cholesky(Q, z): def csdeconv(dwsignal, X, B_reg, tau=0.1, convergence=50, P=None): - r"""Constrained-regularized spherical deconvolution (CSD) [1]_ + r"""Constrained-regularized spherical deconvolution (CSD). Deconvolves the axially symmetric single fiber response function `r_rh` in rotational harmonics coefficients from the diffusion weighted signal in - `dwsignal`. + `dwsignal` :footcite:p:`Tournier2007`. Parameters ---------- @@ -684,9 +679,7 @@ def csdeconv(dwsignal, X, B_reg, tau=0.1, convergence=50, P=None): References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of the - fibre orientation distribution in diffusion MRI: Non-negativity - constrained super-resolved spherical deconvolution. + .. footbibliography:: """ mu = 1e-5 @@ -748,7 +741,10 @@ def csdeconv(dwsignal, X, B_reg, tau=0.1, convergence=50, P=None): def odf_deconv(odf_sh, R, B_reg, lambda_=1.0, tau=0.1, r2_term=False): r"""ODF constrained-regularized spherical deconvolution using - the Sharpening Deconvolution Transform (SDT) [1]_, [2]_. + the Sharpening Deconvolution Transform (SDT). + + See :footcite:p:`Tuch2004` and :footcite:p:`Descoteaux2009` for further + details about the method. Parameters ---------- @@ -767,16 +763,17 @@ def odf_deconv(odf_sh, R, B_reg, lambda_=1.0, tau=0.1, r2_term=False): threshold (``tau *max(fODF)``) controlling the amplitude below which the corresponding fODF is assumed to be zero. r2_term : bool - True if ODF is computed from model that uses the $r^2$ term in the - integral. Recall that Tuch's ODF (used in Q-ball Imaging [1]_) and - the true normalized ODF definition differ from a $r^2$ term in the ODF - integral. The original Sharpening Deconvolution Transform (SDT) - technique [2]_ is expecting Tuch's ODF without the $r^2$ (see [3]_ for - the mathematical details). Now, this function supports ODF that have - been computed using the $r^2$ term because the proper analytical - response function has be derived. For example, models such as DSI, - GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved - with the r2_term=True. + True if ODF is computed from model that uses the $r^2$ term in the + integral. Recall that Tuch's ODF (used in Q-ball Imaging + :footcite:p:`Tuch2004`) and the true normalized ODF definition differ + from a $r^2$ term in the ODF integral. The original Sharpening + Deconvolution Transform (SDT) technique :footcite:p:`Descoteaux2009` + is expecting Tuch's ODF without the $r^2$ (see + :footcite:p:`Descoteaux2008b` for the mathematical details). Now, this + function supports ODF that have been computed using the $r^2$ term + because the proper analytical response function has be derived. For + example, models such as DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, + should now be deconvolved with the r2_term=True. Returns ------- @@ -789,11 +786,7 @@ def odf_deconv(odf_sh, R, B_reg, lambda_=1.0, tau=0.1, r2_term=False): References ---------- - .. [1] Tuch, D. MRM 2004. Q-Ball Imaging. - .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and - Probabilistic Tractography Based on Complex Fibre Orientation - Distributions - .. [3] Descoteaux, M, PhD thesis, INRIA Sophia-Antipolis, 2008. + .. footbibliography:: """ # In ConstrainedSDTModel.fit, odf_sh is divided by its norm (Z) and # sometimes the norm is 0 which creates NaNs. @@ -859,7 +852,7 @@ def odf_sh_to_sharp( tau=0.1, r2_term=False, ): - r"""Sharpen odfs using the sharpening deconvolution transform [2]_ + r"""Sharpen odfs using the sharpening deconvolution transform. This function can be used to sharpen any smooth ODF spherical function. In theory, this should only be used to sharpen QballModel ODFs, but in @@ -867,6 +860,8 @@ def odf_sh_to_sharp( ODF-like spherical function. The constrained-regularization is stable and will not only sharpen the ODF peaks but also regularize the noisy peaks. + See :footcite:p:`Descoteaux2009` for further details about the method. + Parameters ---------- odfs_sh : ndarray (``(sh_order_max + 1)*(sh_order_max + 2)/2``, ) @@ -876,9 +871,10 @@ def odf_sh_to_sharp( basis : {None, 'tournier07', 'descoteaux07'} different spherical harmonic basis: ``None`` for the default DIPY basis, - ``tournier07`` for the Tournier 2007 [4]_ basis, and - ``descoteaux07`` for the Descoteaux 2007 [3]_ basis - (``None`` defaults to ``descoteaux07``). + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007` basis, + and ``descoteaux07`` for the Descoteaux 2007 + :footcite:p:`Descoteaux2007` basis (``None`` defaults to + ``descoteaux07``). ratio : float, ratio of the smallest vs the largest eigenvalue of the single prolate tensor response function (:math:`\frac{\lambda_2}{\lambda_1}`) @@ -890,16 +886,17 @@ def odf_sh_to_sharp( tau parameter in the L matrix construction (see odfdeconv) (default 0.1) r2_term : bool - True if ODF is computed from model that uses the $r^2$ term in the - integral. Recall that Tuch's ODF (used in Q-ball Imaging [1]_) and - the true normalized ODF definition differ from a $r^2$ term in the ODF - integral. The original Sharpening Deconvolution Transform (SDT) - technique [2]_ is expecting Tuch's ODF without the $r^2$ (see [3]_ for - the mathematical details). Now, this function supports ODF that have - been computed using the $r^2$ term because the proper analytical - response function has be derived. For example, models such as DSI, - GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved - with the r2_term=True. + True if ODF is computed from model that uses the $r^2$ term in the + integral. Recall that Tuch's ODF (used in Q-ball Imaging + :footcite:p:`Tuch2004`) and the true normalized ODF definition differ + from a $r^2$ term in the ODF integral. The original Sharpening + Deconvolution Transform (SDT) technique :footcite:p:`Descoteaux2009` is + expecting Tuch's ODF without the $r^2$ (see :footcite:p:`Descoteaux2007` + for the mathematical details). Now, this function supports ODF that + have been computed using the $r^2$ term because the proper analytical + response function has be derived. For example, models such as DSI, + GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved + with the r2_term=True. Returns ------- @@ -908,17 +905,7 @@ def odf_sh_to_sharp( References ---------- - .. [1] Tuch, D. MRM 2004. Q-Ball Imaging. - .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and - Probabilistic Tractography Based on Complex Fibre Orientation - Distributions - .. [3] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [4] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. + .. footbibliography:: """ r, theta, phi = cart2sphere(sphere.x, sphere.y, sphere.z) @@ -972,13 +959,11 @@ def mask_for_response_ssst(gtab, data, roi_center=None, roi_radii=10, fa_thr=0.7 returning a mask of voxels within a ROI, that have a FA value above a given threshold. For example we can use a ROI (20x20x20) at the center of the volume and store the signal values for the voxels with - FA values higher than 0.7 (see [1]_). + FA values higher than 0.7 (see :footcite:p:`Tournier2004`). References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the - fiber orientation density function from diffusion-weighted MRI - data using spherical deconvolution + .. footbibliography:: """ if len(data.shape) < 4: @@ -1040,8 +1025,8 @@ def response_from_mask_ssst(gtab, data, mask): fiber response function. In order to do this, we look for voxels with very anisotropic configurations. This information can be obtained by using csdeconv.mask_for_response_ssst() through a mask of selected voxels - (see[1]_). The present function uses such a mask to compute the ssst - response function. + (see :footcite:p:`Tournier2004`). The present function uses such a mask to + compute the ssst response function. For the response we also need to find the average S0 in the ROI. This is possible using `gtab.b0s_mask()` we can find all the S0 volumes (which @@ -1055,9 +1040,7 @@ def response_from_mask_ssst(gtab, data, mask): References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the - fiber orientation density function from diffusion-weighted MRI - data using spherical deconvolution + .. footbibliography:: """ ten = TensorModel(gtab) @@ -1148,7 +1131,9 @@ def recursive_response( num_processes=None, sphere=default_sphere, ): - """Recursive calibration of response function using peak threshold + """Recursive calibration of response function using peak threshold. + + See :footcite:p:`Tax2014` for further details about the method. Parameters ---------- @@ -1164,7 +1149,8 @@ def recursive_response( maximal spherical harmonics order (l). Default: 8 peak_thr : float, optional peak threshold, how large the second peak can be relative to the first - peak in order to call it a single fiber population [1]. Default: 0.01 + peak in order to call it a single fiber population + :footcite:p:`Tax2014`. Default: 0.01 init_fa : float, optional FA of the initial 'fat' response function (tensor). Default: 0.08 init_trace : float, optional @@ -1197,13 +1183,12 @@ def recursive_response( It is dependent on the dataset (non-informed used subjectivity), and still depends on the diffusion tensor (FA and first eigenvector), which has low accuracy at high b-value. This function recursively - calibrates the response function, for more information see [1]. + calibrates the response function, for more information see + :footcite:p:`Tax2014`. References ---------- - .. [1] Tax, C.M.W., et al. NeuroImage 2014. Recursive calibration of - the fiber response function for spherical deconvolution of - diffusion MRI data. + .. footbibliography:: """ S0 = 1.0 evals = fa_trace_to_lambdas(init_fa, init_trace) diff --git a/dipy/reconst/cti.py b/dipy/reconst/cti.py index 04213a2bb0..f3ba9ae61d 100644 --- a/dipy/reconst/cti.py +++ b/dipy/reconst/cti.py @@ -199,7 +199,9 @@ class CorrelationTensorModel(ReconstModel): """Class for the Correlation Tensor Model""" def __init__(self, gtab1, gtab2, fit_method="WLS", *args, **kwargs): - """Correlation Tensor Imaging Model [1]_ + """Correlation Tensor Imaging Model. + + See :footcite:p:`NetoHenriques2020` for further details about the model. Parameters ---------- @@ -214,6 +216,9 @@ def __init__(self, gtab1, gtab2, fit_method="WLS", *args, **kwargs): **kwargs Arbitrary keyword arguments passed to the :func:`fit` method. + References + ---------- + .. footbibliography:: """ self.gtab1 = gtab1 self.gtab2 = gtab2 @@ -363,7 +368,7 @@ def K_aniso(self): Notes ----- - The $K_{aniso}$ is defined as [1]_: + The $K_{aniso}$ is defined as :footcite:p:`NetoHenriques2020`: .. math:: @@ -377,9 +382,7 @@ def K_aniso(self): References ---------- - .. [1] [NetoHe2020] Henriques, R.N., Jespersen, S.N., Shemesh, N., 2020. - Correlation tensor magnetic resonance imaging. Neuroimage 211. - doi: 10.1016/j.neuroimage.2020.116605 + .. footbibliography:: """ C = self.ct D = self.quadratic_form diff --git a/dipy/reconst/dki.py b/dipy/reconst/dki.py index d71b24b1f3..76833bf303 100644 --- a/dipy/reconst/dki.py +++ b/dipy/reconst/dki.py @@ -60,9 +60,10 @@ def _positive_evals(L1, L2, L3, er=2e-7): def carlson_rf(x, y, z, errtol=3e-4): - r"""Compute the Carlson's incomplete elliptic integral of the first kind + r"""Compute the Carlson's incomplete elliptic integral of the first kind. - Carlson's incomplete elliptic integral of the first kind is defined as: + Carlson's incomplete elliptic integral of the first kind is defined as + :footcite:p:`Carlson1995`: .. math:: @@ -92,8 +93,7 @@ def carlson_rf(x, y, z, errtol=3e-4): References ---------- - .. [1] Carlson, B.C., 1994. Numerical computation of real or complex - elliptic integrals. arXiv:math/9409227 [math.CA] + .. footbibliography:: """ xn = x.copy() @@ -133,9 +133,10 @@ def carlson_rf(x, y, z, errtol=3e-4): def carlson_rd(x, y, z, errtol=1e-4): - r"""Compute the Carlson's incomplete elliptic integral of the second kind + r"""Compute the Carlson's incomplete elliptic integral of the second kind. - Carlson's incomplete elliptic integral of the second kind is defined as: + Carlson's incomplete elliptic integral of the second kind is defined as + :footcite:p:`Carlson1995`: .. math:: @@ -165,8 +166,7 @@ def carlson_rd(x, y, z, errtol=1e-4): References ---------- - .. [1] Carlson, B.C., 1994. Numerical computation of real or complex - elliptic integrals. arXiv:math/9409227 [math.CA] + .. footbibliography:: """ xn = x.copy() @@ -242,7 +242,7 @@ def _F1m(a, b, c): Notes ----- - Function $F_1$ is defined as [1]_: + Function $F_1$ is defined as :footcite:p:`Tabesh2011`: .. math:: @@ -258,9 +258,7 @@ def _F1m(a, b, c): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 + .. footbibliography:: """ # Eigenvalues are considered equal if they are not 2.5% different to each @@ -344,7 +342,7 @@ def _F2m(a, b, c): Notes ----- - Function $F_2$ is defined as [1]_: + Function $F_2$ is defined as :footcite:p:`Tabesh2011`: .. math:: @@ -358,9 +356,7 @@ def _F2m(a, b, c): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 + .. footbibliography:: """ # Eigenvalues are considered equal if they are not 2.5% different to each @@ -396,7 +392,7 @@ def _F2m(a, b, c): L1 = a[cond2] L3 = (c[cond2] + b[cond2]) / 2.0 - # Compute alfa [1]_ + # Compute alfa :footcite:p:`Tabesh2011` x = 1.0 - (L1 / L3) alpha = np.zeros(len(L1)) for i in range(len(x)): @@ -469,6 +465,9 @@ def directional_diffusion_variance(kt, V): r"""Calculate the apparent diffusion variance (adv) in each direction of a sphere for a single voxel + See :footcite:p:`Jensen2005`, :footcite:p:`NetoHenriques2015`, and + :footcite:p:`NetoHenriques2021` for further details about the method. + Parameters ---------- kt : array (15,) @@ -484,18 +483,7 @@ def directional_diffusion_variance(kt, V): References ---------- - .. [1] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). - Exploring the 3D geometry of the diffusion kurtosis tensor - - Impact on the development of robust tractography procedures and - novel biomarkers, NeuroImage 111: 85-99 + .. footbibliography:: """ adv = ( V[:, 0] * V[:, 0] * V[:, 0] * V[:, 0] * kt[0] @@ -522,7 +510,10 @@ def directional_kurtosis( dt, md, kt, V, min_diffusivity=0, min_kurtosis=-3 / 7, adc=None, adv=None ): r"""Calculate the apparent kurtosis coefficient (akc) in each direction of - a sphere for a single voxel [1]_,[2]_ + a sphere for a single voxel. + + See :footcite:p:`NetoHenriques2015` and :footcite:p:`NetoHenriques2021` for + further details about the method. Parameters ---------- @@ -545,7 +536,7 @@ def directional_kurtosis( kurtosis-based measures, directional kurtosis values smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined - to spherical pores [3]_) + to spherical pores :footcite:p:`Jensen2005`). adc : ndarray(g,) (optional) Apparent diffusion coefficient (ADC) in all g directions of a sphere for a single voxel. @@ -561,18 +552,7 @@ def directional_kurtosis( References ---------- - .. [1] Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). - Exploring the 3D geometry of the diffusion kurtosis tensor - - Impact on the development of robust tractography procedures and - novel biomarkers, NeuroImage 111: 85-99 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ if adc is None: @@ -592,7 +572,10 @@ def apparent_kurtosis_coef( dki_params, sphere, min_diffusivity=0, min_kurtosis=-3.0 / 7 ): r"""Calculate the apparent kurtosis coefficient (AKC) in each direction - of a sphere [1]_,[2]_ + of a sphere. + + See :footcite:p:`NetoHenriques2015` and :footcite:p:`NetoHenriques2021` for + further details about the method. Parameters ---------- @@ -617,7 +600,7 @@ def apparent_kurtosis_coef( kurtosis-based measures, directional kurtosis values smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined - to spherical pores [3]_) + to spherical pores :footcite:p:`Jensen2005`). Returns ------- @@ -627,7 +610,7 @@ def apparent_kurtosis_coef( Notes ----- For each sphere direction with coordinates $(n_{1}, n_{2}, n_{3})$, the - calculation of AKC is done using formula [1]_: + calculation of AKC is done using formula :footcite:p:`NetoHenriques2015`: .. math:: @@ -645,18 +628,7 @@ def apparent_kurtosis_coef( References ---------- - .. [1] Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). - Exploring the 3D geometry of the diffusion kurtosis tensor - - Impact on the development of robust tractography procedures and - novel biomarkers, NeuroImage 111: 85-99 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ # Flat parameters @@ -699,7 +671,10 @@ def apparent_kurtosis_coef( def mean_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=3, analytical=True): - r""" Compute mean kurtosis (MK) from the kurtosis tensor [1]_,[2]_ + r""" Compute mean kurtosis (MK) from the kurtosis tensor. + + See :footcite:p:`Tabesh2011` and :footcite:p:`NetoHenriques2021` for further + details about the method. Parameters ---------- @@ -715,7 +690,8 @@ def mean_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=3, analytical= To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions - that consist of water confined to spherical pores [3]_) + that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than `max_kurtosis` are replaced with @@ -733,17 +709,19 @@ def mean_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=3, analytical= ----- The MK is defined as the average of directional kurtosis coefficients across all spatial directions, which can be formulated by the following - surface integral [1]_,[2]_: + surface integral :footcite:p:`Tabesh2011`, :footcite:p:`NetoHenriques2021`: .. math:: MK \equiv \frac{1}{4\pi} \int d\Omega_\mathbf{n} K(\mathbf{n}) This integral can be numerically solved by averaging directional - kurtosis values sampled for directions of a spherical t-design [4]_. + kurtosis values sampled for directions of a spherical t-design + :footcite:p:`Hardin1996`. Alternatively, MK can be solved from the analytical solution derived by - Tabesh et al. [1]_,[2]_. This solution is given by: + :footcite:p:`Tabesh2011`, :footcite:p:`NetoHenriques2021`. This solution is + given by: .. math:: @@ -782,20 +760,7 @@ def mean_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=3, analytical= References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [4] Hardin, R.H., Sloane, N.J.A., 1996. McLaren's Improved Snub Cube and - Other New Spherical Designs in Three Dimensions. Discrete and - Computational Geometry 15, 429-441. + .. footbibliography:: """ # Flat parameters. For numpy versions more recent than 1.6.0, this step @@ -864,7 +829,7 @@ def _G1m(a, b, c): Notes ----- - Function $G_1$ is defined as [1]_: + Function $G_1$ is defined as :footcite:p:`Tabesh2011`: .. math:: @@ -876,9 +841,7 @@ def _G1m(a, b, c): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 + .. footbibliography:: """ # Float error used to compare two floats, abs(l1 - l2) < er for l1 = l2 @@ -933,7 +896,7 @@ def _G2m(a, b, c): Notes ----- - Function $G_2$ is defined as [1]_: + Function $G_2$ is defined as :footcite:p:`Tabesh2011`: .. math:: @@ -943,9 +906,7 @@ def _G2m(a, b, c): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 + .. footbibliography:: """ # Float error used to compare two floats, abs(l1 - l2) < er for l1 = l2 @@ -983,7 +944,10 @@ def _G2m(a, b, c): def radial_kurtosis( dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True ): - r"""Compute radial kurtosis (RK) of a diffusion kurtosis tensor [1]_,[2]_ + r"""Compute radial kurtosis (RK) of a diffusion kurtosis tensor. + + See :footcite:p:`Tabesh2011` and :footcite:p:`NetoHenriques2021` for further + details about the method. Parameters ---------- @@ -1000,7 +964,8 @@ def radial_kurtosis( To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions - that consist of water confined to spherical pores [3]_) + that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are larger than `max_kurtosis` are replaced with @@ -1017,7 +982,8 @@ def radial_kurtosis( Notes ----- RK is defined as the average of the directional kurtosis perpendicular - to the fiber's main direction e1 [1]_, [2]_: + to the fiber's main direction e1 :footcite:p:`Tabesh2011`, + :footcite:p:`NetoHenriques2021`: .. math:: @@ -1025,9 +991,11 @@ def radial_kurtosis( \delta (\mathbf{\theta}\cdot \mathbf{e}_1) This equation can be numerically computed by averaging apparent - directional kurtosis samples for directions perpendicular to e1. [2]_ + directional kurtosis samples for directions perpendicular to e1 + :footcite:p:`NetoHenriques2021`. - Otherwise, RK can be calculated from its analytical solution [1]_: + Otherwise, RK can be calculated from its analytical solution + :footcite:p:`Tabesh2011`: .. math:: @@ -1055,17 +1023,7 @@ def radial_kurtosis( References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ outshape = dki_params.shape[:-1] @@ -1125,7 +1083,10 @@ def radial_kurtosis( def axial_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): - r"""Compute axial kurtosis (AK) from the kurtosis tensor [1]_, [2]_ + r"""Compute axial kurtosis (AK) from the kurtosis tensor. + + See :footcite:p:`Tabesh2011` and :footcite:`NetoHenriques2021` for further + details about the method. Parameters ---------- @@ -1142,7 +1103,8 @@ def axial_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytica To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions - that consist of water confined to spherical pores [3]_) + that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are larger than `max_kurtosis` are replaced with @@ -1161,15 +1123,18 @@ def axial_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytica Notes ----- AK is defined as the directional kurtosis parallel to the fiber's main - direction e1 [1]_, [2]_. You can compute AK using to approaches: + direction e1 :footcite:p:`Tabesh2011`, :footcite:`NetoHenriques2021`. You + can compute AK using to approaches: - 1) AK is calculated from rotated diffusion kurtosis tensor [1]_, i.e.: + 1) AK is calculated from rotated diffusion kurtosis tensor + :footcite:p:`Tabesh2011`, i.e.: .. math:: AK = \hat{W}_{1111} \frac{(\lambda_{1}+\lambda_{2}+\lambda_{3})^2}{(9 \lambda_{1}^2)} - 2) AK can be sampled from the principal axis of the diffusion tensor [2]_: + 2) AK can be sampled from the principal axis of the diffusion tensor + :footcite:`NetoHenriques2021`: .. math:: AK = K(\mathbf{e}_1) @@ -1181,17 +1146,7 @@ def axial_kurtosis(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytica References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ # Flat parameters @@ -1341,7 +1296,9 @@ def _voxel_kurtosis_maximum(dt, md, kt, sphere, gtol=1e-2): def kurtosis_maximum(dki_params, sphere="repulsion100", gtol=1e-2, mask=None): - """Compute kurtosis maximum value [1]_ + """Compute kurtosis maximum value. + + See :footcite:`NetoHenriques2021` for further details about the method. Parameters ---------- @@ -1376,10 +1333,7 @@ def kurtosis_maximum(dki_params, sphere="repulsion100", gtol=1e-2, mask=None): References ---------- - .. [1] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ shape = dki_params.shape[:-1] @@ -1416,7 +1370,9 @@ def kurtosis_maximum(dki_params, sphere="repulsion100", gtol=1e-2, mask=None): def mean_kurtosis_tensor(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10): - r"""Compute mean of the kurtosis tensor (MKT) [1]_ + r"""Compute mean of the kurtosis tensor (MKT). + + See :footcite:p:`Hansen2013` for further details about the method. Parameters ---------- @@ -1433,7 +1389,8 @@ def mean_kurtosis_tensor(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10): To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions - that consist of water confined to spherical pores [2]_) + that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than `max_kurtosis` are replaced with @@ -1445,7 +1402,7 @@ def mean_kurtosis_tensor(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10): Notes ----- - The MKT is defined as [1]_: + The MKT is defined as :footcite:p:`Hansen2013`: .. math:: @@ -1462,14 +1419,7 @@ def mean_kurtosis_tensor(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10): References ---------- - .. [1] Hansen, B., Lund, T. E., Sangill, R., and Jespersen, S. N. (2013). - Experimentally and computationally fast method for estimation of - a mean kurtosis.Magnetic Resonance in Medicine69, 1754–1760.388 - doi:10.1002/mrm.24743 - .. [2] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ MKT = ( @@ -1495,7 +1445,9 @@ def mean_kurtosis_tensor(dki_params, min_kurtosis=-3.0 / 7, max_kurtosis=10): def radial_tensor_kurtosis(dki_params, *, min_kurtosis=-3.0 / 7, max_kurtosis=10): - r"""Compute the rescaled radial tensor kurtosis (RTK) [1]_ + r"""Compute the rescaled radial tensor kurtosis (RTK). + + See :footcite:p:`Hansen2013` for further details about the method. Parameters ---------- @@ -1524,7 +1476,8 @@ def radial_tensor_kurtosis(dki_params, *, min_kurtosis=-3.0 / 7, max_kurtosis=10 Notes ----- - Rescaled radial tensor kurtosis (RTK) is defined as ([1]_): + Rescaled radial tensor kurtosis (RTK) is defined as + :footcite:p:`Hansen2013`: .. math:: @@ -1536,9 +1489,7 @@ def radial_tensor_kurtosis(dki_params, *, min_kurtosis=-3.0 / 7, max_kurtosis=10 References ---------- - .. [1] Hansen, B., Shemesh, N., and Jespersen, S. N. (2017). - Fast imaging of mean, axial and radial diffusion kurtosis. - Neuroimage 142, 381–393. doi:10.1016/j.neuroimage.2016.08.022 + .. footbibliography:: """ outshape = dki_params.shape[:-1] dki_params = dki_params.reshape((-1, dki_params.shape[-1])) @@ -1581,7 +1532,10 @@ def radial_tensor_kurtosis(dki_params, *, min_kurtosis=-3.0 / 7, max_kurtosis=10 def kurtosis_fractional_anisotropy(dki_params): - r"""Compute the anisotropy of the kurtosis tensor (KFA) [1]_,[2]_ + r"""Compute the anisotropy of the kurtosis tensor (KFA). + + See :footcite:p:`Glenn2015` and :footcite:p:`NetoHenriques2021` for further + details about the method. Parameters ---------- @@ -1600,7 +1554,7 @@ def kurtosis_fractional_anisotropy(dki_params): Notes ----- - The KFA is defined as [1]_: + The KFA is defined as :footcite:p:`Glenn2015`: .. math:: @@ -1609,17 +1563,11 @@ def kurtosis_fractional_anisotropy(dki_params): where $W$ is the kurtosis tensor, MKT the kurtosis tensor mean, $I^{(4)}$ is the fully symmetric rank 2 isotropic tensor and $||...||_F$ is the tensor's - Frobenius norm [1]_. + Frobenius norm :footcite:p:`Glenn2015`. References ---------- - .. [1] Glenn, G. R., Helpern, J. A., Tabesh, A., and Jensen, J. H. (2015). - Quantitative assessment of diffusional kurtosis anisotropy. - NMR in Biomedicine 28, 448–459. doi:10.1002/nbm.3271 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ Wxxxx = dki_params[..., 12] @@ -1680,6 +1628,9 @@ def dki_prediction(dki_params, gtab, S0=1.0): S=S_{0}e^{-bD+\frac{1}{6}b^{2}D^{2}K} + See :footcite:p:`Jensen2005` and :footcite:p:`NetoHenriques2021` for further + details about the method. + Parameters ---------- dki_params : ndarray (x, y, z, 27) or (n, 27) @@ -1703,14 +1654,7 @@ def dki_prediction(dki_params, gtab, S0=1.0): References ---------- - .. [1] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [2] Henriques R, Correia MM, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ evals, evecs, kt = split_dki_param(dki_params) @@ -1749,7 +1693,10 @@ class DiffusionKurtosisModel(ReconstModel): """Class for the Diffusion Kurtosis Model""" def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs): - """Diffusion Kurtosis Tensor Model [1]_, [2]_ + """Diffusion Kurtosis Tensor Model. + + See :footcite:p:`Jensen2005` and :footcite:p:`NetoHenriques2021` for + further details about the model. Parameters ---------- @@ -1761,9 +1708,10 @@ def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs) - 'OLS' or 'ULLS' for ordinary least squares. - 'WLS', 'WLLS' or 'UWLLS' for weighted ordinary least squares. See func:`dki.ls_fit_dki`. - - 'CLS' for LMI constrained ordinary least squares [3]_. + - 'CLS' for LMI constrained ordinary least squares + :footcite:p:`DelaHaije2020`. - 'CWLS' for LMI constrained weighted least squares - [3]_. See func:`dki.cls_fit_dki`. + :footcite:p:`DelaHaije2020`. See func:`dki.cls_fit_dki`. callable has to have the signature: ``fit_method(design_matrix, data, *args, **kwargs)`` @@ -1777,17 +1725,7 @@ def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs) References ---------- - .. [1] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Dela Haije et al. (2020). Enforcing necessary non-negativity - constraints for common diffusion MRI models using sum of squares - programming. NeuroImage 209: 116405. + .. footbibliography:: """ ReconstModel.__init__(self, gtab) @@ -1952,6 +1890,9 @@ def multi_fit(self, data_thres, mask=None): def predict(self, dki_params, S0=1.0): """Predict a signal for this DKI model class instance given parameters + See :footcite:p:`Jensen2005` and :footcite:p:`NetoHenriques2021` for + further details about the method. + Parameters ---------- dki_params : ndarray (x, y, z, 27) or (n, 27) @@ -1969,14 +1910,7 @@ def predict(self, dki_params, S0=1.0): References ---------- - .. [1] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ return dki_prediction(dki_params, self.gtab, S0) @@ -2057,23 +1991,26 @@ def akc(self, sphere): return apparent_kurtosis_coef(self.model_params, sphere) def mk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): - r""" Compute mean kurtosis (MK) from the kurtosis tensor [1]_, [2]_ + r""" Compute mean kurtosis (MK) from the kurtosis tensor. + + See :footcite:t:`Tabesh2011` and :footcite:p:`NetoHenriques2021` for + further details about the method. Parameters ---------- - min_kurtosis : float (optional) + min_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit - for regions that consist of water confined to spherical pores [3]_) - max_kurtosis : float (optional) + for regions that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). + max_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than `max_kurtosis` are replaced - with `max_kurtosis`. Default = 10 - analytical : bool (optional) + with `max_kurtosis`. + analytical : bool, optional If True, MK is calculated using its analytical solution, otherwise - an exact numerical estimator is used (see Notes). Default is set to - True. + an exact numerical estimator is used (see Notes). Returns ------- @@ -2084,17 +2021,19 @@ def mk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): ----- The MK is defined as the average of directional kurtosis coefficients across all spatial directions, which can be formulated by the following - surface integral [1]_, [2]_: + surface integral :footcite:p:`Tabesh2011`, + :footcite:p:`NetoHenriques2021`: .. math:: MK \equiv \frac{1}{4\pi} \int d\Omega_\mathbf{n} K(\mathbf{n}) This integral can be numerically solved by averaging directional - kurtosis values sampled for directions of a spherical t-design [4]_. + kurtosis values sampled for directions of a spherical t-design + :footcite:p:`Hardin1996`. Alternatively, MK can be solved from the analytical solution derived by - Tabesh et al. [1]_. This solution is given by: + :footcite:t:`Tabesh2011`. This solution is given by: .. math:: @@ -2133,40 +2072,31 @@ def mk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [4] Hardin, R.H., Sloane, N.J.A., 1996. McLaren's Improved Snub Cube - and Other New Spherical Designs in Three Dimensions. Discrete - and Computational Geometry 15, 429-441. + .. footbibliography:: """ return mean_kurtosis(self.model_params, min_kurtosis, max_kurtosis, analytical) def ak(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): r""" - Compute axial kurtosis (AK) of a diffusion kurtosis tensor [1]_, [2]_ + Compute axial kurtosis (AK) of a diffusion kurtosis tensor. + + See :footcite:p:`Tabesh2011` and :footcite:p:`NetoHenriques2021` for + further details about the method. Parameters ---------- - min_kurtosis : float (optional) + min_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are smaller than `min_kurtosis` are replaced with -3./7 (theoretical kurtosis limit - for regions that consist of water confined to spherical pores [3]_) - max_kurtosis : float (optional) + for regions that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). + max_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are larger than `max_kurtosis` are replaced with `max_kurtosis`. - analytical : bool (optional) + analytical : bool, optional If True, AK is calculated from rotated diffusion kurtosis tensor, otherwise it will be computed from the apparent diffusion kurtosis values along the principal axis of the diffusion tensor @@ -2180,7 +2110,8 @@ def ak(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): Notes ----- AK is defined as the directional kurtosis parallel to the fiber's main - direction e1 [1]_, [2]_. You can compute AK using to approaches: + direction e1 :footcite:p:`Tabesh2011`, :footcite:p:`NetoHenriques2021`. + You can compute AK using to approaches: 1) AK is calculated from rotated diffusion kurtosis tensor, i.e.: @@ -2200,40 +2131,31 @@ def ak(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ return axial_kurtosis(self.model_params, min_kurtosis, max_kurtosis, analytical) def rk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): - r"""Compute radial kurtosis (RK) of a diffusion kurtosis tensor [1]_ + r"""Compute radial kurtosis (RK) of a diffusion kurtosis tensor. + + See :footcite:p:`Tabesh2011` for further details about the method. Parameters ---------- - min_kurtosis : float (optional) + min_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores - [3]_) - max_kurtosis : float (optional) + :footcite:p:`Jensen2005`). + max_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are larger than `max_kurtosis` are - replaced with `max_kurtosis`. Default = 10 - analytical : bool (optional) + replaced with `max_kurtosis`. + analytical : bool, optional If True, RK is calculated using its analytical solution, otherwise - an exact numerical estimator is used (see Notes). Default is set to - True + an exact numerical estimator is used (see Notes). Returns ------- @@ -2243,7 +2165,8 @@ def rk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): Notes ----- RK is defined as the average of the directional kurtosis perpendicular - to the fiber's main direction e1 [1]_, [2]_: + to the fiber's main direction e1 :footcite:p:`Tabesh2011`, + :footcite:p:`NetoHenriques2021`: .. math:: @@ -2251,9 +2174,11 @@ def rk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): K(\mathbf{\theta}) \delta (\mathbf{\theta}\cdot \mathbf{e}_1) This equation can be numerically computed by averaging apparent - directional kurtosis samples for directions perpendicular to e1 [2]_. + directional kurtosis samples for directions perpendicular to e1 + :footcite:p:`NetoHenriques2021`. - Otherwise, RK can be calculated from its analytical solution [1]_: + Otherwise, RK can be calculated from its analytical solution + :footcite:p:`Tabesh2011`: .. math:: @@ -2282,17 +2207,7 @@ def rk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. - .. [3] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ return radial_kurtosis( @@ -2300,7 +2215,10 @@ def rk(self, min_kurtosis=-3.0 / 7, max_kurtosis=10, analytical=True): ) def kmax(self, sphere="repulsion100", gtol=1e-5, mask=None): - r"""Compute the maximum value of a single voxel kurtosis tensor + """Compute the maximum value of a single voxel kurtosis tensor + + See :footcite:p:`NetoHenriques2021` for further details about the + method. Parameters ---------- @@ -2321,28 +2239,28 @@ def kmax(self, sphere="repulsion100", gtol=1e-5, mask=None): References ---------- - .. [1] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ return kurtosis_maximum(self.model_params, sphere, gtol, mask) def mkt(self, min_kurtosis=-3.0 / 7, max_kurtosis=10): - r"""Compute mean of the kurtosis tensor (MKT) [1]_ + r"""Compute mean of the kurtosis tensor (MKT). + + See :footcite:p:`Hansen2013` for further details about the method. Parameters ---------- - min_kurtosis : float (optional) + min_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. Default = -3./7 (theoretical kurtosis limit - for regions that consist of water confined to spherical pores [2]_) - max_kurtosis : float (optional) + for regions that consist of water confined to spherical pores + :footcite:p:`Jensen2005`). + max_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than `max_kurtosis` are replaced - with `max_kurtosis`. Default = 10 + with `max_kurtosis`. Returns ------- @@ -2351,7 +2269,7 @@ def mkt(self, min_kurtosis=-3.0 / 7, max_kurtosis=10): Notes ----- - The MKT is defined as [1]_: + The MKT is defined as :footcite:p:`Hansen2013`: .. math:: @@ -2368,27 +2286,22 @@ def mkt(self, min_kurtosis=-3.0 / 7, max_kurtosis=10): References ---------- - .. [1] Hansen, B., Lund, T. E., Sangill, R., and Jespersen, S. N. 2013. - Experimentally and computationally fast method for estimation - of a mean kurtosis. Magnetic Resonance in Medicine69, 1754–1760. - 388. doi:10.1002/mrm.24743 - .. [2] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 + .. footbibliography:: """ return mean_kurtosis_tensor(self.model_params, min_kurtosis, max_kurtosis) def rtk(self, *, min_kurtosis=-3.0 / 7, max_kurtosis=10): - r"""Compute the rescaled radial tensor kurtosis (RTK) [1]_ + r"""Compute the rescaled radial tensor kurtosis (RTK). + + See :footcite:p:`Hansen2016b` for further details about the method. Parameters ---------- - min_kurtosis : float (optional) + min_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are smaller than `min_kurtosis` are replaced with `min_kurtosis`. - max_kurtosis : float (optional) + max_kurtosis : float, optional To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are larger than `max_kurtosis` are replaced with `max_kurtosis`. @@ -2400,7 +2313,8 @@ def rtk(self, *, min_kurtosis=-3.0 / 7, max_kurtosis=10): Notes ----- - Rescaled radial tensor kurtosis (RTK) is defined as ([1]_): + Rescaled radial tensor kurtosis (RTK) is defined as + :footcite:p:`Hansen2016b`: .. math:: @@ -2412,10 +2326,7 @@ def rtk(self, *, min_kurtosis=-3.0 / 7, max_kurtosis=10): References ---------- - .. [1] Hansen, B., Shemesh, N., and Jespersen, S. N. (2017). - Fast imaging of mean, axial and radial diffusion kurtosis. - Neuroimage 142, 381–393. - doi:10.1016/j.neuroimage.2016.08.022 + .. footbibliography:: """ return radial_tensor_kurtosis( self.model_params, min_kurtosis=min_kurtosis, max_kurtosis=max_kurtosis @@ -2423,11 +2334,13 @@ def rtk(self, *, min_kurtosis=-3.0 / 7, max_kurtosis=10): @property def kfa(self): - r"""Return the kurtosis tensor (KFA) [1]_ + r"""Return the kurtosis tensor (KFA). + + See :footcite:p:`Glenn2015` for further details about the method. Notes ----- - The KFA is defined as [1]_: + The KFA is defined as :footcite:p:`Glenn2015`: .. math:: @@ -2436,13 +2349,11 @@ def kfa(self): where $W$ is the kurtosis tensor, MKT the kurtosis tensor mean, $I^{(4)}$ is the fully symmetric rank 2 isotropic tensor and $||...||_F$ is the - tensor's Frobenius norm [1]_. + tensor's Frobenius norm :footcite:p:`Glenn2015`. References ---------- - .. [1] Glenn, G. R., Helpern, J. A., Tabesh, A., and Jensen, J. H. - (2015). Quantitative assessment of diffusional kurtosis - anisotropy. NMR in Biomedicine 28, 448–459. doi:10.1002/nbm.3271 + .. footbibliography: """ return kurtosis_fractional_anisotropy(self.model_params) @@ -2451,6 +2362,9 @@ def predict(self, gtab, S0=1.0): r"""Given a DKI model fit, predict the signal on the vertices of a gradient table + See :footcite:p:`Jensen2005` and :footcite:p:`NetoHenriques2021` for + further details about the method. + Parameters ---------- gtab : a GradientTable class instance @@ -2488,14 +2402,7 @@ def predict(self, gtab, S0=1.0): References ---------- - .. [1] Jensen JH, Helpern JA, Ramani A, Lu H, Kaczynski K, (2005). - Diffusional kurtosis imaging: The quantification of non-gaussian - water diffusion by means of magnetic resonance imaging. Magnetic - Resonance in Medicine 53(6): 1432-1440 - .. [2] Henriques R, Correia M, Marrale M, Huber E, Kruper J, Koudoro S, - Yeatman JD, Garyfallidis E, Rokem A (2021). Diffusional Kurtosis - Imaging in the Diffusion Imaging in Python Project. Frontiers in - Human Neuroscience 15: 675433. + .. footbibliography:: """ return dki_prediction(self.model_params, gtab, S0) @@ -2558,7 +2465,9 @@ def ls_fit_dki( min_diffusivity=0, ): r"""Compute the diffusion and kurtosis tensors using an ordinary or - weighted linear least squares approach [1]_ + weighted linear least squares approach. + + See :footcite:p:`Veraart2013` for further details about the method. Parameters ---------- @@ -2592,10 +2501,7 @@ def ls_fit_dki( References ---------- - [1] Veraart, J., Sijbers, J., Sunaert, S., Leemans, A., Jeurissen, B., - (2013). Weighted linear least squares estimation of diffusion MRI - parameters: Strengths, limitations, and pitfalls. Magn Reson Med 81, - 335-346. + .. footbibliography:: """ # Set up least squares problem @@ -2633,7 +2539,9 @@ def cls_fit_dki( cvxpy_solver=None, ): r"""Compute the diffusion and kurtosis tensors using a constrained - ordinary or weighted linear least squares approach [1]_ + ordinary or weighted linear least squares approach. + + See :footcite:p:`DelaHaije2020` for further details about the method. Parameters ---------- @@ -2674,9 +2582,7 @@ def cls_fit_dki( References ---------- - .. [1] Dela Haije et al. (2020). Enforcing necessary non-negativity - constraints for common diffusion MRI models using sum of squares - programming. NeuroImage 209: 116405. + .. footbibliography:: """ # Set up least squares problem A = design_matrix @@ -2705,6 +2611,8 @@ def Wrotate(kt, Basis): r""" Rotate a kurtosis tensor from the standard Cartesian coordinate system to another coordinate system basis + See :footcite:p:`Hui2008` for further details about the method. + Parameters ---------- kt : (15,) @@ -2738,9 +2646,7 @@ def Wrotate(kt, Basis): References ---------- - [1] Hui ES, Cheung MM, Qi L, Wu EX, 2008. Towards better MR - characterization of neural tissues using directional diffusion kurtosis - analysis. Neuroimage 42(1): 122-34 + .. footbibliography:: """ inds = np.array( @@ -2804,6 +2710,8 @@ def Wrotate_element(kt, indi, indj, indk, indl, B): r"""Compute the specified index element of a kurtosis tensor rotated to the coordinate system basis B + See :footcite:p:`Hui2008` for further details about the method. + Parameters ---------- kt : ndarray (x, y, z, 15) or (n, 15) @@ -2831,9 +2739,7 @@ def Wrotate_element(kt, indi, indj, indk, indl, B): References ---------- - [1] Hui ES, Cheung MM, Qi L, Wu EX, 2008. Towards better MR - characterization of neural tissues using directional diffusion kurtosis - analysis. Neuroimage 42(1): 122-34 + .. footbibliography:: """ Wre = 0 diff --git a/dipy/reconst/dki_micro.py b/dipy/reconst/dki_micro.py index cefdd8661d..d66b8bad29 100644 --- a/dipy/reconst/dki_micro.py +++ b/dipy/reconst/dki_micro.py @@ -30,7 +30,9 @@ def axonal_water_fraction(dki_params, sphere="repulsion100", gtol=1e-2, mask=None): - """Computes the axonal water fraction from DKI [1]_. + """Computes the axonal water fraction from DKI. + + See :footcite:p:`Fieremans2011` for further details about the method. Parameters ---------- @@ -62,9 +64,7 @@ def axonal_water_fraction(dki_params, sphere="repulsion100", gtol=1e-2, mask=Non References ---------- - .. [1] Fieremans E, Jensen JH, Helpern JA, 2011. White matter - characterization with diffusional kurtosis imaging. - Neuroimage 58(1):177-88. doi: 10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ kt_max = kurtosis_maximum(dki_params, sphere=sphere, gtol=gtol, mask=mask) @@ -75,7 +75,9 @@ def axonal_water_fraction(dki_params, sphere="repulsion100", gtol=1e-2, mask=Non def diffusion_components(dki_params, sphere="repulsion100", awf=None, mask=None): """Extracts the restricted and hindered diffusion tensors of well aligned - fibers from diffusion kurtosis imaging parameters [1]_. + fibers from diffusion kurtosis imaging parameters. + + See :footcite:p:`Fieremans2011` for further details about the method. Parameters ---------- @@ -89,7 +91,8 @@ def diffusion_components(dki_params, sphere="repulsion100", awf=None, mask=None) 3) Fifteen elements of the kurtosis tensor sphere : Sphere class instance, optional The sphere providing sample directions to sample the restricted and - hindered cellular diffusion tensors. For more details see [1]_. + hindered cellular diffusion tensors. For more details see + :footcite:p:`Fieremans2011`. awf : ndarray (optional) Array containing values of the axonal water fraction that has the shape dki_params.shape[:-1]. If not given this will be automatically computed @@ -107,15 +110,14 @@ def diffusion_components(dki_params, sphere="repulsion100", awf=None, mask=None) Notes ----- - In the original article of DKI microstructural model [1]_, the hindered and - restricted tensors were defined as the intra-cellular and extra-cellular - diffusion compartments respectively. + In the original article of DKI microstructural model + :footcite:p:`Fieremans2011`, the hindered and restricted tensors were + defined as the intra-cellular and extra-cellular diffusion compartments + respectively. References ---------- - .. [1] Fieremans E, Jensen JH, Helpern JA, 2011. White matter - characterization with diffusional kurtosis imaging. - Neuroimage 58(1):177-88. doi: 10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ shape = dki_params.shape[:-1] @@ -226,9 +228,14 @@ def dkimicro_prediction(params, gtab, S0=1): direction, $f$ is the volume fraction of the restricted diffusion compartment (also known as the axonal water fraction). - 2) In the original article of DKI microstructural model [1]_, the hindered - and restricted tensors were defined as the intra-cellular and - extra-cellular diffusion compartments respectively. + 2) In the original article of DKI microstructural model + :footcite:p:`Fieremans2011`, the hindered and restricted tensors were + defined as the intra-cellular and extra-cellular diffusion compartments + respectively. + + References + ---------- + .. footbibliography:: """ # Initialize pred_sig @@ -320,7 +327,9 @@ class KurtosisMicrostructureModel(DiffusionKurtosisModel): """Class for the Diffusion Kurtosis Microstructural Model""" def __init__(self, gtab, fit_method="WLS", *args, **kwargs): - """Initialize a KurtosisMicrostrutureModel class instance [1]_. + """Initialize a KurtosisMicrostrutureModel class instance. + + See :footcite:p:`Fieremans2011` for further details about the model. Parameters ---------- @@ -345,9 +354,7 @@ def __init__(self, gtab, fit_method="WLS", *args, **kwargs): References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ DiffusionKurtosisModel.__init__(self, gtab, fit_method="WLS", *args, **kwargs) @@ -444,15 +451,14 @@ def predict(self, params, S0=1.0): Notes ----- - In the original article of DKI microstructural model [1]_, the hindered - and restricted tensors were defined as the intra-cellular and - extra-cellular diffusion compartments respectively. + In the original article of DKI microstructural model + :footcite:p:`Fieremans2011`, the hindered and restricted tensors were + defined as the intra-cellular and extra-cellular diffusion compartments + respectively. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return dkimicro_prediction(params, self.gtab, S0) @@ -482,15 +488,14 @@ def __init__(self, model, model_params): Notes ----- - In the original article of DKI microstructural model [1]_, the hindered - and restricted tensors were defined as the intra-cellular and - extra-cellular diffusion compartments respectively. + In the original article of DKI microstructural model + :footcite:p:`Fieremans2011`, the hindered and restricted tensors were + defined as the intra-cellular and extra-cellular diffusion compartments + respectively. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ DiffusionKurtosisFit.__init__(self, model, model_params) @@ -501,14 +506,13 @@ def awf(self): Notes ----- - The volume fraction of the restricted diffusion compartment can be seem - as the volume fraction of the intra-cellular compartment [1]_. + The volume fraction of the restricted diffusion compartment can be seen + as the volume fraction of the intra-cellular compartment + :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return self.model_params[..., 27] @@ -518,14 +522,12 @@ def restricted_evals(self): Notes ----- - The restricted diffusion tensor can be seem as the tissue's - intra-cellular diffusion compartment [1]_. + The restricted diffusion tensor can be seen as the tissue's + intra-cellular diffusion compartment :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ self._is_awfonly() return _compartments_eigenvalues(self.model_params[..., 34:40]) @@ -536,14 +538,12 @@ def hindered_evals(self): Notes ----- - The hindered diffusion tensor can be seem as the tissue's - extra-cellular diffusion compartment [1]_. + The hindered diffusion tensor can be seen as the tissue's + extra-cellular diffusion compartment :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ self._is_awfonly() return _compartments_eigenvalues(self.model_params[..., 28:34]) @@ -551,13 +551,13 @@ def hindered_evals(self): @property def axonal_diffusivity(self): """Returns the axonal diffusivity defined as the restricted diffusion - tensor trace [1]_. + tensor trace. + + See :footcite:p:`Fieremans2011` for further details about the method. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return trace(self.restricted_evals) @@ -567,14 +567,12 @@ def hindered_ad(self): Notes ----- - The hindered diffusion tensor can be seem as the tissue's - extra-cellular diffusion compartment [1]_. + The hindered diffusion tensor can be seen as the tissue's + extra-cellular diffusion compartment :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return axial_diffusivity(self.hindered_evals) @@ -584,14 +582,12 @@ def hindered_rd(self): Notes ----- - The hindered diffusion tensor can be seem as the tissue's - extra-cellular diffusion compartment [1]_. + The hindered diffusion tensor can be seen as the tissue's + extra-cellular diffusion compartment :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return radial_diffusivity(self.hindered_evals) @@ -599,18 +595,18 @@ def hindered_rd(self): def tortuosity(self): """Returns the tortuosity of the hindered diffusion which is defined by ADe / RDe, where ADe and RDe are the axial and radial diffusivities - of the hindered compartment [1]_. + of the hindered compartment. + + See :footcite:p:`Fieremans2011` for further details about the method. Notes ----- - The hindered diffusion tensor can be seem as the tissue's - extra-cellular diffusion compartment [1]_. + The hindered diffusion tensor can be seen as the tissue's + extra-cellular diffusion compartment :footcite:p:`Fieremans2011`. References ---------- - .. [1] Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter - Characterization with Diffusion Kurtosis Imaging. Neuroimage - 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006 + .. footbibliography:: """ return tortuosity(self.hindered_ad, self.hindered_rd) diff --git a/dipy/reconst/dsi.py b/dipy/reconst/dsi.py index b8e71c9b50..e0eb5725d9 100644 --- a/dipy/reconst/dsi.py +++ b/dipy/reconst/dsi.py @@ -33,11 +33,13 @@ def __init__( where $\mathbf{r}$ is the displacement vector and $\mathbf{q}$ is the wave vector which corresponds to different gradient directions. Method used to calculate the ODFs. Here we implement the method proposed by - Wedeen et al. [1]_. + :footcite:t:`Wedeen2005`. The main assumption for this model is fast gradient switching and that the acquisition gradients will sit on a keyhole Cartesian grid in - q_space [3]_. + q_space :footcite:p:`Garyfallidis2012b`. + + See also :footcite:p:`CanalesRodriguez2010`. Parameters ---------- @@ -59,14 +61,7 @@ def __init__( References ---------- - .. [1] Wedeen V.J et al., "Mapping Complex Tissue Architecture With - Diffusion Spectrum Magnetic Resonance Imaging", MRM 2005. - - .. [2] Canales-Rodriguez E.J et al., "Deconvolution in Diffusion - Spectrum Imaging", Neuroimage, 2010. - - .. [3] Garyfallidis E, "Towards an accurate brain tractography", PhD - thesis, University of Cambridge, 2012. + .. footbibliography:: Examples -------- @@ -199,11 +194,14 @@ def rtop_signal(self, filtering=True): return rtop def rtop_pdf(self, normalized=True): - r"""Calculates the return to origin probability from the propagator, which is - the propagator evaluated at zero (see Descoteaux et Al. [1]_, - Tuch [2]_, Wu et al. [3]_) + r"""Calculates the return to origin probability from the propagator, + which is the propagator evaluated at zero. + rtop = P(0) + See :footcite:p:`Descoteaux2011`, :footcite:p:`Tuch2002` and + :footcite:p:`Wu2008` for further details about the method. + Parameters ---------- normalized : boolean, optional @@ -217,16 +215,7 @@ def rtop_pdf(self, normalized=True): References ---------- - .. [1] Descoteaux M. et al., "Multiple q-shell diffusion propagator - imaging", Medical Image Analysis, vol 15, No. 4, p. 603-621, 2011. - - .. [2] Tuch D.S., "Diffusion MRI of Complex Tissue Structure", - PhD Thesis, 2002. - - .. [3] Wu Y. et al., "Computation of Diffusion Function Measures - in q -Space Using Magnetic Resonance Hybrid Diffusion Imaging", - IEEE TRANSACTIONS ON MEDICAL IMAGING, vol. 27, No. 6, p. 858-865, - 2008 + .. footbibliography:: """ @@ -246,7 +235,7 @@ def msd_discrete(self, normalized=True): MSD:{DSI}=\int_{-\infty}^{\infty}\int_{-\infty}^{\infty}\int_{-\infty}^{\infty} P(\hat{\mathbf{r}}) \cdot \hat{\mathbf{r}}^{2} \ dr_x \ dr_y \ dr_z where $\hat{\mathbf{r}}$ is a point in the 3D Propagator space - (see Wu et al. [1]_). + (see :footcite:p:`Wu2007`). Parameters ---------- @@ -261,8 +250,7 @@ def msd_discrete(self, normalized=True): References ---------- - .. [1] Wu Y. et al., "Hybrid diffusion imaging", NeuroImage, vol 36, - p. 617-629, 2007. + .. footbibliography:: """ # noqa: E501 @@ -524,8 +512,10 @@ def __init__( where $\mathbf{r}$ is the displacement vector and $\mathbf{q}$ is the wave vector which corresponds to different gradient directions, $M(\mathbf{q})$ is a mask corresponding to your q-space sampling and - $\otimes$ is the convolution operator [1]_. + $\otimes$ is the convolution operator + :footcite:p:`CanalesRodriguez2010`. + See also :footcite:p:`Biggs1997`. Parameters ---------- @@ -547,12 +537,7 @@ def __init__( References ---------- - .. [1] Canales-Rodriguez E.J et al., "Deconvolution in Diffusion - Spectrum Imaging", Neuroimage, 2010. - - .. [2] Biggs David S.C. et al., "Acceleration of Iterative Image - Restoration Algorithms", Applied Optics, vol. 36, No. 8, p. 1766-1775, - 1997. + .. footbibliography:: """ # noqa: E501 DiffusionSpectrumModel.__init__( @@ -638,13 +623,11 @@ def LR_deconv(prop, psf, numit=5, acc_factor=1): numit : int Number of Lucy-Richardson iteration to perform. acc_factor : float - Exponential acceleration factor as in [1]_. + Exponential acceleration factor as in :footcite:p:`Biggs1997`. References ---------- - .. [1] Biggs David S.C. et al., "Acceleration of Iterative Image - Restoration Algorithms", Applied Optics, vol. 36, No. 8, p. 1766-1775, - 1997. + .. footbibliography:: """ diff --git a/dipy/reconst/dti.py b/dipy/reconst/dti.py index dca34e379c..85a97e6b4d 100755 --- a/dipy/reconst/dti.py +++ b/dipy/reconst/dti.py @@ -109,7 +109,8 @@ def geodesic_anisotropy(evals, axis=-1): Notes ----- - GA is calculated using the following equation given in [1]_: + GA is calculated using the following equation given in + :footcite:p:`Batchelor2005`: .. math:: @@ -120,36 +121,23 @@ def geodesic_anisotropy(evals, axis=-1): Note that the notation, $$, is often used as the mean diffusivity (MD) of the diffusion tensor and can lead to confusions in the literature - (see [1]_ versus [2]_ versus [3]_ for example). Reference [2]_ defines + (see :footcite:p:`Batchelor2005` versus :footcite:p:`Correia2011b` versus + :footcite:p:`Lee2008` for example). :footcite:p:`Correia2011b` defines geodesic anisotropy (GA) with $$ as the MD in the denominator of the - sum. This is wrong. The original paper [1]_ defines GA with - $ = det(D)^{1/3}$, as the isotropic part of the distance. This might be - an explanation for the confusion. The isotropic part of the diffusion - tensor in Euclidean space is the MD whereas the isotropic part of the - tensor in log-Euclidean space is $det(D)^{1/3}$. The Appendix of [1]_ and - log-Euclidean derivations from [3]_ are clear on this. Hence, all that to - say that $ = det(D)^{1/3}$ here for the GA definition and not MD. + sum. This is wrong. The original paper :footcite:p:`Batchelor2005` defines + GA with $ = det(D)^{1/3}$, as the isotropic part of the distance. This + might be an explanation for the confusion. The isotropic part of the + diffusion tensor in Euclidean space is the MD whereas the isotropic part of + the tensor in log-Euclidean space is $det(D)^{1/3}$. The Appendix of + :footcite:p:`Batchelor2005` and log-Euclidean derivations from + :footcite:p:`Lee2008` are clear on this. Hence, all that to say that + $ = det(D)^{1/3}$ here for the GA definition and not MD. + + See also :footcite:p:`Arsigny2006`. References ---------- - - .. [1] P. G. Batchelor, M. Moakher, D. Atkinson, F. Calamante, - A. Connelly, "A rigorous framework for diffusion tensor calculus", - Magnetic Resonance in Medicine, vol. 53, pp. 221-225, 2005. - - .. [2] M. M. Correia, V. F. Newcombe, G.B. Williams. - "Contrast-to-noise ratios for indices of anisotropy obtained from - diffusion MRI: a study with standard clinical b-values at 3T". - NeuroImage, vol. 57, pp. 1103-1115, 2011. - - .. [3] A. D. Lee, etal, P. M. Thompson. - "Comparison of fractional and geodesic anisotropy in diffusion tensor - images of 90 monozygotic and dizygotic twins". 5th IEEE International - Symposium on Biomedical Imaging (ISBI), pp. 943-946, May 2008. - - .. [4] V. Arsigny, P. Fillard, X. Pennec, N. Ayache. - "Log-Euclidean metrics for fast and simple calculus on diffusion - tensors." Magnetic Resonance in Medecine, vol 56, pp. 411-421, 2006. + .. footbibliography:: """ evals = _roll_evals(evals, axis) @@ -160,7 +148,7 @@ def geodesic_anisotropy(evals, axis=-1): log3 = np.zeros(ev1.shape) idx = np.nonzero(ev1) - # this is the definition in [1]_ + # this is the definition in :footcite:p:`Batchelor2005` detD = np.power(ev1 * ev2 * ev3, 1 / 3.0) log1[idx] = np.log(ev1[idx] / detD[idx]) log2[idx] = np.log(ev2[idx] / detD[idx]) @@ -356,7 +344,9 @@ def determinant(q_form): def isotropic(q_form): r""" - Calculate the isotropic part of the tensor [1]_. + Calculate the isotropic part of the tensor. + + See :footcite:p:`Ennis2006` for further details about the method. Parameters ---------- @@ -371,17 +361,15 @@ def isotropic(q_form): Notes ----- - The isotropic part of a tensor is defined as (equations 3-5 of [1]_): + The isotropic part of a tensor is defined as (equations 3-5 of + :footcite:p:`Ennis2006`): .. math:: \bar{A} = \frac{1}{2} tr(A) I References ---------- - .. [1] Daniel B. Ennis and G. Kindlmann, "Orthogonal Tensor - Invariants and the Analysis of Diffusion Tensor Magnetic Resonance - Images", Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, - 2006. + .. footbibliography:: """ tr_A = q_form[..., 0, 0] + q_form[..., 1, 1] + q_form[..., 2, 2] @@ -392,7 +380,9 @@ def isotropic(q_form): def deviatoric(q_form): r""" - Calculate the deviatoric (anisotropic) part of the tensor [1]_. + Calculate the deviatoric (anisotropic) part of the tensor. + + See :footcite:p:`Ennis2006` for further details about the method. Parameters ---------- @@ -407,7 +397,8 @@ def deviatoric(q_form): Notes ----- - The deviatoric part of the tensor is defined as (equations 3-5 in [1]_): + The deviatoric part of the tensor is defined as (equations 3-5 in + :footcite:p:`Ennis2006`): .. math:: \widetilde{A} = A - \bar{A} @@ -417,10 +408,7 @@ def deviatoric(q_form): References ---------- - .. [1] Daniel B. Ennis and G. Kindlmann, "Orthogonal Tensor - Invariants and the Analysis of Diffusion Tensor Magnetic Resonance - Images", Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, - 2006. + .. footbibliography:: """ A_squiggle = q_form - isotropic(q_form) @@ -461,7 +449,9 @@ def norm(q_form): def mode(q_form): r""" - Mode (MO) of a diffusion tensor [1]_. + Mode (MO) of a diffusion tensor. + + See :footcite:p:`Ennis2006` for further details about the method. Parameters ---------- @@ -478,7 +468,7 @@ def mode(q_form): ----- Mode ranges between -1 (planar anisotropy) and +1 (linear anisotropy) with 0 representing isotropy. Mode is calculated with the following - equation (equation 9 in [1]_): + equation (equation 9 in :footcite:p:`Ennis2006`): .. math:: @@ -488,11 +478,7 @@ def mode(q_form): References ---------- - - .. [1] Daniel B. Ennis and G. Kindlmann, "Orthogonal Tensor - Invariants and the Analysis of Diffusion Tensor Magnetic Resonance - Images", Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, - 2006. + .. footbibliography:: """ A_squiggle = deviatoric(q_form) @@ -512,7 +498,9 @@ def mode(q_form): def linearity(evals, axis=-1): r""" - The linearity of the tensor [1]_ + The linearity of the tensor. + + See :footcite:p:`Westin1997` for further details about the method. Parameters ---------- @@ -536,9 +524,7 @@ def linearity(evals, axis=-1): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., - "Geometrical diffusion measures for MRI from tensor basis analysis" in - Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ evals = _roll_evals(evals, axis) @@ -548,7 +534,9 @@ def linearity(evals, axis=-1): def planarity(evals, axis=-1): r""" - The planarity of the tensor [1]_ + The planarity of the tensor. + + See :footcite:p:`Westin1997` for further details about the method. Parameters ---------- @@ -573,9 +561,7 @@ def planarity(evals, axis=-1): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., - "Geometrical diffusion measures for MRI from tensor basis analysis" in - Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ evals = _roll_evals(evals, axis) @@ -585,7 +571,9 @@ def planarity(evals, axis=-1): def sphericity(evals, axis=-1): r""" - The sphericity of the tensor [1]_ + The sphericity of the tensor. + + See :footcite:p:`Westin1997` for further details about the method. Parameters ---------- @@ -609,9 +597,7 @@ def sphericity(evals, axis=-1): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., - "Geometrical diffusion measures for MRI from tensor basis analysis" in - Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ evals = _roll_evals(evals, axis) @@ -698,7 +684,10 @@ class TensorModel(ReconstModel): """Diffusion Tensor""" def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs): - """A Diffusion Tensor Model [1]_, [2]_. + """A Diffusion Tensor Model. + + See :footcite:p:`Basser1994b` and :footcite:p:`Basser1996` for further + details about the model. Parameters ---------- @@ -714,7 +703,7 @@ def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs) 'NLLS' for non-linear least-squares :func:`dti.nlls_fit_tensor` 'RT' or 'restore' or 'RESTORE' for RESTORE robust tensor - fitting [3]_ + fitting :footcite:p:`Chang2005` :func:`dti.restore_fit_tensor` callable has to have the signature: @@ -746,14 +735,7 @@ def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs) References ---------- - .. [1] Basser, P.J., Mattiello, J., LeBihan, D., 1994. Estimation of - the effective self-diffusion tensor from the NMR spin echo. J Magn - Reson B 103, 247-254. - .. [2] Basser, P., Pierpaoli, C., 1996. Microstructural and - physiological features of tissues elucidated by quantitative - diffusion-tensor MRI. Journal of Magnetic Resonance 111, 209-219. - .. [3] Chang, L-C, Jones D.K., Pierpaoli, C. 2005. RESTORE: Robust - estimation of tensors by outlier rejection. MRM 53: 1088-1095 + .. footbibliography:: """ ReconstModel.__init__(self, gtab) @@ -1066,7 +1048,8 @@ def planarity(self): Returns ------- sphericity : array - Calculated sphericity of the diffusion tensor [1]_. + Calculated sphericity of the diffusion tensor + :footcite:p:`Westin1997`. Notes ----- @@ -1079,9 +1062,7 @@ def planarity(self): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz - F., "Geometrical diffusion measures for MRI from tensor basis - analysis" in Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ return planarity(self.evals) @@ -1092,7 +1073,8 @@ def linearity(self): Returns ------- linearity : array - Calculated linearity of the diffusion tensor [1]_. + Calculated linearity of the diffusion tensor + :footcite:p:`Westin1997`. Notes ----- @@ -1105,9 +1087,7 @@ def linearity(self): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz - F., "Geometrical diffusion measures for MRI from tensor basis - analysis" in Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ return linearity(self.evals) @@ -1118,7 +1098,8 @@ def sphericity(self): Returns ------- sphericity : array - Calculated sphericity of the diffusion tensor [1]_. + Calculated sphericity of the diffusion tensor + :footcite:p:`Westin1997`. Notes ----- @@ -1130,9 +1111,7 @@ def sphericity(self): References ---------- - .. [1] Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz - F., "Geometrical diffusion measures for MRI from tensor basis - analysis" in Proc. 5th Annual ISMRM, 1997. + .. footbibliography:: """ return sphericity(self.evals) @@ -1155,22 +1134,13 @@ def odf(self, sphere): Notes ----- - This is based on equation 3 in [1]_. To re-derive it from - scratch, follow steps in [2]_, Section 7.9 Equation - 7.24 but with an $r^2$ term in the integral. + This is based on equation 3 in :footcite:p:`Aganj2010`. To re-derive it + from scratch, follow steps in :footcite:p:`Descoteaux2008b`, Section 7.9 + Equation 7.24 but with an $r^2$ term in the integral. References ---------- - .. [1] Aganj, I., Lenglet, C., Sapiro, G., Yacoub, E., Ugurbil, - K., & Harel, N. (2010). Reconstruction of the orientation - distribution function in single- and multiple-shell q-ball imaging - within constant solid angle. Magnetic Resonance in Medicine, 64(2), - 554-566. doi:DOI: 10.1002/mrm.22365 - - .. [2] Descoteaux, M. (2008). PhD Thesis: High Angular - Resolution Diffusion MRI: from Local Estimation to Segmentation and - Tractography. - ftp://ftp-sop.inria.fr/athena/Publications/PhDs/descoteaux_thesis.pdf + .. footbibliography:: """ odf = np.zeros((self.evals.shape[:-1] + (sphere.vertices.shape[0],))) @@ -1408,7 +1378,9 @@ def wrapped_fit_tensor( def wls_fit_tensor(design_matrix, data, return_S0_hat=False): r""" Computes weighted least squares (WLS) fit to calculate self-diffusion - tensor using a linear regression model [1]_. + tensor using a linear regression model. + + See :footcite:p:`Chung2006` for further details about the method. Parameters ---------- @@ -1461,9 +1433,7 @@ def wls_fit_tensor(design_matrix, data, return_S0_hat=False): References ---------- - .. [1] Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap - approaches for estimation of uncertainties of DTI parameters. - NeuroImage 33, 531-541. + .. footbibliography:: """ tol = 1e-6 @@ -1496,7 +1466,9 @@ def ols_fit_tensor( ): r""" Computes ordinary least squares (OLS) fit to calculate self-diffusion - tensor using a linear regression model [1]_. + tensor using a linear regression model. + + See :footcite:p:`Chung2006` for further details about the method. Parameters ---------- @@ -1536,9 +1508,7 @@ def ols_fit_tensor( References ---------- - .. [1] Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap - approaches for estimation of uncertainties of DTI parameters. - NeuroImage 33, 531-541. + .. footbibliography:: """ tol = 1e-6 @@ -1598,8 +1568,8 @@ def err_func(self, tensor, design_matrix, data, weighting=None, sigma=None): The voxel signal in all gradient directions weighting : str, optional. - Whether to use the Geman-McClure weighting criterion (see [1]_ - for details) + Whether to use the Geman-McClure weighting criterion (see + :footcite:p:`Chang2005` for details) sigma : float, array, optional If 'sigma' weighting is used, we will weight the error function @@ -1609,7 +1579,8 @@ def err_func(self, tensor, design_matrix, data, weighting=None, sigma=None): Notes ----- - The Geman-McClure M-estimator is described as follows [1]_ (page 1089): + The Geman-McClure M-estimator is described as follows + :footcite:p:`Chang2005` (page 1089): "The scale factor C affects the shape of the GMM [Geman-McClure M-estimator] weighting function and represents the expected spread of the residuals (i.e., the SD of the residuals) due @@ -1631,8 +1602,7 @@ def err_func(self, tensor, design_matrix, data, weighting=None, sigma=None): References ---------- - .. [1] Chang, L-C, Jones, DK and Pierpaoli, C (2005). RESTORE: robust - estimation of tensors by outlier rejection. MRM, 53: 1088-95. + .. footbibliography:: """ # This is the predicted signal given the params: @@ -1679,7 +1649,8 @@ def err_func(self, tensor, design_matrix, data, weighting=None, sigma=None): return ans def jacobian_func(self, tensor, design_matrix, data, weighting=None, sigma=None): - """The Jacobian is the first derivative of the error function [1]_. + """The Jacobian is the first derivative of the error function + :footcite:p:`Koay2006c`. Parameters ---------- @@ -1705,13 +1676,11 @@ def jacobian_func(self, tensor, design_matrix, data, weighting=None, sigma=None) Notes ----- - This is an implementation of equation 14 in [1]_. + This is an implementation of equation 14 in :footcite:p:`Koay2006c`. References ---------- - .. [1] Koay, CG, Chang, L-C, Carew, JD, Pierpaoli, C, Basser PJ (2006). - A unifying theoretical and algorithmic framework for least squares - methods of estimation in diffusion tensor imaging. MRM 182, 115-25. + .. footbibliography:: """ # minus sign, because derivative of residuals = data - y @@ -1908,7 +1877,9 @@ def restore_fit_tensor( design_matrix, data, sigma=None, jac=True, return_S0_hat=False, fail_is_nan=False ): """ - Use the RESTORE algorithm [1]_ to calculate a robust tensor fit + Use the RESTORE algorithm to calculate a robust tensor fit. + + See :footcite:p:`Chang2005` for further details about the method. Parameters ---------- @@ -1922,7 +1893,7 @@ def restore_fit_tensor( dimension should contain the data. It makes no copies of data. sigma : float, array of shape [n_directions], array of shape [X, Y, Z] - An estimate of the variance. [1]_ recommend to use + An estimate of the variance. :footcite:t:`Chang2005` recommend to use 1.5267 * std(background_noise), where background_noise is estimated from some part of the image known to contain no signal (only noise). Array with ndim > 1 corresponds to spatially varying sigma, so if @@ -1946,8 +1917,7 @@ def restore_fit_tensor( References ---------- - .. [1] Chang, L-C, Jones, DK and Pierpaoli, C (2005). RESTORE: robust - estimation of tensors by outlier rejection. MRM, 53: 1088-95. + .. footbibliography:: """ # Detect number of parameters to estimate from design_matrix length plus diff --git a/dipy/reconst/forecast.py b/dipy/reconst/forecast.py index e648e01529..db80ee174c 100644 --- a/dipy/reconst/forecast.py +++ b/dipy/reconst/forecast.py @@ -19,28 +19,21 @@ class ForecastModel(OdfModel, Cache): r"""Fiber ORientation Estimated using Continuous Axially Symmetric Tensors - (FORECAST) [1,2,3]_. FORECAST is a Spherical Deconvolution reconstruction + (FORECAST). + + FORECAST :footcite:p:`Anderson2005`, :footcite:p:`Kaden2016a`, + :footcite:p:`Zucchelli2017` is a Spherical Deconvolution reconstruction model for multi-shell diffusion data which enables the calculation of a voxel adaptive response function using the Spherical Mean Technique (SMT) - [2,3]_. + :footcite:p:`Kaden2016a`, :footcite:p:`Zucchelli2017`. With FORECAST it is possible to calculate crossing invariant parallel diffusivity, perpendicular diffusivity, mean diffusivity, and fractional - anisotropy [2]_ + anisotropy :footcite:p:`Kaden2016a`. References ---------- - .. [1] Anderson A. W., "Measurement of Fiber Orientation Distributions - Using High Angular Resolution Diffusion Imaging", Magnetic - Resonance in Medicine, 2005. - - .. [2] Kaden E. et al., "Quantitative Mapping of the Per-Axon Diffusion - Coefficients in Brain White Matter", Magnetic Resonance in - Medicine, 2016. - - .. [3] Zucchelli E. et al., "A generalized SMT-based framework for - Diffusion MRI microstructural model estimation", MICCAI Workshop - on Computational DIFFUSION MRI (CDMRI), 2017. + .. footbibliography:: Notes ----- @@ -58,9 +51,11 @@ def __init__( lambda_csd=1.0, ): r"""Analytical and continuous modeling of the diffusion signal with - respect to the FORECAST basis [1,2,3]_. + respect to the FORECAST basis. + This implementation is a modification of the original FORECAST - model presented in [1]_ adapted for multi-shell data as in [2,3]_ . + model presented in :footcite:p:`Anderson2005` adapted for multi-shell + data as in :footcite:p:`Kaden2016a`, :footcite:p:`Zucchelli2017`. The main idea is to model the diffusion signal as the combination of a single fiber response function $F(\mathbf{b})$ times the fODF @@ -98,17 +93,7 @@ def __init__( References ---------- - .. [1] Anderson A. W., "Measurement of Fiber Orientation Distributions - Using High Angular Resolution Diffusion Imaging", Magnetic - Resonance in Medicine, 2005. - - .. [2] Kaden E. et al., "Quantitative Mapping of the Per-Axon Diffusion - Coefficients in Brain White Matter", Magnetic Resonance in - Medicine, 2016. - - .. [3] Zucchelli M. et al., "A generalized SMT-based framework for - Diffusion MRI microstructural model estimation", MICCAI Workshop - on Computational DIFFUSION MRI (CDMRI), 2017. + .. footbibliography:: Examples -------- diff --git a/dipy/reconst/fwdti.py b/dipy/reconst/fwdti.py index 481557b83b..bf6af4c9c7 100644 --- a/dipy/reconst/fwdti.py +++ b/dipy/reconst/fwdti.py @@ -55,14 +55,11 @@ def fwdti_prediction(params, gtab, S0=1, Diso=3.0e-3): value provided in the GradientTable input for that direction, $Q$ is the quadratic form of the tensor determined by the input parameters, $f$ is the free water diffusion compartment, $D_{iso}$ is the free water diffusivity - which is equal to $3 * 10^{-3} mm^{2}s^{-1} [1]_. + which is equal to $3 * 10^{-3} mm^{2}s^{-1} :footcite:p:`NetoHenriques2017`. References ---------- - .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., - Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free - water elimination two-compartment model for diffusion tensor - imaging. ReScience volume 3, issue 1, article number 2 + .. footbibliography:: """ evals = params[..., :3] evecs = params[..., 3:-1].reshape(params.shape[:-1] + (3, 3)) @@ -90,7 +87,9 @@ class FreeWaterTensorModel(ReconstModel): """Class for the Free Water Elimination Diffusion Tensor Model""" def __init__(self, gtab, fit_method="NLS", *args, **kwargs): - """Free Water Diffusion Tensor Model [1]_. + """Free Water Diffusion Tensor Model. + + See :footcite:p:`NetoHenriques2017` for further details about the model. Parameters ---------- @@ -99,10 +98,10 @@ def __init__(self, gtab, fit_method="NLS", *args, **kwargs): fit_method : str or callable str can be one of the following: - 'WLS' for weighted linear least square fit according to [1]_ - :func:`fwdti.wls_iter` - 'NLS' for non-linear least square fit according to [1]_ - :func:`fwdti.nls_iter` + - 'WLS' for weighted linear least square fit according to + :footcite:p:`NetoHenriques2017` :func:`fwdti.wls_iter` + - 'NLS' for non-linear least square fit according to + :footcite:p:`NetoHenriques2017` :func:`fwdti.nls_iter` callable has to have the signature: ``fit_method(design_matrix, data, *args, **kwargs)`` @@ -112,10 +111,7 @@ def __init__(self, gtab, fit_method="NLS", *args, **kwargs): References ---------- - .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., - Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free - water elimination two-compartment model for diffusion tensor - imaging. ReScience volume 3, issue 1, article number 2 + .. footbibliography:: """ ReconstModel.__init__(self, gtab) @@ -185,9 +181,13 @@ class FreeWaterTensorFit(TensorFit): def __init__(self, model, model_params): """Initialize a FreeWaterTensorFit class instance. + Since the free water tensor model is an extension of DTI, class instance is defined as subclass of the TensorFit from dti.py + See :footcite:p:`NetoHenriques2017` for further details about the + method. + Parameters ---------- model : FreeWaterTensorModel Class instance @@ -203,10 +203,7 @@ def __init__(self, model, model_params): References ---------- - .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., - Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free - water elimination two-compartment model for diffusion tensor - imaging. ReScience volume 3, issue 1, article number 2 + .. footbibliography:: """ TensorFit.__init__(self, model, model_params) @@ -350,7 +347,9 @@ def wls_fit_tensor( gtab, data, Diso=3e-3, mask=None, min_signal=1.0e-6, piterations=3, mdreg=2.7e-3 ): r"""Computes weighted least squares (WLS) fit to calculate self-diffusion - tensor using a linear regression model [1]_. + tensor using a linear regression model. + + See :footcite:p:`NetoHenriques2017` for further details about the method. Parameters ---------- @@ -393,10 +392,7 @@ def wls_fit_tensor( References ---------- - .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., - Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free - water elimination two-compartment model for diffusion tensor - imaging. ReScience volume 3, issue 1, article number 2 + .. footbibliography:: """ fw_params = np.zeros(data.shape[:-1] + (13,)) W = design_matrix(gtab) @@ -460,8 +456,8 @@ def _nls_err_func( $mm^{2}.s^{-1}$. Please adjust this value if you are assuming different units of diffusion. weighting : str (optional). - Whether to use the Geman-McClure weighting criterion (see [1]_ - for details) + Whether to use the Geman-McClure weighting criterion (see + :footcite:p:`NetoHenriques2017` for details) sigma : float or float array (optional) If 'sigma' weighting is used, we will weight the error function according to the background noise estimated either in aggregate over @@ -478,6 +474,10 @@ def _nls_err_func( ft = arcsin(2*f - 1) + pi/2, insuring f estimates between 0 and 1. See fwdti.nls_fit_tensor Default: True + + References + ---------- + .. footbibliography:: """ tensor = np.copy(tensor_elements) if cholesky: @@ -633,8 +633,8 @@ def nls_iter( options: 'sigma' 'gmm' sigma: float, optional If the 'sigma' weighting scheme is used, a value of sigma needs to be - provided here. According to [Chang2005]_, a good value to use is - 1.5267 * std(background_noise), where background_noise is estimated + provided here. According to :footcite:t:`Chang2005`, a good value to use + is 1.5267 * std(background_noise), where background_noise is estimated from some part of the image known to contain no signal (only noise). Returns @@ -777,8 +777,8 @@ def nls_fit_tensor( options: 'sigma' 'gmm' sigma: float, optional If the 'sigma' weighting scheme is used, a value of sigma needs to be - provided here. According to [Chang2005]_, a good value to use is - 1.5267 * std(background_noise), where background_noise is estimated + provided here. According to :footcite:t:`Chang2005`, a good value to use + is 1.5267 * std(background_noise), where background_noise is estimated from some part of the image known to contain no signal (only noise). Returns @@ -791,6 +791,10 @@ def nls_fit_tensor( 2) Three lines of the eigenvector matrix each containing the first, second and third coordinates of the eigenvector 3) The volume fraction of the free water compartment + + References + ---------- + .. footbibliography:: """ fw_params = np.zeros(data.shape[:-1] + (13,)) W = design_matrix(gtab) @@ -840,14 +844,11 @@ def lower_triangular_to_cholesky(tensor_elements): ------- cholesky_elements : array (6,) Array containing the six Cholesky's decomposition elements - (R0, R1, R2, R3, R4, R5) [1]_. + (R0, R1, R2, R3, R4, R5) :footcite:p:`Koay2006b`. References ---------- - .. [1] Koay, C.G., Carew, J.D., Alexander, A.L., Basser, P.J., - Meyerand, M.E., 2006. Investigation of anomalous estimates of - tensor-derived quantities in diffusion tensor imaging. Magnetic - Resonance in Medicine, 55(4), 930-936. doi:10.1002/mrm.20832 + .. footbibliography:: """ R0 = np.sqrt(tensor_elements[0]) R3 = tensor_elements[1] / R0 @@ -866,7 +867,7 @@ def cholesky_to_lower_triangular(R): ---------- R : array (6,) Array containing the six Cholesky's decomposition elements - (R0, R1, R2, R3, R4, R5) [1]_. + (R0, R1, R2, R3, R4, R5) :footcite:p:`Koay2006b`. Returns ------- @@ -876,10 +877,7 @@ def cholesky_to_lower_triangular(R): References ---------- - .. [1] Koay, C.G., Carew, J.D., Alexander, A.L., Basser, P.J., - Meyerand, M.E., 2006. Investigation of anomalous estimates of - tensor-derived quantities in diffusion tensor imaging. Magnetic - Resonance in Medicine, 55(4), 930-936. doi:10.1002/mrm.20832 + .. footbibliography:: """ Dxx = R[0] ** 2 Dxy = R[0] * R[3] diff --git a/dipy/reconst/gqi.py b/dipy/reconst/gqi.py index e9fd822848..abff336aa0 100644 --- a/dipy/reconst/gqi.py +++ b/dipy/reconst/gqi.py @@ -11,14 +11,16 @@ class GeneralizedQSamplingModel(OdfModel, Cache): def __init__(self, gtab, method="gqi2", sampling_length=1.2, normalize_peaks=False): - r"""Generalized Q-Sampling Imaging [1]_ + r"""Generalized Q-Sampling Imaging. + + See :footcite:t:`Yeh2010` for further details about the model. This model has the same assumptions as the DSI method i.e. Cartesian grid sampling in q-space and fast gradient switching. - Implements equations 2.14 from [2]_ for standard GQI and equation 2.16 - from [2]_ for GQI2. You can think of GQI2 as an analytical solution of - the DSI ODF. + Implements equations 2.14 from :footcite:p:`Garyfallidis2012b` for + standard GQI and equation 2.16 from :footcite:p:`Garyfallidis2012b` for + GQI2. You can think of GQI2 as an analytical solution of the DSI ODF. Parameters ---------- @@ -31,19 +33,16 @@ def __init__(self, gtab, method="gqi2", sampling_length=1.2, normalize_peaks=Fal normalize_peaks : bool, optional True to normalize peaks. - References - ---------- - .. [1] Yeh F-C et al., "Generalized Q-Sampling Imaging", IEEE TMI, 2010 - - .. [2] Garyfallidis E, "Towards an accurate brain tractography", PhD - thesis, University of Cambridge, 2012. - Notes ----- As of version 0.9, range of the sampling length in GQI2 has changed - to match the same scale used in the 'standard' method [1]_. This - means that the value of `sampling_length` should be approximately - 1 - 1.3 (see [1]_, pg. 1628). + to match the same scale used in the 'standard' method + :footcite:t:`Yeh2010`. This means that the value of `sampling_length` + should be approximately 1 - 1.3 (see :footcite:t:`Yeh2010`, pg. 1628). + + References + ---------- + .. footbibliography:: Examples -------- @@ -160,7 +159,11 @@ def normalize_qa(qa, max_qa=None): def squared_radial_component(x, tol=0.01): """Part of the GQI2 integral - Eq.8 in the referenced paper by Yeh et al. 2010 + Eq.8 in the referenced paper by :footcite:t:`Yeh2010`. + + References + ---------- + .. footbibliography:: """ with warnings.catch_warnings(): warnings.simplefilter("ignore") diff --git a/dipy/reconst/ivim.py b/dipy/reconst/ivim.py index 000019a650..3dd83b45ea 100644 --- a/dipy/reconst/ivim.py +++ b/dipy/reconst/ivim.py @@ -188,11 +188,12 @@ def __init__( r""" Initialize an IVIM model. - The IVIM model assumes that biological tissue includes a volume - fraction 'f' of water flowing with a pseudo-diffusion coefficient - D* and a fraction (1-f) of static (diffusion only), intra and - extracellular water, with a diffusion coefficient D. In this model - the echo attenuation of a signal in a single voxel can be written as + The IVIM model footcite:p:`LeBihan1988`, :footcite:p:`Federau2012` + assumes that biological tissue includes a volume fraction 'f' of water + flowing with a pseudo-diffusion coefficient D* and a fraction (1-f) of + static (diffusion only), intra and extracellular water, with a diffusion + coefficient D. In this model the echo attenuation of a signal in a + single voxel can be written as .. math:: @@ -252,12 +253,7 @@ def __init__( References ---------- - .. [1] Le Bihan, Denis, et al. "Separation of diffusion and perfusion - in intravoxel incoherent motion MR imaging." Radiology 168.2 - (1988): 497-505. - .. [2] Federau, Christian, et al. "Quantitative measurement of brain - perfusion with intravoxel incoherent motion MR imaging." - Radiology 265.3 (2012): 874-881. + .. footbibliography:: """ if not np.any(gtab.b0s_mask): e_s = "No measured signal at bvalue == 0." @@ -515,6 +511,9 @@ class IvimModelVP(ReconstModel): def __init__(self, gtab, bounds=None, maxiter=10, xtol=1e-8): r"""Initialize an IvimModelVP class. + See :footcite:p:`LeBihan1988`, :footcite:p:`Federau2012` and + :footcite:p:`Fadnavis2019` for further details about the model. + The IVIM model assumes that biological tissue includes a volume fraction 'f' of water flowing with a pseudo-diffusion coefficient D* and a fraction (1-f: treated as a separate fraction in the variable @@ -537,16 +536,7 @@ def __init__(self, gtab, bounds=None, maxiter=10, xtol=1e-8): References ---------- - .. [1] Le Bihan, Denis, et al. "Separation of diffusion and perfusion - in intravoxel incoherent motion MR imaging." Radiology 168.2 - (1988): 497-505. - .. [2] Federau, Christian, et al. "Quantitative measurement of brain - perfusion with intravoxel incoherent motion MR imaging." - Radiology 265.3 (2012): 874-881. - .. [3] Fadnavis, Shreyas et.al. "MicroLearn: Framework for machine - learning, reconstruction, optimization and microstructure - modeling, Proceedings of: International Society of Magnetic - Resonance in Medicine (ISMRM), Montreal, Canada, 2019. + .. footbibliography:: """ self.maxiter = maxiter @@ -561,7 +551,7 @@ def __init__(self, gtab, bounds=None, maxiter=10, xtol=1e-8): def fit(self, data, bounds_de=None, **kwargs): r"""Fit method of the IvimModelVP model class - MicroLearn framework (VarPro)[1]_. + MicroLearn framework (VarPro) :footcite:p:`Fadnavis2019`. The VarPro computes the IVIM parameters using the MIX approach. This algorithm uses three different optimizers. It starts with a @@ -571,18 +561,12 @@ def fit(self, data, bounds_de=None, **kwargs): the volume fractions are determined. Then the last step is non linear least square fitting on all the parameters. The results of the first and second step are utilized as the initial values for the last step - of the algorithm. (see [1]_ and [2]_ for a comparison and a thorough - discussion). + of the algorithm. (see :footcite:p:`Fadnavis2019` and + :footcite:p:`Farooq2016` for a comparison and a thorough discussion). References ---------- - .. [1] Fadnavis, Shreyas et.al. "MicroLearn: Framework for machine - learning, reconstruction, optimization and microstructure - modeling, Proceedings of: International Society of Magnetic - Resonance in Medicine (ISMRM), Montreal, Canada, 2019. - .. [2] Farooq, Hamza, et al. "Microstructure Imaging of Crossing (MIX) - White Matter Fibers from diffusion MRI." Scientific reports 6 - (2016). + .. footbibliography:: """ data_max = data.max() @@ -658,8 +642,9 @@ def ivim_mix_cost_one(self, phi, signal): First calculates the Moore-Penrose inverse of the input `phi` and takes a dot product with the measured signal. The result obtained is again multiplied with `phi` to complete the projection of the variable into - a transformed space. (see [1]_ and [2]_ for thorough discussion on - Variable Projections and relevant cost functions). + a transformed space. (see :footcite:p:`Fadnavis2019` and + :footcite:p:`Farooq2016` for thorough discussion on Variable Projections + and relevant cost functions). Parameters ---------- @@ -682,13 +667,7 @@ def ivim_mix_cost_one(self, phi, signal): References ---------- - .. [1] Fadnavis, Shreyas et.al. "MicroLearn: Framework for machine - learning, reconstruction, optimization and microstructure - modeling, Proceedings of: International Society of Magnetic - Resonance in Medicine (ISMRM), Montreal, Canada, 2019. - .. [2] Farooq, Hamza, et al. "Microstructure Imaging of Crossing (MIX) - White Matter Fibers from diffusion MRI." Scientific reports 6 - (2016). + .. footbibliography:: """ # Moore-Penrose diff --git a/dipy/reconst/mapmri.py b/dipy/reconst/mapmri.py index 8c9bfa523c..445c2e4408 100644 --- a/dipy/reconst/mapmri.py +++ b/dipy/reconst/mapmri.py @@ -24,57 +24,32 @@ class MapmriModel(ReconstModel, Cache): - r"""Mean Apparent Propagator MRI (MAPMRI) [1]_ of the diffusion signal. - - The main idea is to model the diffusion signal as a linear combination of - the continuous functions presented in [2]_ but extending it in three - dimensions. - The main difference with the SHORE proposed in [3]_ is that MAPMRI 3D - extension is provided using a set of three basis functions for the radial - part, one for the signal along x, one for y and one for z, while [3]_ - uses one basis function to model the radial part and real Spherical - Harmonics to model the angular part. - From the MAPMRI coefficients is possible to use the analytical formulae - to estimate the ODF. - - See [8]_ for additional tissue microstructure insights provided by MAPMRI. - - References - ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Ozarslan E. et al., "Simple harmonic oscillator based reconstruction - and estimation for one-dimensional q-space magnetic resonance - 1D-SHORE)", eapoc Intl Soc Mag Reson Med, vol. 16, p. 35., 2008. + r"""Mean Apparent Propagator MRI (MAPMRI) of the diffusion signal. - .. [3] Merlet S. et al., "Continuous diffusion signal, EAP and ODF - estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. + The main idea in MAPMRI footcite:p:`Ozarslan2013` is to model the diffusion + signal as a linear combination of the continuous functions presented in + footcite:p:`Ozarslan2008` but extending it in three dimensions. - .. [4] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). + The main difference with the SHORE proposed in footcite:p:`Merlet2013` is + that MAPMRI 3D extension is provided using a set of three basis functions + for the radial part, one for the signal along x, one for y and one for z, + while footcite:p:`Merlet2013` uses one basis function to model the radial + part and real Spherical Harmonics to model the angular part. - .. [5] Cheng, J., 2014. Estimation and Processing of Ensemble Average - Propagator and Its Features in Diffusion MRI. Ph.D. Thesis. + From the MAPMRI coefficients is possible to use the analytical formulae + to estimate the ODF. - .. [6] Hosseinbor et al. "Bessel fourier orientation reconstruction - (bfor): An analytical diffusion propagator reconstruction for hybrid - diffusion imaging and computation of q-space indices". NeuroImage - 64, 2013, 650-670. + See :footcite:p:`Avram2015` for additional tissue microstructure insights + provided by MAPMRI. - .. [7] Craven et al. "Smoothing Noisy Data with Spline Functions." - NUMER MATH 31.4 (1978): 377-403. + See also footcite:p:`Fick2016b`, footcite:p:`Cheng2012`, + footcite:p:`Hosseinbor2013`, footcite:p:`Craven1979`, and + footcite:p:`DelaHaije2020` for additional insight into to the model. - .. [8] Avram et al. "Clinical feasibility of using mean apparent - propagator (MAP) MRI to characterize brain tissue microstructure". - NeuroImage 2015, in press. + References + ---------- + .. footbibliography:: - .. [9] Dela Haije et al. "Enforcing necessary non-negativity constraints - for common diffusion MRI models using sum of squares programming". - NeuroImage 209, 2020, 116405. """ def __init__( @@ -95,32 +70,36 @@ def __init__( cvxpy_solver=None, ): r"""Analytical and continuous modeling of the diffusion signal with - respect to the MAPMRI basis [1]_. + respect to the MAPMRI basis. - The main idea is to model the diffusion signal as a linear combination - of the continuous functions presented in [2]_ but extending it in three + The main idea of the MAPMRI :footcite:p:`Ozarslan2013` is to model the + diffusion signal as a linear combination of the continuous functions + presented in :footcite:p:`Ozarslan2008` but extending it in three dimensions. - The main difference with the SHORE proposed in [3]_ is that MAPMRI 3D - extension is provided using a set of three basis functions for the - radial part, one for the signal along x, one for y and one for z, while - [3]_ uses one basis function to model the radial part and real - Spherical Harmonics to model the angular part. + The main difference with the SHORE proposed in + :footcite:p:`Ozarslan2009` is that MAPMRI 3D extension is provided using + a set of three basis functions for the radial part, one for the signal + along x, one for y and one for z, while :footcite:p:`Ozarslan2009` uses + one basis function to model the radial part and real Spherical Harmonics + to model the angular part. From the MAPMRI coefficients it is possible to estimate various q-space indices, the PDF and the ODF. The fitting procedure can be constrained using the positivity - constraint proposed in [1]_ or [4]_ and/or the laplacian regularization - proposed in [5]_. + constraint proposed in :footcite:p:`Ozarslan2013` or + :footcite:p:`DelaHaije2020` and/or the laplacian regularization proposed + in :footcite:p:`Fick2016b`. For the estimation of q-space indices we recommend using the 'regular' anisotropic implementation of MAPMRI. However, it has been shown that the ODF estimation in this implementation has a bias which 'squeezes together' the ODF peaks when there is a crossing at an angle - smaller than 90 degrees [5]_. When you want to estimate ODFs for - tractography we therefore recommend using the isotropic implementation - (which is equivalent to [3]_). + smaller than 90 degrees :footcite:p:`Fick2016b`. When you want to + estimate ODFs for tractography we therefore recommend using the + isotropic implementation (which is equivalent to + :footcite:p:`Ozarslan2009`). The switch between isotropic and anisotropic can be easily made through the anisotropic_scaling option. @@ -136,18 +115,19 @@ def __init__( laplacian_regularization: bool, Regularize using the Laplacian of the MAP-MRI basis. laplacian_weighting: string or scalar, - The string 'GCV' makes it use generalized cross-validation [7]_ to - find the regularization weight [4]_. A scalar sets the - regularization weight to that value and an array will make it - selected the optimal weight from the values in the array. + The string 'GCV' makes it use generalized cross-validation + :footcite:p:`Craven1979` to find the regularization weight + :footcite:p:`DelaHaije2020`. A scalar sets the regularization + weight to that value and an array will make it selected the optimal + weight from the values in the array. positivity_constraint : bool, Constrain the propagator to be positive. global_constraints : bool, optional If set to False, positivity is enforced on a grid determined by pos_grid and pos_radius. If set to True, positivity is enforced - everywhere using the constraints of [6]_. Global constraints are - currently supported for anisotropic_scaling=True and for - radial_order <= 10. Default: False. + everywhere using the constraints of :footcite:p:`Merlet2013`. Global + constraints are currently supported for anisotropic_scaling=True and + for radial_order <= 10. pos_grid : integer, The number of points in the grid that is used in the local positivity constraint. @@ -156,7 +136,7 @@ def __init__( constraint constrains to posivity is that value. If set to 'adaptive', the maximum distance is dependent on the estimated tissue diffusivity. If 'infinity', semidefinite programming - constraints are used [9]_. + constraints are used :footcite:p:`DelaHaije2020`. anisotropic_scaling : bool, If True, uses the standard anisotropic MAP-MRI basis. If False, uses the isotropic MAP-MRI basis (equal to 3D-SHORE). @@ -179,7 +159,7 @@ def __init__( static_diffusivity : float, the tissue diffusivity that is used when dti_scale_estimation is set to False. The default is that of typical white matter - D=0.7e-3 [5]_. + D=0.7e-3 :footcite:p:`Fick2016b`. cvxpy_solver : str, optional cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See https://www.cvxpy.org/ for @@ -188,30 +168,7 @@ def __init__( References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Ozarslan E. et al., "Simple harmonic oscillator based - reconstruction and estimation for one-dimensional q-space - magnetic resonance 1D-SHORE)", Proc Intl Soc Mag Reson Med, - vol. 16, p. 35., 2008. - - .. [3] Ozarslan E. et al., "Simple harmonic oscillator based - reconstruction and estimation for three-dimensional q-space - mri", ISMRM 2009. - - .. [4] Dela Haije et al. "Enforcing necessary non-negativity - constraints for common diffusion MRI models using sum of squares - programming". NeuroImage 209, 2020, 116405. - - .. [5] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - - .. [6] Merlet S. et al., "Continuous diffusion signal, EAP and ODF - estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. + .. footbibliography:: Examples -------- @@ -543,8 +500,10 @@ def mapmri_coeff(self): return self._mapmri_coef def odf(self, sphere, s=2): - r"""Calculates the analytical Orientation Distribution Function (ODF) - from the signal [1]_ Eq. (32). + """Calculates the analytical Orientation Distribution Function (ODF) + from the signal. + + See :footcite:p:`Ozarslan2013` Eq. (32). Parameters ---------- @@ -555,9 +514,7 @@ def odf(self, sphere, s=2): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ if self.model.anisotropic_scaling: @@ -579,20 +536,15 @@ def odf(self, sphere, s=2): def odf_sh(self, s=2): r"""Calculates the real analytical odf for a given discrete sphere. + Computes the design matrix of the ODF for the given sphere vertices - and radial moment [1]_ eq. (32). The radial moment s acts as a - sharpening method. The analytical equation for the spherical ODF basis - is given in [2]_ eq. (C8). + and radial moment :footcite:p:`Ozarslan2013` eq. (32). The radial moment + s acts as a sharpening method. The analytical equation for the spherical + ODF basis is given in :footcite:p:`Fick2016b` eq. (C8). References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ if self.model.anisotropic_scaling: raise ValueError( @@ -610,19 +562,15 @@ def odf_sh(self, s=2): return odf def rtpp(self): - r"""Calculates the analytical return to the plane probability (RTPP) - [1]_ eq. (42). The analytical formula for the isotropic MAP-MRI - basis was derived in [2]_ eq. (C11). + r"""Calculates the analytical return to the plane probability (RTPP). + + RTPP is defined in :footcite:p:`Ozarslan2013` eq. (42). The analytical + formula for the isotropic MAP-MRI basis was derived in + :footcite:p:`Fick2016b` eq. (C11). References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ Bm = self.model.Bm ind_mat = self.model.ind_mat @@ -670,19 +618,15 @@ def rtpp(self): return rtpp.sum() def rtap(self): - r"""Calculates the analytical return to the axis probability (RTAP) - [1]_ eq. (40, 44a). The analytical formula for the isotropic MAP-MRI - basis was derived in [2]_ eq. (C11). + r"""Calculates the analytical return to the axis probability (RTAP). + + RTAP is defined in :footcite:p:`Ozarslan2013` eq. (40, 44a). The + analytical formula for the isotropic MAP-MRI basis was derived in + :footcite:p:`Fick2016b` eq. (C11). References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ Bm = self.model.Bm ind_mat = self.model.ind_mat @@ -728,19 +672,15 @@ def rtap(self): return rtap def rtop(self): - r"""Calculates the analytical return to the origin probability (RTOP) - [1]_ eq. (36, 43). The analytical formula for the isotropic MAP-MRI - basis was derived in [2]_ eq. (C11). + r"""Calculates the analytical return to the origin probability (RTOP). + + RTOP is defined in :footcite:p:`Ozarslan2013` eq. (36, 43). The + analytical formula for the isotropic MAP-MRI basis was derived in + :footcite:p:`Fick2016b` eq. (C11). References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ Bm = self.model.Bm @@ -758,18 +698,14 @@ def rtop(self): def msd(self): r"""Calculates the analytical Mean Squared Displacement (MSD). + It is defined as the Laplacian of the origin of the estimated signal - [1]_. The analytical formula for the MAP-MRI basis was derived in [2]_ - eq. (C13, D1). + :footcite:p:`Cheng2012`. The analytical formula for the MAP-MRI basis + was derived in :footcite:p:`Fick2016b` eq. (C13, D1). References ---------- - .. [1] Cheng, J., 2014. Estimation and Processing of Ensemble Average - Propagator and Its Features in Diffusion MRI. Ph.D. Thesis. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ mu = self.mu @@ -810,20 +746,15 @@ def msd(self): def qiv(self): r"""Calculates the analytical Q-space Inverse Variance (QIV). + It is defined as the inverse of the Laplacian of the origin of the - estimated propagator [1]_ eq. (22). The analytical formula for the - MAP-MRI basis was derived in [2]_ eq. (C14, D2). + estimated propagator :footcite:p:`Hosseinbor2013` eq. (22). The + analytical formula for the MAP-MRI basis was derived in + :footcite:p:`Fick2016b` eq. (C14, D2). References ---------- - .. [1] Hosseinbor et al. "Bessel fourier orientation reconstruction - (bfor): An analytical diffusion propagator reconstruction for hybrid - diffusion imaging and computation of q-space indices. NeuroImage 64, - 2013, 650-670. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ ux, uy, uz = self.mu ind_mat = self.model.ind_mat @@ -859,20 +790,17 @@ def qiv(self): return qiv def ng(self): - r"""Calculates the analytical non-Gaussiannity (NG) [1]_. - For the NG to be meaningful the mapmri scale factors must be - estimated only on data representing Gaussian diffusion of spins, i.e., - bvals smaller than about 2000 s/mm^2 [2]_. + r"""Calculates the analytical non-Gaussiannity (NG). + + For the NG to be meaningful the mapmri scale factors must be estimated + only on data representing Gaussian diffusion of spins, i.e., bvals + smaller than about 2000 s/mm^2 :footcite:p:`Avram2015`. + + See :footcite:p:`Ozarslan2013` for a definition of the metric. References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Avram et al. "Clinical feasibility of using mean apparent - propagator (MAP) MRI to characterize brain tissue microstructure". - NeuroImage 2015, in press. + .. footbibliography:: """ if self.model.bval_threshold > 2000.0: warn( @@ -889,20 +817,17 @@ def ng(self): return np.sqrt(1 - coef[0] ** 2 / np.sum(coef**2)) def ng_parallel(self): - r"""Calculates the analytical parallel non-Gaussiannity (NG) [1]_. - For the NG to be meaningful the mapmri scale factors must be - estimated only on data representing Gaussian diffusion of spins, i.e., - bvals smaller than about 2000 s/mm^2 [2]_. + r"""Calculates the analytical parallel non-Gaussiannity (NG). + + For the NG to be meaningful the mapmri scale factors must be estimated + only on data representing Gaussian diffusion of spins, i.e., bvals + smaller than about 2000 s/mm^2 :footcite:p:`Avram2015`. + + See :footcite:p:`Ozarslan2013` for a definition of the metric. References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Avram et al. "Clinical feasibility of using mean apparent - propagator (MAP) MRI to characterize brain tissue microstructure". - NeuroImage 2015, in press. + .. footbibliography:: """ if self.model.bval_threshold > 2000.0: warn( @@ -935,19 +860,16 @@ def ng_parallel(self): def ng_perpendicular(self): r"""Calculates the analytical perpendicular non-Gaussiannity (NG) - [1]_. For the NG to be meaningful the mapmri scale factors must be - estimated only on data representing Gaussian diffusion of spins, i.e., - bvals smaller than about 2000 s/mm^2 [2]_. + + For the NG to be meaningful the mapmri scale factors must be estimated + only on data representing Gaussian diffusion of spins, i.e., bvals + smaller than about 2000 s/mm^2 :footcite:p:`Avram2015`. + + See :footcite:p:`Ozarslan2013` for a definition of the metric. References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Avram et al. "Clinical feasibility of using mean apparent - propagator (MAP) MRI to characterize brain tissue microstructure". - NeuroImage 2015, in press. + .. footbibliography:: """ if self.model.bval_threshold > 2000.0: warn( @@ -980,18 +902,18 @@ def ng_perpendicular(self): return np.sqrt(1 - np.sum(a00**2) / np.sum(a_perp**2)) def norm_of_laplacian_signal(self): - """Calculates the norm of the laplacian of the fitted signal [1]_. + """Calculates the norm of the laplacian of the fitted signal. + This information could be useful to assess if the extrapolation of the fitted signal contains spurious oscillations. A high laplacian may - indicate that these are present, and any q-space indices that - use integrals of the signal may be corrupted (e.g. RTOP, RTAP, RTPP, - QIV). + indicate that these are present, and any q-space indices that use + integrals of the signal may be corrupted (e.g. RTOP, RTAP, RTPP, QIV). + + See :footcite:p:`Fick2016b` for a definition of the metric. References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ if self.model.anisotropic_scaling: laplacian_matrix = mapmri_laplacian_reg_matrix( @@ -1076,7 +998,9 @@ def pdf(self, r_points): def isotropic_scale_factor(mu_squared): - r"""Estimated isotropic scaling factor _[1] Eq. (49). + r"""Estimated isotropic scaling factor. + + See :footcite:p:`Ozarslan2013` Eq. (49). Parameters ---------- @@ -1090,9 +1014,7 @@ def isotropic_scale_factor(mu_squared): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ X, Y, Z = mu_squared coef_array = np.array([-3, -(X + Y + Z), (X * Y + X * Z + Y * Z), 3 * X * Y * Z]) @@ -1102,7 +1024,9 @@ def isotropic_scale_factor(mu_squared): def mapmri_index_matrix(radial_order): - r"""Calculates the indices for the MAPMRI [1]_ basis in x, y and z. + r"""Calculates the indices for the MAPMRI basis in x, y and z. + + See :footcite:p:`Ozarslan2013` for a definition of MAPMRI. Parameters ---------- @@ -1116,9 +1040,7 @@ def mapmri_index_matrix(radial_order): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ index_matrix = [] for n in range(0, radial_order + 1, 2): @@ -1130,7 +1052,9 @@ def mapmri_index_matrix(radial_order): def b_mat(index_matrix): - r"""Calculates the B coefficients from [1]_ Eq. (27). + r"""Calculates the B coefficients from + + See :footcite:p:`Ozarslan2013` Eq. (27). Parameters ---------- @@ -1144,9 +1068,7 @@ def b_mat(index_matrix): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ B = np.zeros(index_matrix.shape[0]) @@ -1163,7 +1085,9 @@ def b_mat(index_matrix): def b_mat_isotropic(index_matrix): - r"""Calculates the isotropic B coefficients from [1]_ Fig 8. + r"""Calculates the isotropic B coefficients. + + See :footcite:p:`Ozarslan2013` Fig 8. Parameters ---------- @@ -1177,9 +1101,7 @@ def b_mat_isotropic(index_matrix): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ B = np.zeros((index_matrix.shape[0])) @@ -1191,7 +1113,9 @@ def b_mat_isotropic(index_matrix): def mapmri_phi_1d(n, q, mu): - r"""One dimensional MAPMRI basis function from [1]_ Eq. (4). + r"""One dimensional MAPMRI basis function. + + See :footcite:p:`Ozarslan2013` Eq. (4). Parameters ---------- @@ -1204,9 +1128,7 @@ def mapmri_phi_1d(n, q, mu): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ qn = 2 * np.pi * mu * q @@ -1221,7 +1143,9 @@ def mapmri_phi_1d(n, q, mu): def mapmri_phi_matrix(radial_order, mu, q_gradients): - r"""Compute the MAPMRI phi matrix for the signal [1]_ eq. (23). + r"""Compute the MAPMRI phi matrix for the signal. + + See :footcite:p:`Ozarslan2013` eq. (23). Parameters ---------- @@ -1234,9 +1158,7 @@ def mapmri_phi_matrix(radial_order, mu, q_gradients): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ ind_mat = mapmri_index_matrix(radial_order) @@ -1267,7 +1189,9 @@ def mapmri_phi_matrix(radial_order, mu, q_gradients): def mapmri_psi_1d(n, x, mu): - r"""One dimensional MAPMRI propagator basis function from [1]_ Eq. (10). + r"""One dimensional MAPMRI propagator basis function. + + See :footcite:p:`Ozarslan2013` Eq. (10). Parameters ---------- @@ -1280,9 +1204,7 @@ def mapmri_psi_1d(n, x, mu): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ H = hermite(n)(x / mu) @@ -1294,7 +1216,9 @@ def mapmri_psi_1d(n, x, mu): def mapmri_psi_matrix(radial_order, mu, rgrad): - r"""Compute the MAPMRI psi matrix for the propagator [1]_ eq. (22). + r"""Compute the MAPMRI psi matrix for the propagator. + + See :footcite:p:`Ozarslan2013` eq. (22). Parameters ---------- @@ -1307,9 +1231,7 @@ def mapmri_psi_matrix(radial_order, mu, rgrad): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ ind_mat = mapmri_index_matrix(radial_order) @@ -1337,7 +1259,9 @@ def mapmri_psi_matrix(radial_order, mu, rgrad): def mapmri_odf_matrix(radial_order, mu, s, vertices): - r"""Compute the MAPMRI ODF matrix [1]_ Eq. (33). + r"""Compute the MAPMRI ODF matrix. + + See :footcite:p:`Ozarslan2013` Eq. (33). Parameters ---------- @@ -1353,9 +1277,7 @@ def mapmri_odf_matrix(radial_order, mu, s, vertices): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ ind_mat = mapmri_index_matrix(radial_order) @@ -1387,13 +1309,13 @@ def mapmri_odf_matrix(radial_order, mu, s, vertices): def _odf_cfunc(n1, n2, n3, a, b, g, s): - r"""Compute the MAPMRI ODF function from [1]_ Eq. (34). + r"""Compute the MAPMRI ODF function. + + See :footcite:p:`Ozarslan2013` Eq. (34). References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ f = mfactorial @@ -1416,8 +1338,9 @@ def _odf_cfunc(n1, n2, n3, a, b, g, s): def mapmri_isotropic_phi_matrix(radial_order, mu, q): - r"""Three dimensional isotropic MAPMRI signal basis function from [1]_ - Eq. (61). + r"""Three dimensional isotropic MAPMRI signal basis function + + See :footcite:p:`Ozarslan2013` Eq. (61). Parameters ---------- @@ -1430,9 +1353,7 @@ def mapmri_isotropic_phi_matrix(radial_order, mu, q): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ qval, theta, phi = cart2sphere(q[:, 0], q[:, 1], q[:, 2]) theta[np.isnan(theta)] = 0 @@ -1457,7 +1378,9 @@ def mapmri_isotropic_phi_matrix(radial_order, mu, q): def mapmri_isotropic_radial_signal_basis(j, l_value, mu, qval): - r"""Radial part of the isotropic 1D-SHORE signal basis [1]_ eq. (61). + r"""Radial part of the isotropic 1D-SHORE signal basis. + + See :footcite:p:`Ozarslan2013` eq. (61). Parameters ---------- @@ -1472,9 +1395,7 @@ def mapmri_isotropic_radial_signal_basis(j, l_value, mu, qval): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ pi2_mu2_q2 = 2 * np.pi**2 * mu**2 * qval**2 const = ( @@ -1541,8 +1462,9 @@ def mapmri_isotropic_M_mu_dependent(radial_order, mu, qval): def mapmri_isotropic_psi_matrix(radial_order, mu, rgrad): - r"""Three dimensional isotropic MAPMRI propagator basis function from [1]_ - Eq. (61). + r"""Three dimensional isotropic MAPMRI propagator basis function. + + See :footcite:p:`Ozarslan2013` Eq. (61). Parameters ---------- @@ -1555,9 +1477,7 @@ def mapmri_isotropic_psi_matrix(radial_order, mu, rgrad): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ r, theta, phi = cart2sphere(rgrad[:, 0], rgrad[:, 1], rgrad[:, 2]) @@ -1583,7 +1503,9 @@ def mapmri_isotropic_psi_matrix(radial_order, mu, rgrad): def mapmri_isotropic_radial_pdf_basis(j, l_value, mu, r): - r"""Radial part of the isotropic 1D-SHORE propagator basis [1]_ eq. (61). + r"""Radial part of the isotropic 1D-SHORE propagator basis. + + See :footcite:p:`Ozarslan2013` eq. (61). Parameters ---------- @@ -1598,9 +1520,7 @@ def mapmri_isotropic_radial_pdf_basis(j, l_value, mu, r): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ r2u2 = r**2 / (2 * mu**2) const = ( @@ -1671,9 +1591,11 @@ def binomialfloat(n, k): def mapmri_isotropic_odf_matrix(radial_order, mu, s, vertices): - r"""Compute the isotropic MAPMRI ODF matrix [1]_ Eq. 32 but for the - isotropic propagator in [1]_ eq. (60). Analytical derivation in - [2]_ eq. (C8). + r"""Compute the isotropic MAPMRI ODF matrix. + + The computation follows :footcite:p:`Ozarslan2013` Eq. 32 but, it is done + for the isotropic propagator in footcite:p:`Ozarslan2013` eq. (60). + Analytical derivation in :footcite:p:`Fick2016b` eq. (C8). Parameters ---------- @@ -1693,13 +1615,7 @@ def mapmri_isotropic_odf_matrix(radial_order, mu, s, vertices): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ r, theta, phi = cart2sphere(vertices[:, 0], vertices[:, 1], vertices[:, 2]) @@ -1732,11 +1648,14 @@ def mapmri_isotropic_odf_matrix(radial_order, mu, s, vertices): def mapmri_isotropic_odf_sh_matrix(radial_order, mu, s): - r"""Compute the isotropic MAPMRI ODF matrix [1]_ Eq. 32 for the isotropic - propagator in [1]_ eq. (60). Here we do not compute the sphere function but - the spherical harmonics by only integrating the radial part of the - propagator. We use the same derivation of the ODF in the isotropic - implementation as in [2]_ eq. (C8). + r"""Compute the isotropic MAPMRI ODF matrix. + + The computation follows :footcite:p:`Ozarslan2013` Eq. 32, but it is done + for the isotropic propagator in :footcite:p:`Ozarslan2013` eq. (60). Here + we do not compute the sphere function but the spherical harmonics by only + integrating the radial part of the propagator. We use the same derivation of + the ODF in the isotropic implementation as in :footcite:p:`Fick2016b` eq. + (C8). Parameters ---------- @@ -1754,13 +1673,7 @@ def mapmri_isotropic_odf_sh_matrix(radial_order, mu, s): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [2] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ sh_mat = sph_harm_ind_list(radial_order) @@ -1791,7 +1704,9 @@ def mapmri_isotropic_odf_sh_matrix(radial_order, mu, s): def mapmri_isotropic_laplacian_reg_matrix(radial_order, mu): r"""Computes the Laplacian regularization matrix for MAP-MRI's isotropic - implementation [1]_ eq. (C7). + implementation. + + See :footcite:p:`Fick2016b` eq. (C7). Parameters ---------- @@ -1807,9 +1722,7 @@ def mapmri_isotropic_laplacian_reg_matrix(radial_order, mu): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ ind_mat = mapmri_isotropic_index_matrix(radial_order) @@ -1818,7 +1731,9 @@ def mapmri_isotropic_laplacian_reg_matrix(radial_order, mu): def mapmri_isotropic_laplacian_reg_matrix_from_index_matrix(ind_mat, mu): r"""Computes the Laplacian regularization matrix for MAP-MRI's isotropic - implementation [1]_ eq. (C7). + implementation. + + See :footcite:p:`Fick2016b` eq. (C7). Parameters ---------- @@ -1834,9 +1749,7 @@ def mapmri_isotropic_laplacian_reg_matrix_from_index_matrix(ind_mat, mu): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ n_elem = ind_mat.shape[0] @@ -1901,7 +1814,9 @@ def mapmri_isotropic_laplacian_reg_matrix_from_index_matrix(ind_mat, mu): def mapmri_isotropic_index_matrix(radial_order): - r"""Calculates the indices for the isotropic MAPMRI basis [1]_ Fig 8. + r"""Calculates the indices for the isotropic MAPMRI basis. + + See :footcite:p:`Ozarslan2013` Fig 8. Parameters ---------- @@ -1915,9 +1830,7 @@ def mapmri_isotropic_index_matrix(radial_order): References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ index_matrix = [] @@ -1973,7 +1886,9 @@ def delta(n, m): def map_laplace_u(n, m): - r"""S(n, m) static matrix for Laplacian regularization [1]_ eq. (13). + r"""S(n, m) static matrix for Laplacian regularization. + + See :footcite:p:`Fick2016b` eq. (13). Parameters ---------- @@ -1987,16 +1902,16 @@ def map_laplace_u(n, m): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ return (-1) ** n * delta(n, m) / (2 * np.sqrt(np.pi)) def map_laplace_t(n, m): - r"""L(m, n) static matrix for Laplacian regularization [1]_ eq. (12). + r"""L(m, n) static matrix for Laplacian regularization. + + See :footcite:p:`Fick2016b` eq. (12). Parameters ---------- @@ -2010,9 +1925,7 @@ def map_laplace_t(n, m): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ a = np.sqrt((m - 1) * m) * delta(m - 2, n) @@ -2022,7 +1935,9 @@ def map_laplace_t(n, m): def map_laplace_s(n, m): - r"""R(m,n) static matrix for Laplacian regularization [1]_ eq. (11). + r"""R(m,n) static matrix for Laplacian regularization. + + See :footcite:p:`Fick2016b` eq. (11). Parameters ---------- @@ -2036,9 +1951,7 @@ def map_laplace_s(n, m): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ @@ -2055,8 +1968,9 @@ def map_laplace_s(n, m): def mapmri_STU_reg_matrices(radial_order): - """Generate the static portions of the Laplacian regularization matrix - according to [1]_ eq. (11, 12, 13). + """Generate the static portions of the Laplacian regularization matrix. + + See :footcite:p:`Fick2016b` eq. (11, 12, 13). Parameters ---------- @@ -2070,9 +1984,7 @@ def mapmri_STU_reg_matrices(radial_order): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ S = np.zeros((radial_order + 1, radial_order + 1)) @@ -2093,7 +2005,9 @@ def mapmri_STU_reg_matrices(radial_order): def mapmri_laplacian_reg_matrix(ind_mat, mu, S_mat, T_mat, U_mat): - """Put the Laplacian regularization matrix together [1]_ eq. (10). + """Put the Laplacian regularization matrix together. + + See :footcite:p:`Fick2016b` eq. (10). The static parts in S, T and U are multiplied and divided by the voxel-specific scale factors. @@ -2114,9 +2028,7 @@ def mapmri_laplacian_reg_matrix(ind_mat, mu, S_mat, T_mat, U_mat): References ---------- - .. [1] Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP data." - NeuroImage (2016). + .. footbibliography:: """ ux, uy, uz = mu @@ -2165,7 +2077,9 @@ def mapmri_laplacian_reg_matrix(ind_mat, mu, S_mat, T_mat, U_mat): def generalized_crossvalidation_array(data, M, LR, weights_array=None): - """Generalized Cross Validation Function [1]_ eq. (15). + """Generalized Cross Validation Function. + + See :footcite:p:`Fick2016b` eq. (15). Here weights_array is a numpy array with all values that should be considered in the GCV. It will run through the weights until the cost @@ -2183,6 +2097,9 @@ def generalized_crossvalidation_array(data, M, LR, weights_array=None): weights_array : array (N_of_weights) array of optional regularization weights + References + ---------- + .. footbibliography:: """ if weights_array is None: lrange = np.linspace(0.05, 1, 20) # reasonably fast standard range @@ -2206,10 +2123,12 @@ def generalized_crossvalidation_array(data, M, LR, weights_array=None): def generalized_crossvalidation(data, M, LR, gcv_startpoint=5e-2): - """Generalized Cross Validation Function [1]_ eq. (15). + """Generalized Cross Validation Function. Finds optimal regularization weight based on generalized cross-validation. + See :footcite:p:`Craven1979` eq. (15). + Parameters ---------- data : array (N), @@ -2228,8 +2147,7 @@ def generalized_crossvalidation(data, M, LR, gcv_startpoint=5e-2): References ---------- - .. [1] Craven et al. "Smoothing Noisy Data with Spline Functions." - NUMER MATH 31.4 (1978): 377-403. + .. footbibliography:: """ MMt = np.dot(M.T, M) @@ -2247,7 +2165,14 @@ def generalized_crossvalidation(data, M, LR, gcv_startpoint=5e-2): def gcv_cost_function(weight, args): - """The GCV cost function that is iterated [4]_.""" + """The GCV cost function that is iterated. + + See :footcite:p:`Fick2016b` for further details about the method. + + References + ---------- + .. footbibliography:: + """ data, M, MMt, K, LR = args S = np.linalg.multi_dot([M, np.linalg.pinv(MMt + weight * LR), M.T]) trS = np.trace(S) diff --git a/dipy/reconst/mcsd.py b/dipy/reconst/mcsd.py index d82c7435cb..572b694a43 100644 --- a/dipy/reconst/mcsd.py +++ b/dipy/reconst/mcsd.py @@ -165,18 +165,20 @@ def __init__( ): r""" Multi-Shell Multi-Tissue Constrained Spherical Deconvolution - (MSMT-CSD) [1]_. This method extends the CSD model proposed in [2]_ by - the estimation of multiple response functions as a function of multiple - b-values and multiple tissue types. + (MSMT-CSD) :footcite:p:`Jeurissen2014`. This method extends the CSD + model proposed in :footcite:p:`Tournier2007`. by the estimation of + multiple response functions as a function of multiple b-values and + multiple tissue types. Spherical deconvolution computes a fiber orientation distribution - (FOD), also called fiber ODF (fODF) [2]_. The fODF is derived from - different tissue types and thus overcomes the overestimation of WM in - GM and CSF areas. + (FOD), also called fiber ODF (fODF) :footcite:p:`Tournier2007`. The fODF + is derived from different tissue types and thus overcomes the + overestimation of WM in GM and CSF areas. The response function is based on the different tissue types and is provided as input to the MultiShellDeconvModel. - It will be used as deconvolution kernel, as described in [2]_. + It will be used as deconvolution kernel, as described in + :footcite:p:`Tournier2007`. Parameters ---------- @@ -208,15 +210,7 @@ def __init__( References ---------- - .. [1] Jeurissen, B., et al. NeuroImage 2014. Multi-tissue constrained - spherical deconvolution for improved analysis of multi-shell - diffusion MRI data - .. [2] Tournier, J.D., et al. NeuroImage 2007. Robust determination of - the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical - deconvolution - .. [3] Tournier, J.D, et al. Imaging Systems and Technology - 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions + .. footbibliography:: """ if not iso >= 2: msg = "Multi-tissue CSD requires at least 2 tissue compartments" diff --git a/dipy/reconst/msdki.py b/dipy/reconst/msdki.py index b47669bb63..911773e773 100644 --- a/dipy/reconst/msdki.py +++ b/dipy/reconst/msdki.py @@ -74,14 +74,12 @@ def msk_from_awf(f): Notes ----- - Computes mean signal kurtosis using equations 17 of [1]_ + Computes mean signal kurtosis using equations 17 of + :footcite:p:`NetoHenriques2019`. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 + .. footbibliography:: """ msk_num = 216 * f - 504 * f**2 + 504 * f**3 - 180 * f**4 msk_den = 135 - 360 * f + 420 * f**2 - 240 * f**3 + 60 * f**4 @@ -106,11 +104,16 @@ def _msk_from_awf_error(f, msk): ------- error : float Error computed by subtracting msk with fun(f), where fun is the function - described in equation 17 of [1]_ + described in equation 17 of :footcite:p:`NetoHenriques2019`. Notes ----- - This function corresponds to the differential of equations 17 of [1]_ + This function corresponds to the differential of equations 17 of + :footcite:p:`NetoHenriques2019`. + + References + ---------- + .. footbibliography:: """ return msk_from_awf(f) - msk @@ -133,15 +136,14 @@ def _diff_msk_from_awf(f, msk): Notes ----- - This function corresponds to the differential of equations 17 of [1]_. + This function corresponds to the differential of equations 17 of + :footcite:p:`NetoHenriques2019`. + This function is applicable to both _msk_from_awf and _msk_from_awf_error. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 + .. footbibliography:: """ F = 216 * f - 504 * f**2 + 504 * f**3 - 180 * f**4 # Numerator G = 135 - 360 * f + 420 * f**2 - 240 * f**3 + 60 * f**4 # Denominator @@ -155,7 +157,10 @@ def _diff_msk_from_awf(f, msk): def awf_from_msk(msk, mask=None): """ Computes the axonal water fraction from the mean signal kurtosis - assuming the 2-compartmental spherical mean technique model [1]_, [2]_ + assuming the 2-compartmental spherical mean technique model. + + See :footcite:p:`Kaden2016b` and :footcite:p:`NetoHenriques2019` for further + details about the method. Parameters ---------- @@ -173,16 +178,11 @@ def awf_from_msk(msk, mask=None): Notes ----- Computes the axonal water fraction from the mean signal kurtosis - MSK using equation 17 of [1]_ + MSK using equation 17 of :footcite:p:`NetoHenriques2019`. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 - .. [2] Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment - microscopic diffusion imaging. Neuroimage 139:346–359. + .. footbibliography:: """ awf = np.zeros(msk.shape) @@ -227,6 +227,8 @@ def msdki_prediction(msdki_params, gtab, S0=1.0): Predict the mean signal given the parameters of the mean signal DKI, an GradientTable object and S0 signal. + See :footcite:p:`NetoHenriques2018` for further details about the method. + Parameters ---------- msdki_params : ndarray ([X, Y, Z, ...], 2) @@ -246,10 +248,7 @@ def msdki_prediction(msdki_params, gtab, S0=1.0): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain (Doctoral - thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ A = design_matrix(round_bvals(gtab.bvals)) @@ -274,7 +273,9 @@ class MeanDiffusionKurtosisModel(ReconstModel): """Mean signal Diffusion Kurtosis Model""" def __init__(self, gtab, bmag=None, return_S0_hat=False, *args, **kwargs): - """Mean Signal Diffusion Kurtosis Model [1]_. + """Mean Signal Diffusion Kurtosis Model. + + See :footcite:p:`NetoHenriques2018` for further details about the model. Parameters ---------- @@ -294,10 +295,7 @@ def __init__(self, gtab, bmag=None, return_S0_hat=False, *args, **kwargs): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ ReconstModel.__init__(self, gtab) @@ -359,6 +357,9 @@ def predict(self, msdki_params, S0=1.0): Predict a signal for this MeanDiffusionKurtosisModel class instance given parameters. + See :footcite:p:`NetoHenriques2018` for further details about the + method. + Parameters ---------- msdki_params : ndarray @@ -381,10 +382,7 @@ def predict(self, msdki_params, S0=1.0): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ return msdki_prediction(msdki_params, self.gtab, S0) @@ -421,6 +419,9 @@ def msd(self): Mean signal diffusivity (MSD) calculated from the mean signal Diffusion Kurtosis Model. + See :footcite:p:`NetoHenriques2018` for further details about the + method. + Returns ------- msd : ndarray @@ -428,10 +429,7 @@ def msd(self): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ return self.model_params[..., 0] @@ -441,6 +439,9 @@ def msk(self): Mean signal kurtosis (MSK) calculated from the mean signal Diffusion Kurtosis Model. + See :footcite:p:`NetoHenriques2018` for further details about the + method. + Returns ------- msk : ndarray @@ -448,10 +449,7 @@ def msk(self): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ return self.model_params[..., 1] @@ -459,7 +457,10 @@ def msk(self): def smt2f(self): r""" Computes the axonal water fraction from the mean signal kurtosis - assuming the 2-compartmental spherical mean technique model [1]_, [2]_ + assuming the 2-compartmental spherical mean technique model. + + See :footcite:p:`Kaden2016b` and :footcite:p:`NetoHenriques2019` for + further details about the method. Returns ------- @@ -469,16 +470,11 @@ def smt2f(self): Notes ----- Computes the axonal water fraction from the mean signal kurtosis - MSK using equation 17 of [1]_ + MSK using equation 17 of :footcite:p:`NetoHenriques2019`. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 - .. [2] Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment - microscopic diffusion imaging. Neuroimage 139:346–359. + .. footbibliography:: """ return awf_from_msk(self.msk) @@ -487,7 +483,10 @@ def smt2di(self): r""" Computes the intrinsic diffusivity from the mean signal diffusional kurtosis parameters assuming the 2-compartmental spherical mean - technique model [1]_, [2]_ + technique model. + + See :footcite:p:`Kaden2016b` and :footcite:p:`NetoHenriques2019` for + further details about the method. Returns ------- @@ -496,16 +495,12 @@ def smt2di(self): Notes ----- - Computes the intrinsic diffusivity using equation 16 of [1]_ + Computes the intrinsic diffusivity using equation 16 of + :footcite:p:`NetoHenriques2019`. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 - .. [2] Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment - microscopic diffusion imaging. Neuroimage 139:346–359. + .. footbibliography:: """ return 3 * self.msd / (1 + 2 * (1 - self.smt2f) ** 2) @@ -514,7 +509,10 @@ def smt2uFA(self): r""" Computes the microscopic fractional anisotropy from the mean signal diffusional kurtosis parameters assuming the 2-compartmental spherical - mean technique model [1]_, [2]_ + mean technique model. + + See :footcite:p:`Kaden2016b` and :footcite:p:`NetoHenriques2019` for + further details about the method. Returns ------- @@ -524,16 +522,12 @@ def smt2uFA(self): Notes ----- - Computes the intrinsic diffusivity using equation 10 of [1]_ + Computes the intrinsic diffusivity using equation 10 of + :footcite:p:`NetoHenriques2019`. References ---------- - .. [1] Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic - anisotropy misestimation in spherical‐mean single diffusion - encoding MRI. Magnetic Resonance in Medicine (In press). - doi: 10.1002/mrm.27606 - .. [2] Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment - microscopic diffusion imaging. Neuroimage 139:346–359. + .. footbibliography:: """ fe = 1 - self.smt2f num = 3 * (1 - 2 * fe**2 + fe**3) @@ -545,6 +539,9 @@ def predict(self, gtab, S0=1.0): Given a mean signal diffusion kurtosis model fit, predict the signal on the vertices of a sphere + See :footcite:p:`NetoHenriques2018` for further details about the + method. + Parameters ---------- gtab : a GradientTable class instance @@ -568,10 +565,7 @@ def predict(self, gtab, S0=1.0): References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ return msdki_prediction(self.model_params, gtab, S0=S0) @@ -586,7 +580,9 @@ def wls_fit_msdki( ): r""" Fits the mean signal diffusion kurtosis imaging based on a weighted - least square solution [1]_. + least square solution. + + See :footcite:p:`NetoHenriques2018` for further details about the method. Parameters ---------- @@ -617,10 +613,7 @@ def wls_fit_msdki( References ---------- - .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data - Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). Downing College, University of Cambridge. - https://doi.org/10.17863/CAM.29356 + .. footbibliography:: """ params = np.zeros(msignal.shape[:-1] + (3,)) diff --git a/dipy/reconst/odf.py b/dipy/reconst/odf.py index 82231fd64e..639c670bb5 100644 --- a/dipy/reconst/odf.py +++ b/dipy/reconst/odf.py @@ -45,7 +45,9 @@ def gfa(samples): Notes ----- - The GFA is defined as [1]_ :: + The GFA is defined as :footcite:p:`CohenAdad2011`: + + .. math:: \sqrt{\frac{n \sum_i{(\Psi_i - <\Psi>)^2}}{(n-1) \sum{\Psi_i ^ 2}}} @@ -53,9 +55,9 @@ def gfa(samples): the unit sphere and angle brackets denote average over the samples on the sphere. - .. [1] Quality assessment of High Angular Resolution Diffusion Imaging - data using bootstrap on Q-ball reconstruction. J. Cohen Adad, M. - Descoteaux, L.L. Wald. JMRI 33: 1194-1208. + References + ---------- + .. footbibliography:: """ diff = samples - samples.mean(-1)[..., None] n = samples.shape[-1] diff --git a/dipy/reconst/qtdmri.py b/dipy/reconst/qtdmri.py index b29a17934a..e71ef3df8b 100644 --- a/dipy/reconst/qtdmri.py +++ b/dipy/reconst/qtdmri.py @@ -27,10 +27,12 @@ class QtdmriModel(Cache): - r"""The q$\tau$-dMRI model [1]_ to analytically and continuously represent - the q$\tau$ diffusion signal attenuation over diffusion sensitization - q and diffusion time $\tau$. The model can be seen as an extension of - the MAP-MRI basis [2]_ towards different diffusion times. + r"""The q$\tau$-dMRI model to analytically and continuously represent the + q$\tau$ diffusion signal attenuation over diffusion sensitization q and + diffusion time $\tau$. + + The model :footcite:p:`Fick2018` can be seen as an extension of the MAP-MRI + basis :footcite:p:`Ozarslan2013` towards different diffusion times. The main idea is to model the diffusion signal over time and space as a linear combination of continuous functions, @@ -68,8 +70,8 @@ class QtdmriModel(Cache): Regularize using the Laplacian of the qt-dMRI basis. laplacian_weighting: string or scalar, The string 'GCV' makes it use generalized cross-validation to find - the regularization weight [3]_. A scalar sets the regularization - weight to that value. + the regularization weight :footcite:p:`Craven1979`. A scalar sets the + regularization weight to that value. l1_regularization : bool, Regularize by imposing sparsity in the coefficients using the l1-norm. @@ -79,7 +81,7 @@ class QtdmriModel(Cache): to that value. cartesian : bool Whether to use the Cartesian or spherical implementation of the - qt-dMRI basis, which we first explored in [4]_. + qt-dMRI basis, which we first explored in :footcite:p:`Fick2015`. anisotropic_scaling : bool Whether to use anisotropic scaling or isotropic scaling. This option can be used to test if the Cartesian implementation is @@ -105,20 +107,7 @@ class QtdmriModel(Cache): References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. - - .. [2] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - - .. [3] Craven et al. "Smoothing Noisy Data with Spline Functions." - NUMER MATH 31.4 (1978): 377-403. - - .. [4] Fick, Rutger HJ, et al. "A unifying framework for spatial and - temporal diffusion in diffusion mri." International Conference on - Information Processing in Medical Imaging. Springer, Cham, 2015. + .. footbibliography:: """ def __init__( @@ -549,11 +538,12 @@ def __init__( def qtdmri_to_mapmri_coef(self, tau): """This function converts the qtdmri coefficients to mapmri - coefficients for a given tau [1]_. The conversion is performed by a - matrix multiplication that evaluates the time-dependent part of the - basis and multiplies it with the coefficients, after which coefficients - with the same spatial orders are summed up, resulting in mapmri - coefficients. + coefficients for a given tau. + + Defined in :footcite:p:`Fick2018`, the conversion is performed by a + matrix multiplication that evaluates the time-depenent part of the basis + and multiplies it with the coefficients, after which coefficients with + the same spatial orders are summed up, resulting in mapmri coefficients. Parameters ---------- @@ -562,9 +552,7 @@ def qtdmri_to_mapmri_coef(self, tau): References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ if self.model.cartesian: II = self.model.cache_get("qtdmri_to_mapmri_matrix", key=tau) @@ -627,9 +615,10 @@ def sparsity_density(self, threshold=0.99): def odf(self, sphere, tau, s=2): r"""Calculates the analytical Orientation Distribution Function (ODF) - for a given diffusion time tau from the signal, [1]_ Eq. (32). The - qtdmri coefficients are first converted to mapmri coefficients - following [2]. + for a given diffusion time tau from the signal. + + See :footcite:p:`Ozarslan2013` Eq. (32). The qtdmri coefficients are + first converted to mapmri coefficients following :footcite:p:`Fick2018`. Parameters ---------- @@ -642,12 +631,7 @@ def odf(self, sphere, tau, s=2): References ---------- - .. [1] Ozarslan E. et. al, "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - .. [2] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) if self.model.cartesian: @@ -668,11 +652,13 @@ def odf(self, sphere, tau, s=2): def odf_sh(self, tau, s=2): r"""Calculates the real analytical odf for a given discrete sphere. + Computes the design matrix of the ODF for the given sphere vertices - and radial moment [1]_ eq. (32). The radial moment s acts as a - sharpening method. The analytical equation for the spherical ODF basis - is given in [2]_ eq. (C8). The qtdmri coefficients are first converted - to mapmri coefficients following [3]. + and radial moment :footcite:p:`Ozarslan2013` eq. (32). The radial moment + s acts as a sharpening method. The analytical equation for the spherical + ODF basis is given in :footcite:p:`Fick2016b` eq. (C8). The qtdmri + coefficients are first converted to mapmri coefficients following + :footcite:p:`Fick2018`. Parameters ---------- @@ -683,15 +669,7 @@ def odf_sh(self, tau, s=2): References ---------- - .. [1] Ozarslan E. et. al, "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) if self.model.cartesian: @@ -709,10 +687,12 @@ def odf_sh(self, tau, s=2): def rtpp(self, tau): r"""Calculates the analytical return to the plane probability (RTPP) - for a given diffusion time tau, [1]_ eq. (42). The analytical formula - for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). The - qtdmri coefficients are first converted to mapmri coefficients - following [3]. + for a given diffusion time tau. + + See :footcite:p:`Ozarslan2013` eq. (42). The analytical formula for the + isotropic MAP-MRI basis was derived in :footcite:p:`Fick2016b` eq. (C11). + The qtdmri coefficients are first converted to mapmri coefficients + following :footcite:p:`Fick2018`. Parameters ---------- @@ -721,15 +701,7 @@ def rtpp(self, tau): References ---------- - .. [1] Ozarslan E. et. al, "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) @@ -778,10 +750,12 @@ def rtpp(self, tau): def rtap(self, tau): r"""Calculates the analytical return to the axis probability (RTAP) - for a given diffusion time tau, [1]_ eq. (40, 44a). The analytical - formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). - The qtdmri coefficients are first converted to mapmri coefficients - following [3]. + for a given diffusion time tau. + + See :footcite:p:`Ozarslan2013` eq. (40, 44a). The analytical formula for + the isotropic MAP-MRI basis was derived in :footcite:p:`Fick2016b` eq. + (C11). The qtdmri coefficients are first converted to mapmri + coefficients following :footcite:p:`Fick2018`. Parameters ---------- @@ -790,15 +764,7 @@ def rtap(self, tau): References ---------- - .. [1] Ozarslan E. et. al, "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) @@ -848,10 +814,12 @@ def rtap(self, tau): def rtop(self, tau): r"""Calculates the analytical return to the origin probability (RTOP) - for a given diffusion time tau [1]_ eq. (36, 43). The analytical - formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). - The qtdmri coefficients are first converted to mapmri coefficients - following [3]. + for a given diffusion time tau. + + See :footcite:p:`Ozarslan2013` eq. (36, 43). The analytical formula for + the isotropic MAP-MRI basis was derived in :footcite:p:`Fick2016b` eq. + (C11). The qtdmri coefficients are first converted to mapmri + coefficients following :footcite:p:`Fick2018`. Parameters ---------- @@ -860,15 +828,7 @@ def rtop(self, tau): References ---------- - .. [1] Ozarslan E. et. al, "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) @@ -890,10 +850,13 @@ def rtop(self, tau): def msd(self, tau): r"""Calculates the analytical Mean Squared Displacement (MSD) for a - given diffusion time tau. It is defined as the Laplacian of the origin - of the estimated signal [1]_. The analytical formula for the MAP-MRI - basis was derived in [2]_ eq. (C13, D1). The qtdmri coefficients are - first converted to mapmri coefficients following [3]. + given diffusion time tau. + + It is defined as the Laplacian of the origin of the estimated signal + :footcite:t:`Cheng2012`. The analytical formula for the MAP-MRI basis + was derived in :footcite:p:`Fick2016b` eq. (C13, D1). The qtdmri + coefficients are first converted to mapmri coefficients following + :footcite:p:`Fick2018`. Parameters ---------- @@ -902,14 +865,7 @@ def msd(self, tau): References ---------- - .. [1] Cheng, J., 2014. Estimation and Processing of Ensemble Average - Propagator and Its Features in Diffusion MRI. Ph.D. Thesis. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) mu = self.us @@ -953,10 +909,12 @@ def msd(self, tau): def qiv(self, tau): r"""Calculates the analytical Q-space Inverse Variance (QIV) for given diffusion time tau. + It is defined as the inverse of the Laplacian of the origin of the - estimated propagator [1]_ eq. (22). The analytical formula for the - MAP-MRI basis was derived in [2]_ eq. (C14, D2). The qtdmri - coefficients are first converted to mapmri coefficients following [3]. + estimated propagator :footcite:p:`Hosseinbor2013` eq. (22). The + analytical formula for the MAP-MRI basis was derived in + :footcite:p:`Fick2016b` eq. (C14, D2). The qtdmri coefficients are first + converted to mapmri coefficients following :footcite:t:`Fick2018`. Parameters ---------- @@ -965,16 +923,7 @@ def qiv(self, tau): References ---------- - .. [1] Hosseinbor et al. "Bessel fourier orientation reconstruction - (bfor): An analytical diffusion propagator reconstruction for - hybrid diffusion imaging and computation of q-space indices. - NeuroImage 64, 2013, 650–670. - .. [2]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [3] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ mapmri_coef = self.qtdmri_to_mapmri_coef(tau) ux, uy, uz = self.us @@ -1074,22 +1023,21 @@ def predict(self, qvals_or_gtab, S0=1.0): return E def norm_of_laplacian_signal(self): - """Calculates the norm of the laplacian of the fitted signal [1]_. + """Calculates the norm of the laplacian of the fitted signal. + This information could be useful to assess if the extrapolation of the fitted signal contains spurious oscillations. A high laplacian norm may indicate that these are present, and any q-space indices that use integrals of the signal may be corrupted (e.g. RTOP, RTAP, RTPP, - QIV). In contrast to [1]_, the Laplacian now describes oscillations in - the 4-dimensional qt-signal [2]_. + QIV). In contrast to :footcite:t:`Fick2016b`, the Laplacian now + describes oscillations in the 4-dimensional qt-signal + :footcite:p:`Fick2018`. + + See :footcite:p:`Fick2016b` for a definition of the metric. References ---------- - .. [1]_ Fick, Rutger HJ, et al. "MAPL: Tissue microstructure estimation - using Laplacian-regularized MAP-MRI and its application to HCP - data." NeuroImage (2016). - .. [2] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ if self.model.cartesian: lap_matrix = qtdmri_laplacian_reg_matrix( @@ -1151,9 +1099,11 @@ def pdf(self, rt_points): def _qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau, isotropic): """Generate the matrix that maps the spherical qtdmri coefficients to - MAP-MRI coefficients. The conversion is done by only evaluating the time - basis for a diffusion time tau and summing up coefficients with the same - spatial basis orders [1]. + MAP-MRI coefficients. + + The conversion is done by only evaluating the time basis for a diffusion + time tau and summing up coefficients with the same spatial basis orders + :footcite:p:`Fick2018`. Parameters ---------- @@ -1169,12 +1119,9 @@ def _qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau, isotropic): isotropic : bool `True` if the case is isotropic. - References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ if isotropic: mapmri_ind_mat = mapmri.mapmri_isotropic_index_matrix(radial_order) @@ -1208,9 +1155,11 @@ def _qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau, isotropic): def qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau): """Generate the matrix that maps the qtdmri coefficients to MAP-MRI - coefficients for the anisotropic case. The conversion is done by only - evaluating the time basis for a diffusion time tau and summing up - coefficients with the same spatial basis orders [1]. + coefficients for the anisotropic case. + + The conversion is done by only evaluating the time basis for a diffusion + time tau and summing up coefficients with the same spatial basis orders + :footcite:p:`Fick2018`. Parameters ---------- @@ -1226,9 +1175,7 @@ def qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau): References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ return _qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau, False) @@ -1236,9 +1183,11 @@ def qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau): def qtdmri_isotropic_to_mapmri_matrix(radial_order, time_order, ut, tau): """Generate the matrix that maps the spherical qtdmri coefficients to - MAP-MRI coefficients for the isotropic case. The conversion is done by only - evaluating the time basis for a diffusion time tau and summing up - coefficients with the same spatial basis orders [1]. + MAP-MRI coefficients for the isotropic case. + + The conversion is done by only evaluating the time basis for a diffusion + time tau and summing up coefficients with the same spatial basis orders + :footcite:p:`Fick2018`. Parameters ---------- @@ -1254,9 +1203,7 @@ def qtdmri_isotropic_to_mapmri_matrix(radial_order, time_order, ut, tau): References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ return _qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau, True) @@ -1596,16 +1543,15 @@ def qtdmri_laplacian_reg_matrix( part4_ut_precomp=None, normalization=False, ): - """Computes the cartesian qt-dMRI Laplacian regularization matrix. If - given, uses precomputed matrices for temporal and spatial regularization - matrices to speed up computation. Follows the the formulation of Appendix B - in [1]. + """Computes the cartesian qt-dMRI Laplacian regularization matrix. + + If given, uses precomputed matrices for temporal and spatial regularization + matrices to speed up computation. Follows the formulation of Appendix B + in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ if S_mat is None or T_mat is None or U_mat is None: radial_order = ind_mat[:, :3].max() @@ -1651,16 +1597,15 @@ def qtdmri_isotropic_laplacian_reg_matrix( part4_ut_precomp=None, normalization=False, ): - """Computes the spherical qt-dMRI Laplacian regularization matrix. If - given, uses precomputed matrices for temporal and spatial regularization - matrices to speed up computation. Follows the the formulation of Appendix C - in [1]. + """Computes the spherical qt-dMRI Laplacian regularization matrix. + + If given, uses precomputed matrices for temporal and spatial regularization + matrices to speed up computation. Follows the formulation of Appendix C + in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ if part1_uq_iso_precomp is None: part1_us = mapmri.mapmri_isotropic_laplacian_reg_matrix_from_index_matrix( @@ -1701,14 +1646,14 @@ def qtdmri_isotropic_laplacian_reg_matrix( def part23_reg_matrix_q(ind_mat, U_mat, T_mat, us): - """Partial cartesian spatial Laplacian regularization matrix following - second line of Eq. (B2) in [1]. + """Partial cartesian spatial Laplacian regularization matrix. + + The implementation follows the second line of Eq. (B2) in + :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ ux, uy, uz = us x, y, z, _ = ind_mat.T @@ -1743,14 +1688,14 @@ def part23_reg_matrix_q(ind_mat, U_mat, T_mat, us): def part23_iso_reg_matrix_q(ind_mat, us): - """Partial spherical spatial Laplacian regularization matrix following the - equation below Eq. (C4) in [1]. + """Partial spherical spatial Laplacian regularization matrix. + + The implementation follows the equation below Eq. (C4) in + :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ n_elem = int(ind_mat.shape[0]) @@ -1781,14 +1726,13 @@ def part23_iso_reg_matrix_q(ind_mat, us): def part4_reg_matrix_q(ind_mat, U_mat, us): - """Partial cartesian spatial Laplacian regularization matrix following - equation Eq. (B2) in [1]. + """Partial cartesian spatial Laplacian regularization matrix. + + The implementation follows equation Eq. (B2) in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ ux, uy, uz = us x, y, z, _ = ind_mat.T @@ -1807,14 +1751,14 @@ def part4_reg_matrix_q(ind_mat, U_mat, us): def part4_iso_reg_matrix_q(ind_mat, us): - """Partial spherical spatial Laplacian regularization matrix following the - equation below Eq. (C4) in [1]. + """Partial spherical spatial Laplacian regularization matrix. + + The implementation follows the equation below Eq. (C4) in + :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ n_elem = int(ind_mat.shape[0]) LR = np.zeros((n_elem, n_elem)) @@ -1837,14 +1781,13 @@ def part4_iso_reg_matrix_q(ind_mat, us): def part1_reg_matrix_tau(ind_mat, ut): - """Partial temporal Laplacian regularization matrix following - Appendix B in [1]. + """Partial temporal Laplacian regularization matrix. + + The implementation follows Appendix B in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ n_elem = int(ind_mat.shape[0]) LD = np.zeros((n_elem, n_elem)) @@ -1858,14 +1801,13 @@ def part1_reg_matrix_tau(ind_mat, ut): def part23_reg_matrix_tau(ind_mat, ut): - """Partial temporal Laplacian regularization matrix following - Appendix B in [1]. + """Partial temporal Laplacian regularization matrix. + + The implementation follows Appendix B in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ n_elem = int(ind_mat.shape[0]) LD = np.zeros((n_elem, n_elem)) @@ -1881,14 +1823,13 @@ def part23_reg_matrix_tau(ind_mat, ut): def part4_reg_matrix_tau(ind_mat, ut): - """Partial temporal Laplacian regularization matrix following - Appendix B in [1]. + """Partial temporal Laplacian regularization matrix. + + The implementation follows Appendix B in :footcite:p:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ n_elem = int(ind_mat.shape[0]) LD = np.zeros((n_elem, n_elem)) @@ -1938,12 +1879,13 @@ def H(value): def generalized_crossvalidation(data, M, LR, startpoint=5e-4): - r"""Generalized Cross Validation Function [1]. + r"""Generalized Cross Validation Function. + + See :footcite:p:`Craven1979` for further details about the method. References ---------- - .. [1] Craven et al. "Smoothing Noisy Data with Spline Functions." - NUMER MATH 31.4 (1978): 377-403. + .. footbibliography:: """ startpoint = 1e-4 MMt = np.dot(M.T, M) @@ -1965,12 +1907,13 @@ def generalized_crossvalidation(data, M, LR, startpoint=5e-4): def GCV_cost_function(weight, arguments): - r"""Generalized Cross Validation Function that is iterated [1]. + r"""Generalized Cross Validation Function that is iterated. + + See :footcite:p:`Craven1979` for further details about the method. References ---------- - .. [1] Craven et al. "Smoothing Noisy Data with Spline Functions." - NUMER MATH 31.4 (1978): 377-403. + .. footbibliography:: """ data, M, MMt, K, LR = arguments S = np.dot(np.dot(M, np.linalg.pinv(MMt + weight * LR)), M.T) @@ -2070,13 +2013,13 @@ def create_rt_space_grid( def qtdmri_number_of_coefficients(radial_order, time_order): """Computes the total number of coefficients of the qtdmri basis given a - radial and temporal order. Equation given below Eq (9) in [1]. + radial and temporal order. + + See equation given below Eq (9) in :footcite:t:`Fick2018`. References ---------- - .. [1] Fick, Rutger HJ, et al. "Non-Parametric GraphNet-Regularized - Representation of dMRI in Space and Time", Medical Image Analysis, - 2017. + .. footbibliography:: """ F = np.floor(radial_order / 2.0) Msym = (F + 1) * (F + 2) * (4 * F + 3) / 6 diff --git a/dipy/reconst/qti.py b/dipy/reconst/qti.py index 4b38e16904..0b549909c0 100644 --- a/dipy/reconst/qti.py +++ b/dipy/reconst/qti.py @@ -1,7 +1,10 @@ """Classes and functions for fitting the covariance tensor model of q-space -trajectory imaging (QTI) by Westin et al. as presented in “Q-space trajectory -imaging for multidimensional diffusion MRI of the human brain” NeuroImage vol. -135 (2016): 345-62. https://doi.org/10.1016/j.neuroimage.2016.02.039""" +trajectory imaging (QTI) by :footcite:t:`Westin2016`. + +References +---------- +.. footbibliography:: +""" from warnings import warn @@ -402,7 +405,7 @@ def dtd_covariance(DTD): Notes ----- The covariance tensor is calculated according to the following equation and - converted into a rank-2 tensor [1]_: + converted into a rank-2 tensor :footcite:p:`Westin2016`: .. math:: @@ -412,9 +415,7 @@ def dtd_covariance(DTD): References ---------- - .. [1] Westin, Carl-Fredrik, et al. "Q-space trajectory imaging for - multidimensional diffusion MRI of the human brain." Neuroimage 135 - (2016): 345-362. https://doi.org/10.1016/j.neuroimage.2016.02.039. + .. footbibliography:: """ dims = DTD.shape if len(dims) != 3 or (dims[1:3] != (3, 3) and dims[1:3] != (6, 1)): @@ -627,7 +628,9 @@ def _wls_fit(data, mask, X, step=int(1e4)): def _sdpdc_fit(data, mask, X, cvxpy_solver): """Estimate the model parameters using Semidefinite Programming (SDP), - while enforcing positivity constraints on the D and C tensors (SDPdc) [2]_ + while enforcing positivity constraints on the D and C tensors (SDPdc). + + See :footcite:p:`Herberthson2021` for further details about the method. Parameters ---------- @@ -651,9 +654,7 @@ def _sdpdc_fit(data, mask, X, cvxpy_solver): References ---------- - .. [2] Herberthson M., Boito D., Dela Haije T., Feragen A., Westin C.-F., - Ozarslan E., "Q-space trajectory imaging with positivity constraints - (QTI+)" in Neuroimage, Volume 238, 2021. + .. footbibliography:: """ if not have_cvxpy: @@ -714,7 +715,9 @@ def _sdpdc_fit(data, mask, X, cvxpy_solver): class QtiModel(ReconstModel): def __init__(self, gtab, fit_method="WLS", cvxpy_solver="SCS"): - """Covariance tensor model of q-space trajectory imaging [1]_. + """Covariance tensor model of q-space trajectory imaging. + + See :footcite:t:`Westin2016` for further details about the model. Parameters ---------- @@ -726,19 +729,14 @@ def __init__(self, gtab, fit_method="WLS", cvxpy_solver="SCS"): - 'OLS' for ordinary least squares :func:`qti._ols_fit` - 'WLS' for weighted least squares :func:`qti._wls_fit` - 'SDPDc' for semidefinite programming with positivity constraints - applied [2]_ :func:`qti._sdpdc_fit` + applied :footcite:p:`Herberthson2021` :func:`qti._sdpdc_fit` cvxpy_solver: str, optionals solver for the SDP formulation. default: 'SCS' References ---------- - .. [1] Westin, Carl-Fredrik, et al. "Q-space trajectory imaging for - multidimensional diffusion MRI of the human brain." Neuroimage 135 - (2016): 345-362. https://doi.org/10.1016/j.neuroimage.2016.02.039. - .. [2] Herberthson M., Boito D., Dela Haije T., Feragen A., Westin CF., - Ozarslan E., "Q-space trajectory imaging with positivity - constraints (QTI+)" in Neuroimage, Volume 238, 2021. + .. footbibliography:: """ ReconstModel.__init__(self, gtab) diff --git a/dipy/reconst/rumba.py b/dipy/reconst/rumba.py index 32f21c8775..f0a4335a53 100644 --- a/dipy/reconst/rumba.py +++ b/dipy/reconst/rumba.py @@ -38,22 +38,23 @@ def __init__( verbose=False, ): """ - Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) [1]_ - - Modification of the Richardson-Lucy algorithm accounting for Rician - and Noncentral Chi noise distributions, which more accurately - represent MRI noise. Computes a maximum likelihood estimation of the - fiber orientation density function (fODF) at each voxel. Includes - white matter compartments alongside optional GM and CSF compartments - to account for partial volume effects. This fit can be performed - voxelwise or globally. The global fit will proceed more quickly than - the voxelwise fit provided that the computer has adequate RAM (>= 16 GB - should be sufficient for most datasets). + Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD). + + RUMBA-SD :footcite:p:`CanalesRodriguez2015` is a modification of the + Richardson-Lucy algorithm accounting for Rician and Noncentral Chi noise + distributions, which more accurately represent MRI noise. Computes a + maximum likelihood estimation of the fiber orientation density function + (fODF) at each voxel. Includes white matter compartments alongside + optional GM and CSF compartments to account for partial volume effects. + This fit can be performed voxelwise or globally. The global fit will + proceed more quickly than the voxelwise fit provided that the computer + has adequate RAM (>= 16 GB should be sufficient for most datasets). Kernel for deconvolution constructed using a priori knowledge of white matter response function, as well as the mean diffusivity of GM and/or CSF. RUMBA-SD is robust against impulse response imprecision, and thus - the default diffusivity values are often adequate [2]_. + the default diffusivity values are often adequate + :footcite:p:`DellAcqua2007`. Parameters @@ -106,21 +107,7 @@ def __init__( References ---------- - .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., - Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., - Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., - Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R. - (2015). Spherical Deconvolution of Multichannel Diffusion MRI - Data with Non-Gaussian Noise Models and Spatial Regularization. - PLOS ONE, 10(10), e0138910. - https://doi.org/10.1371/journal.pone.0138910 - - .. [2] Dell’Acqua, F., Rizzo, G., Scifo, P., Clarke, R., Scotti, G., & - Fazio, F. (2007). A Model-Based Deconvolution Approach to Solve - Fiber Crossing in Diffusion-Weighted MR Imaging. IEEE - Transactions on Bio-Medical Engineering, 54, 462–472. - https://doi.org/10.1109/TBME.2006.888830 - + .. footbibliography:: """ @@ -492,13 +479,13 @@ def predict(self, gtab=None, S0=None): def rumba_deconv(data, kernel, n_iter=600, recon_type="smf", n_coils=1): r""" - Fit fODF and GM/CSF volume fractions for a voxel using RUMBA-SD [1]_. + Fit fODF and GM/CSF volume fractions for a voxel using RUMBA-SD. Deconvolves the kernel from the diffusion-weighted signal by computing a - maximum likelihood estimation of the fODF. Minimizes the negative - log-likelihood of the data under Rician or Noncentral Chi noise - distributions by adapting the iterative technique developed in - Richardson-Lucy deconvolution. + maximum likelihood estimation of the fODF + :footcite:p:`CanalesRodriguez2015`. Minimizes the negative log-likelihood of + the data under Rician or Noncentral Chi noise distributions by adapting the + iterative technique developed in Richardson-Lucy deconvolution. Parameters ---------- @@ -552,9 +539,9 @@ def rumba_deconv(data, kernel, n_iter=600, recon_type="smf", n_coils=1): fractions for each compartment. Modern MRI scanners produce noise following a Rician or Noncentral Chi - distribution, depending on their signal reconstruction technique [2]_. - Using this linear model, it can be shown that the likelihood of a signal - under a Noncentral Chi noise model is: + distribution, depending on their signal reconstruction technique + `footcite:p:`Constantinides1997`. Using this linear model, it can be shown + that the likelihood of a signal under a Noncentral Chi noise model is: $P(\textbf{S}|\textbf{H}, \textbf{f}, \sigma^2, n) = \prod_{i=1}^{N}\left( \frac{S_i}{\bar{S_i}}\right)^n\exp\left\{-\frac{1}{2\sigma^2}\left[ @@ -590,23 +577,11 @@ def rumba_deconv(data, kernel, n_iter=600, recon_type="smf", n_coils=1): \circ\textbf{Hf})\circ\frac{I_n(\textbf{S}\circ\textbf{Hf}/\alpha^k)} {I_{n-1}(\textbf{S}\circ\textbf{Hf}/\alpha^k)} \right ]\right \}$ - For more details, see [1]_. + For more details, see :footcite:p:`CanalesRodriguez2015`. References ---------- - .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., Caruyer, - E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., - Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., Thiran, - J.-P.,Sarró, S., Pomarol-Clotet, E., & Salvador, R. (2015). - Spherical Deconvolution of Multichannel Diffusion MRI Data with - Non-Gaussian Noise Models and Spatial Regularization. PLOS ONE, - 10(10), e0138910. https://doi.org/10.1371/journal.pone.0138910 - - .. [2] Constantinides, C. D., Atalar, E., & McVeigh, E. R. (1997). - Signal-to-Noise Measurements in Magnitude Images from NMR Phased - Arrays. Magnetic Resonance in Medicine: Official Journal of the - Society of Magnetic Resonance in Medicine / Society of Magnetic - Resonance in Medicine, 38(5), 852–857. + .. footbibliography:: """ n_comp = kernel.shape[1] # number of compartments @@ -673,7 +648,7 @@ def mbessel_ratio(n, x): $I_{n}(x) / I_{n-1}(x)$ using Perron's continued fraction equation where $I_n$ is the modified - Bessel function of first kind, order $n$ [1]_. + Bessel function of first kind, order $n$ :footcite:p:`Gautschi1978`. Parameters ---------- @@ -690,9 +665,7 @@ def mbessel_ratio(n, x): References ---------- - .. [1] W. Gautschi and J. Slavik, “On the computation of modified Bessel - function ratios,” Math. Comp., vol. 32, no. 143, pp. 865–875, 1978, - doi: 10.1090/S0025-5718-1978-0470267-9 + .. footbibliography:: """ y = x / ( @@ -852,12 +825,13 @@ def rumba_deconv_global( Fit fODF for all voxels simultaneously using RUMBA-SD. Deconvolves the kernel from the diffusion-weighted signal at each voxel by - computing a maximum likelihood estimation of the fODF [1]_. Global fitting - also permits the use of total variation regularization (RUMBA-SD + TV). The - spatial dependence introduced by TV promotes smoother solutions (i.e. - prevents oscillations), while still allowing for sharp discontinuities - [2]_. This promotes smoothness and continuity along individual tracts while - preventing smoothing of adjacent tracts. + computing a maximum likelihood estimation of the fODF + :footcite:p:`CanalesRodriguez2015`. Global fitting also permits the use of + total variation regularization (RUMBA-SD + TV). The spatial dependence + introduced by TV promotes smoother solutions (i.e. prevents oscillations), + while still allowing for sharp discontinuities :footcite:p:`Rudin1992`. This + promotes smoothness and continuity along individual tracts while preventing + smoothing of adjacent tracts. Generally, global_fit will proceed more quickly than the voxelwise fit provided that the computer has adequate RAM (>= 16 GB should be more than @@ -930,26 +904,11 @@ def rumba_deconv_global( The regularization strength, $\alpha_{TV}$ is updated after each iteration by the discrepancy principle -- specifically, it is selected to match the - estimated variance after each iteration [3]_. + estimated variance after each iteration :footcite:p:`Chambolle2004`. References ---------- - .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., Caruyer, - E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., - Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., Thiran, - J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R. (2015). - Spherical Deconvolution of Multichannel Diffusion MRI Data with - Non-Gaussian Noise Models and Spatial Regularization. PLOS ONE, - 10(10), e0138910. https://doi.org/10.1371/journal.pone.0138910 - - .. [2] Rudin, L. I., Osher, S., & Fatemi, E. (1992). Nonlinear total - variation based noise removal algorithms. Physica D: Nonlinear - Phenomena, 60(1), 259–268. - https://doi.org/10.1016/0167-2789(92)90242-F - - .. [3] Chambolle A. An algorithm for total variation minimization and - applications. Journal of Mathematical Imaging and Vision. 2004; - 20:89–97. + .. footbibliography:: """ # Crop data to reduce memory consumption diff --git a/dipy/reconst/sfm.py b/dipy/reconst/sfm.py index 7587609ae4..3c46312030 100644 --- a/dipy/reconst/sfm.py +++ b/dipy/reconst/sfm.py @@ -2,18 +2,12 @@ The Sparse Fascicle Model. This is an implementation of the sparse fascicle model described in -[Rokem2015]_. The multi b-value version of this model is described in -[Rokem2014]_. +:footcite:t:`Rokem2015`. The multi b-value version of this model is described +in :footcite:t:`Rokem2014`. - -.. [Rokem2015] Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick - N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell - (2015). Evaluating the accuracy of diffusion MRI models in white - matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272 - -.. [Rokem2014] Ariel Rokem, Kimberly L. Chan, Jason D. Yeatman, Franco - Pestilli, Brian A. Wandell (2014). Evaluating the accuracy of diffusion - models at multiple b-values with cross-validation. ISMRM 2014. +References +---------- +.. footbibliography:: """ from collections import OrderedDict @@ -282,29 +276,19 @@ def sfm_design_matrix(gtab, sphere, response, mode="signal"): >>> sphere = dpd.get_sphere() >>> from dipy.reconst.sfm import sfm_design_matrix - A canonical tensor approximating corpus-callosum voxels [Rokem2014]_: + A canonical tensor approximating corpus-callosum voxels + :footcite:p`Rokem2014`: >>> tensor_matrix = sfm_design_matrix(gtab, sphere, ... [0.0015, 0.0005, 0.0005]) - A 'stick' function ([Behrens2007]_): + A 'stick' function :footcite:p`Behrens2007`: >>> stick_matrix = sfm_design_matrix(gtab, sphere, [0.001, 0, 0]) - Notes - ----- - .. [Rokem2015] Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick - N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell - (2015). Evaluating the accuracy of diffusion MRI models in white - matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272 - - .. [Rokem2014] Ariel Rokem, Kimberly L. Chan, Jason D. Yeatman, Franco - Pestilli, Brian A. Wandell (2014). Evaluating the accuracy of diffusion - models at multiple b-values with cross-validation. ISMRM 2014. - - .. [Behrens2007] Behrens TEJ, Berg HJ, Jbabdi S, Rushworth MFS, Woolrich MW - (2007): Probabilistic diffusion tractography with multiple fibre - orientations: What can we gain? Neuroimage 34:144-55. + References + ---------- + .. footbibliography:: """ if mode == "signal": with warnings.catch_warnings(): @@ -378,11 +362,11 @@ def __init__( l1_ratio : float, optional Sets the balance between L1 and L2 regularization in ElasticNet - [Zou2005]_. + :footcite:p`Zou2005`. alpha : float, optional Sets the balance between least-squares error and L1/L2 - regularization in ElasticNet [Zou2005]_. + regularization in ElasticNet :footcite:p`Zou2005`. isotropic : IsotropicModel class instance This is a class that implements the function that calculates the @@ -395,15 +379,12 @@ def __init__( Notes ----- - This is an implementation of the SFM, described in [Rokem2015]_. - - .. [Rokem2014] Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick - N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell - (2014). Evaluating the accuracy of diffusion MRI models in white - matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272 + This is an implementation of the SFM, described in + :footcite:p`Rokem2015`. - .. [Zou2005] Zou H, Hastie T (2005). Regularization and variable - selection via the elastic net. J R Stat Soc B:301-320 + References + ---------- + .. footbibliography:: """ ReconstModel.__init__(self, gtab) diff --git a/dipy/reconst/shm.py b/dipy/reconst/shm.py index a3f876dc34..bdc0ac4661 100755 --- a/dipy/reconst/shm.py +++ b/dipy/reconst/shm.py @@ -1,17 +1,11 @@ """Tools for using spherical harmonic models to fit diffusion data. +See :footcite:p:`Aganj2009`, :footcite:p:`Descoteaux2007`, +:footcite:p:`TristanVega2009`, and :footcite:p:`TristanVega2010`. + References ---------- -.. [1] Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging With Solid - Angle Consideration. -.. [2] Descoteaux, M., et al. 2007. Regularized, fast, and robust analytical - Q-ball imaging. -.. [3] Tristan-Vega, A., et al. 2010. A new methodology for estimation of fiber - populations in white matter of the brain with Funk-Radon transform. -.. [4] Tristan-Vega, A., et al. 2009. Estimation of fiber orientation - probability density functions in high angular resolution diffusion - imaging. - +.. footbibliography:: Note about the Transpose: In the literature the matrix representation of these methods is often written @@ -102,6 +96,8 @@ def sh_to_rh(r_sh, m_values, l_values): will be ignored as axial symmetry is assumed. Hence, there will be ``(sh_order/2 + 1)`` non-zero coefficients. + See :footcite:p:`Tournier2007` for further details about the method. + Parameters ---------- r_sh : ndarray (N,) @@ -126,9 +122,7 @@ def sh_to_rh(r_sh, m_values, l_values): References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of the - fibre orientation distribution in diffusion MRI: Non-negativity - constrained super-resolved spherical deconvolution + .. footbibliography:: """ mask = m_values == 0 @@ -316,9 +310,11 @@ def real_sph_harm(m_values, l_values, theta, phi): until="2.0", ) def real_sh_tournier_from_index(m_values, l_values, theta, phi, legacy=True): - r"""Compute real spherical harmonics as initially defined in Tournier - 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic $Y_l^m$ - is defined to be: + r"""Compute real spherical harmonics. + + The SH are computed as initially defined in :footcite:p:`Tournier2007` then + updated in MRtrix3 :footcite:p:`Tournier2019`, where the real harmonic + $Y_l^m$ is defined to be: .. math:: :nowrap: @@ -354,14 +350,7 @@ def real_sh_tournier_from_index(m_values, l_values, theta, phi, legacy=True): References ---------- - .. [1] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [2] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ # In the m < 0 case, Tournier basis considers |m| sh = spherical_harmonics(np.abs(m_values), l_values, phi, theta) @@ -386,8 +375,10 @@ def real_sh_tournier_from_index(m_values, l_values, theta, phi, legacy=True): until="2.0", ) def real_sh_descoteaux_from_index(m_values, l_values, theta, phi, legacy=True): - r"""Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, - where the real harmonic $Y_l^m$ is defined to be: + r"""Compute real spherical harmonics. + + The definition adopted here follows :footcite:p:`Descoteaux2007`, where the + real harmonic $Y_l^m$ is defined to be: .. math:: :nowrap: @@ -424,9 +415,7 @@ def real_sh_descoteaux_from_index(m_values, l_values, theta, phi, legacy=True): References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. + .. footbibliography:: """ if legacy: # In the case where m < 0, legacy descoteaux basis considers |m| @@ -444,9 +433,11 @@ def real_sh_descoteaux_from_index(m_values, l_values, theta, phi, legacy=True): @deprecated_params("sh_order", "sh_order_max", since="1.9", until="2.0") def real_sh_tournier(sh_order_max, theta, phi, full_basis=False, legacy=True): - r"""Compute real spherical harmonics as initially defined in Tournier - 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic $Y_l^m$ - is defined to be: + r"""Compute real spherical harmonics. + + The SH are computed as initially defined in :footcite:p:`Tournier2007` then + updated in MRtrix3 :footcite:p:`Tournier2019`, where the real harmonic + $Y_l^m$ is defined to be: .. math:: :nowrap: @@ -487,14 +478,7 @@ def real_sh_tournier(sh_order_max, theta, phi, full_basis=False, legacy=True): References ---------- - .. [1] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [2] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ m_values, l_values = sph_harm_ind_list(sh_order_max, full_basis) @@ -508,8 +492,10 @@ def real_sh_tournier(sh_order_max, theta, phi, full_basis=False, legacy=True): @deprecated_params("sh_order", "sh_order_max", since="1.9", until="2.0") def real_sh_descoteaux(sh_order_max, theta, phi, full_basis=False, legacy=True): - r"""Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, - where the real harmonic $Y_l^m$ is defined to be: + r"""Compute real spherical harmonics. + + The definition adopted here follows :footcite:p:`Descoteaux2007`, where the + real harmonic $Y_l^m$ is defined to be: .. math:: :nowrap: @@ -552,9 +538,7 @@ def real_sh_descoteaux(sh_order_max, theta, phi, full_basis=False, legacy=True): References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. + .. footbibliography:: """ m_value, l_value = sph_harm_ind_list(sh_order_max, full_basis) @@ -575,8 +559,10 @@ def real_sh_descoteaux(sh_order_max, theta, phi, full_basis=False, legacy=True): @deprecated_params("sh_order", "sh_order_max", since="1.9", until="2.0") def real_sym_sh_mrtrix(sh_order_max, theta, phi): r""" - Compute real symmetric spherical harmonics as in Tournier 2007 [2]_, where - the real harmonic $Y_l^m$ is defined to be:: + Compute real symmetric spherical harmonics. + + The SH are computed as initially defined in :footcite:t:`Tournier2007`, + where the real harmonic $Y_l^m$ is defined to be: .. math:: :nowrap: @@ -604,8 +590,8 @@ def real_sym_sh_mrtrix(sh_order_max, theta, phi): ------- y_mn : real float The real harmonic $Y_l^m$ sampled at ``theta`` and ``phi`` as - implemented in mrtrix. Warning: the basis is Tournier et al. - 2007 [2]_; 2004 [1]_ is slightly different. + implemented in mrtrix. Warning: the basis is :footcite:t:`Tournier2007`; + :footcite:p:`Tournier2004` is slightly different. m_values : array The phase factor ($m$) of the harmonics. l_values : array @@ -613,14 +599,7 @@ def real_sym_sh_mrtrix(sh_order_max, theta, phi): References ---------- - .. [1] Tournier J.D., Calamante F., Gadian D.G. and Connelly A. - Direct estimation of the fibre orientation density function from - diffusion-weighted MRI data using spherical deconvolution. - NeuroImage. 2004;23:1176-1185. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. + .. footbibliography:: """ return real_sh_tournier(sh_order_max, theta, phi, legacy=True) @@ -639,7 +618,7 @@ def real_sym_sh_basis(sh_order_max, theta, phi): Samples the basis functions up to order `sh_order_max` at points on the sphere given by `theta` and `phi`. The basis functions are defined here the - same way as in Descoteaux et al. 2007 [1]_ where the real harmonic $Y_l^m$ + same way as in :footcite:p:`Descoteaux2007` where the real harmonic $Y_l^m$ is defined to be: .. math:: @@ -676,9 +655,7 @@ def real_sym_sh_basis(sh_order_max, theta, phi): References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. + .. footbibliography:: """ return real_sh_descoteaux(sh_order_max, theta, phi, legacy=True) @@ -1029,10 +1006,11 @@ def predict(self, gtab=None, S0=1.0): class CsaOdfModel(QballBaseModel): """Implementation of Constant Solid Angle reconstruction method. + See :footcite:p:`Aganj2009` for further details about the method. + References ---------- - .. [1] Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging With - Solid Angle Consideration. + .. footbibliography:: """ min = 0.001 @@ -1061,14 +1039,12 @@ class OpdtModel(QballBaseModel): """Implementation of Orientation Probability Density Transform reconstruction method. + See :footcite:p:`TristanVega2009` and :footcite:p:`TristanVega2010` for + further details about the method. + References ---------- - .. [1] Tristan-Vega, A., et al. 2010. A new methodology for estimation of - fiber populations in white matter of the brain with Funk-Radon - transform. - .. [2] Tristan-Vega, A., et al. 2009. Estimation of fiber orientation - probability density functions in high angular resolution diffusion - imaging. + .. footbibliography:: """ def _set_fit_matrix(self, B, L, F, smooth): @@ -1094,10 +1070,11 @@ def _slowadc_formula(data, delta_b, delta_q): class QballModel(QballBaseModel): """Implementation of regularized Qball reconstruction method. + See :footcite:p:`Descoteaux2007` for further details about the method. + References ---------- - .. [1] Descoteaux, M., et al. 2007. Regularized, fast, and robust - analytical Q-ball imaging. + .. footbibliography:: """ def _set_fit_matrix(self, B, L, F, smooth): @@ -1157,17 +1134,14 @@ def bootstrap_data_array(data, H, R, permute=None): This function, and the bootstrap_data_voxel function, calculate residual-bootstrap samples given a Hat matrix and a Residual matrix. These samples can be used for non-parametric statistics or for bootstrap - probabilistic tractography: + probabilistic tractography, + + See :footcite:p:`Berman2008`, :footcite:p:`Haroon2009`, and + :footcite:p:`Jeurissen2011`. References ---------- - .. [1] J. I. Berman, et al., "Probabilistic streamline q-ball tractography - using the residual bootstrap" 2008. - .. [2] HA Haroon, et al., "Using the model-based residual bootstrap to - quantify uncertainty in fiber orientations from Q-ball analysis" - 2009. - .. [3] B. Jeurissen, et al., "Probabilistic Fiber Tracking Using the - Residual Bootstrap with Constrained Spherical Deconvolution" 2011. + .. footbibliography:: """ if permute is None: @@ -1266,8 +1240,10 @@ def sf_to_sh( coefficients for a full SH basis. basis_type : {None, 'tournier07', 'descoteaux07'}, optional ``None`` for the default DIPY basis, - ``tournier07`` for the Tournier 2007 [2]_[3]_ basis, - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis, + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` basis, + ``descoteaux07`` for the Descoteaux 2007 :footcite:p:`Descoteaux2007` + basis, (``None`` defaults to ``descoteaux07``). full_basis: bool, optional True for using a SH basis containing even and odd order SH functions. @@ -1285,17 +1261,7 @@ def sf_to_sh( References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [3] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ sph_harm_basis = sph_harm_lookup.get(basis_type) @@ -1332,8 +1298,10 @@ def sh_to_sf( coefficients for a full SH basis. basis_type : {None, 'tournier07', 'descoteaux07'}, optional ``None`` for the default DIPY basis, - ``tournier07`` for the Tournier 2007 [2]_[3]_ basis, - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis, + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` basis, + ``descoteaux07`` for the Descoteaux 2007 :footcite:p:`Descoteaux2007` + basis, (``None`` defaults to ``descoteaux07``). full_basis: bool, optional True to use a SH basis containing even and odd order SH functions. @@ -1349,17 +1317,7 @@ def sh_to_sf( References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [3] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ sph_harm_basis = sph_harm_lookup.get(basis_type) @@ -1399,8 +1357,10 @@ def sh_to_sf_matrix( coefficients for a full SH basis. basis_type : {None, 'tournier07', 'descoteaux07'}, optional ``None`` for the default DIPY basis, - ``tournier07`` for the Tournier 2007 [2]_[3]_ basis, - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis, + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` basis, + ``descoteaux07`` for the Descoteaux 2007 :footcite:p:`Descoteaux2007` + basis, (``None`` defaults to ``descoteaux07``). full_basis: bool, optional If True, uses a SH basis containing even and odd order SH functions. @@ -1423,17 +1383,7 @@ def sh_to_sf_matrix( References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [3] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ @@ -1516,6 +1466,8 @@ def calculate_max_order(n_coeffs, full_basis=False): def anisotropic_power(sh_coeffs, norm_factor=0.00001, power=2, non_negative=True): r"""Calculate anisotropic power map with a given SH coefficient matrix. + See :footcite:p:`DellAcqua2014` for further details about the method. + Parameters ---------- sh_coeffs : ndarray @@ -1554,11 +1506,7 @@ def anisotropic_power(sh_coeffs, norm_factor=0.00001, power=2, non_negative=True References ---------- - .. [1] Dell'Acqua, F., Lacerda, L., Catani, M., Simmons, A., 2014. - Anisotropic Power Maps: A diffusion contrast to reveal low - anisotropy tissues from HARDI data, - in: Proceedings of International Society for Magnetic Resonance in - Medicine. Milan, Italy. + .. footbibliography:: """ dim = sh_coeffs.shape[:-1] @@ -1626,8 +1574,11 @@ def convert_sh_to_full_basis(sh_coeffs): def convert_sh_from_legacy(sh_coeffs, sh_basis, full_basis=False): """Convert SH coefficients in legacy SH basis to SH coefficients - of the new SH basis for ``descoteaux07`` [1]_ or ``tournier07`` [2]_[3]_ - bases. + of the new SH basis for ``descoteaux07`` or ``tournier07`` bases. + + See :footcite:p:`Descoteaux2007` and :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` for the ``descoteaux07`` and ``tournier07`` + bases, respectively. Parameters ---------- @@ -1635,8 +1586,10 @@ def convert_sh_from_legacy(sh_coeffs, sh_basis, full_basis=False): A ndarray where the last dimension is the SH coefficients estimates for that voxel. sh_basis: {'descoteaux07', 'tournier07'} - ``tournier07`` for the Tournier 2007 [2]_[3]_ basis, - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis. + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` basis, + ``descoteaux07`` for the Descoteaux 2007 :footcite:p:`Descoteaux2007` + basis. full_basis: bool, optional True if the input SH basis includes both even and odd order SH functions, else False. @@ -1648,17 +1601,7 @@ def convert_sh_from_legacy(sh_coeffs, sh_basis, full_basis=False): References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [3] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ sh_order_max = calculate_max_order(sh_coeffs.shape[-1], full_basis=full_basis) @@ -1676,8 +1619,11 @@ def convert_sh_from_legacy(sh_coeffs, sh_basis, full_basis=False): def convert_sh_to_legacy(sh_coeffs, sh_basis, full_basis=False): """Convert SH coefficients in new SH basis to SH coefficients for - the legacy SH basis for ``descoteaux07`` [1]_ or ``tournier07`` [2]_[3]_ - bases. + the legacy SH basis for ``descoteaux07`` or ``tournier07`` bases. + + See :footcite:p:`Descoteaux2007` and :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` for the ``descoteaux07`` and ``tournier07`` + bases, respectively. Parameters ---------- @@ -1685,8 +1631,10 @@ def convert_sh_to_legacy(sh_coeffs, sh_basis, full_basis=False): A ndarray where the last dimension is the SH coefficients estimates for that voxel. sh_basis: {'descoteaux07', 'tournier07'} - ``tournier07`` for the Tournier 2007 [2]_[3]_ basis, - ``descoteaux07`` for the Descoteaux 2007 [1]_ basis. + ``tournier07`` for the Tournier 2007 :footcite:p:`Tournier2007`, + :footcite:p:`Tournier2019` basis, + ``descoteaux07`` for the Descoteaux 2007 :footcite:p:`Descoteaux2007` + basis. full_basis: bool, optional True if the input SH basis includes both even and odd order SH functions. @@ -1698,17 +1646,7 @@ def convert_sh_to_legacy(sh_coeffs, sh_basis, full_basis=False): References ---------- - .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. - Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination - of the fibre orientation distribution in diffusion MRI: - Non-negativity constrained super-resolved spherical deconvolution. - NeuroImage. 2007;35(4):1459-1472. - .. [3] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: """ sh_order_max = calculate_max_order(sh_coeffs.shape[-1], full_basis=full_basis) @@ -1735,7 +1673,9 @@ def convert_sh_descoteaux_tournier(sh_coeffs): This can be used to convert SH representations between DIPY and MRtrix3. - See [descoteaux07]_ and [tournier19]_ for the origin of these SH bases. + See :footcite:p:`Descoteaux2007` and :footcite:p:`Tournier2019` for the + origin of these SH bases. + See [mrtrixbasis]_ for a description of the basis used in MRtrix3. See [mrtrixdipybases]_ for more details on the conversion. @@ -1754,13 +1694,7 @@ def convert_sh_descoteaux_tournier(sh_coeffs): References ---------- - .. [descoteaux07] Descoteaux, M., Angelino, E., Fitzgibbons, S. and - Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. - Magn. Reson. Med. 2007;58:497-510. - .. [tournier19] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, - Pietsch M, et al. MRtrix3: A fast, flexible and open software - framework for medical image processing and visualisation. - NeuroImage. 2019 Nov 15;202:116-137. + .. footbibliography:: .. [mrtrixbasis] https://mrtrix.readthedocs.io/en/latest/concepts/spherical_harmonics.html .. [mrtrixdipybases] https://github.com/dipy/dipy/discussions/2959#discussioncomment-7481675 """ # noqa: E501 diff --git a/dipy/reconst/shore.py b/dipy/reconst/shore.py index da98a8ad12..c2dd71f078 100644 --- a/dipy/reconst/shore.py +++ b/dipy/reconst/shore.py @@ -15,10 +15,10 @@ class ShoreModel(Cache): r"""Simple Harmonic Oscillator based Reconstruction and Estimation - (SHORE) [1]_ of the diffusion signal. + (SHORE) of the diffusion signal. - The main idea is to model the diffusion signal as a linear combination of - continuous functions $\phi_i$, + The main idea of SHORE :footcite:p:`Ozarslan2008` is to model the diffusion + signal as a linear combination of continuous functions $\phi_i$, .. math:: @@ -26,32 +26,16 @@ class ShoreModel(Cache): where $\mathbf{q}$ is the wave vector which corresponds to different gradient directions. Numerous continuous functions $\phi_i$ can be used to - model $S$. Some are presented in [2,3,4]_. + model $S$. Some are presented in :footcite:p:`Merlet2013`, + :footcite:p:`Rathi2011`, and :footcite:p:`Cheng2011`. From the $c_i$ coefficients, there exist analytical formulae to estimate the ODF, the return to the origin probability (RTOP), the mean square - displacement (MSD), amongst others [5]_. + displacement (MSD), amongst others :footcite:p:`Ozarslan2013`. References ---------- - .. [1] Ozarslan E. et al., "Simple harmonic oscillator based reconstruction - and estimation for one-dimensional q-space magnetic resonance - 1D-SHORE)", Proc Intl Soc Mag Reson Med, vol. 16, p. 35., 2008. - - .. [2] Merlet S. et al., "Continuous diffusion signal, EAP and ODF - estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. - - .. [3] Rathi Y. et al., "Sparse multi-shell diffusion imaging", MICCAI, - 2011. - - .. [4] Cheng J. et al., "Theoretical Analysis and Practical Insights on - EAP Estimation via a Unified HARDI Framework", MICCAI workshop on - Computational Diffusion MRI, 2011. - - .. [5] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: Notes ----- @@ -73,10 +57,12 @@ def __init__( cvxpy_solver=None, ): r"""Analytical and continuous modeling of the diffusion signal with - respect to the SHORE basis [1,2]_. - This implementation is a modification of SHORE presented in [1]_. - The modification was made to obtain the same ordering of the basis - presented in [2,3]_. + respect to the SHORE basis. + + This implementation is a modification of SHORE presented in + :footcite:p:`Merlet2013`. The modification was made to obtain the same + ordering of the basis presented in :footcite:p:`Cheng2011`, + :footcite:p:`Ozarslan2013`. The main idea is to model the diffusion signal as a linear combination of continuous functions $\phi_i$, @@ -125,17 +111,7 @@ def __init__( References ---------- - .. [1] Merlet S. et al., "Continuous diffusion signal, EAP and - ODF estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. - - .. [2] Cheng J. et al., "Theoretical Analysis and Practical Insights - on EAP Estimation via a Unified HARDI Framework", MICCAI workshop on - Computational Diffusion MRI, 2011. - - .. [3] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: Examples -------- @@ -403,13 +379,13 @@ def odf(self, sphere): def rtop_signal(self): r"""Calculates the analytical return to origin probability (RTOP) - from the signal [1]_. + from the signal. + + See :footcite:p:`Ozarslan2013` for further details about the method. References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ rtop = 0 c = self._shore_coef @@ -426,13 +402,13 @@ def rtop_signal(self): def rtop_pdf(self): r"""Calculates the analytical return to origin probability (RTOP) - from the pdf [1]_. + from the pdf. + + See :footcite:p:`Ozarslan2013` for further details about the method. References ---------- - .. [1] Ozarslan E. et al., "Mean apparent propagator (MAP) MRI: A novel - diffusion imaging method for mapping tissue microstructure", - NeuroImage, 2013. + .. footbibliography:: """ rtop = 0 c = self._shore_coef @@ -448,7 +424,9 @@ def rtop_pdf(self): return np.clip(rtop, 0, rtop.max()) def msd(self): - r"""Calculates the analytical mean squared displacement (MSD) [1]_ + r"""Calculates the analytical mean squared displacement (MSD). + + See :footcite:p:`Wu2007` for a definition of the method. .. math:: :nowrap: @@ -457,13 +435,12 @@ def msd(self): \int_{-\infty}^{\infty} P(\hat{\mathbf{r}}) \cdot \hat{\mathbf{r}}^{2} \ dr_x \ dr_y \ dr_z - where $\hat{\mathbf{r}}$ is a point in the 3D propagator space (see Wu - et al. [1]_). + where $\hat{\mathbf{r}}$ is a point in the 3D propagator space (see + :footcite:t:`Wu2007`). References ---------- - .. [1] Wu Y. et al., "Hybrid diffusion imaging", NeuroImage, vol 36, - p. 617-629, 2007. + .. footbibliography:: """ msd = 0 c = self._shore_coef @@ -495,7 +472,9 @@ def shore_coeff(self): def shore_matrix(radial_order, zeta, gtab, tau=1 / (4 * np.pi**2)): - r"""Compute the SHORE matrix for modified Merlet's 3D-SHORE [1]_ + r"""Compute the SHORE matrix for modified Merlet's 3D-SHORE. + + See :footcite:p:`Merlet2013` for the definition. .. math:: :nowrap: @@ -530,9 +509,7 @@ def shore_matrix(radial_order, zeta, gtab, tau=1 / (4 * np.pi**2)): References ---------- - .. [1] Merlet S. et al., "Continuous diffusion signal, EAP and - ODF estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. + .. footbibliography:: """ @@ -568,7 +545,9 @@ def _kappa(zeta, n, ell): def shore_matrix_pdf(radial_order, zeta, rtab): - r"""Compute the SHORE propagator matrix [1]_" + r"""Compute the SHORE propagator matrix. + + See :footcite:p:`Merlet2013` for the definition. Parameters ---------- @@ -581,9 +560,7 @@ def shore_matrix_pdf(radial_order, zeta, rtab): References ---------- - .. [1] Merlet S. et al., "Continuous diffusion signal, EAP and - ODF estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. + .. footbibliography:: """ r, theta, phi = cart2sphere(rtab[:, 0], rtab[:, 1], rtab[:, 2]) @@ -612,7 +589,9 @@ def _kappa_pdf(zeta, n, ell): def shore_matrix_odf(radial_order, zeta, sphere_vertices): - r"""Compute the SHORE ODF matrix [1]_" + r"""Compute the SHORE ODF matrix. + + See :footcite:p:`Merlet2013` for the definition. Parameters ---------- @@ -625,9 +604,7 @@ def shore_matrix_odf(radial_order, zeta, sphere_vertices): References ---------- - .. [1] Merlet S. et al., "Continuous diffusion signal, EAP and - ODF estimation via Compressive Sensing in diffusion MRI", Medical - Image Analysis, 2013. + .. footbibliography:: """ r, theta, phi = cart2sphere( diff --git a/dipy/reconst/tests/test_ivim.py b/dipy/reconst/tests/test_ivim.py index dd30b95a3a..f833ac3133 100644 --- a/dipy/reconst/tests/test_ivim.py +++ b/dipy/reconst/tests/test_ivim.py @@ -3,13 +3,11 @@ The values of the various parameters used in the tests are inspired by the study of the IVIM model applied to MR images of the brain by -Federau, Christian, et al. [1]. +:footcite:t:`Federau2012`. References ---------- -.. [1] Federau, Christian, et al. "Quantitative measurement - of brain perfusion with intravoxel incoherent motion - MR imaging." Radiology 265.3 (2012): 874-881. +.. footbibliography:: """ import warnings diff --git a/dipy/segment/bundles.py b/dipy/segment/bundles.py index 1dff8bca03..36208c39b5 100644 --- a/dipy/segment/bundles.py +++ b/dipy/segment/bundles.py @@ -37,6 +37,8 @@ def check_range(streamline, gt, lt): def bundle_adjacency(dtracks0, dtracks1, threshold): """Find bundle adjacency between two given tracks/bundles + See :footcite:p:`Garyfallidis2012a` for further details about the method. + Parameters ---------- dtracks0 : Streamlines @@ -56,9 +58,7 @@ def bundle_adjacency(dtracks0, dtracks1, threshold): References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ d01 = bundles_distances_mdf(dtracks0, dtracks1) @@ -89,6 +89,8 @@ def bundle_adjacency(dtracks0, dtracks1, threshold): def ba_analysis(recognized_bundle, expert_bundle, *, nb_pts=20, threshold=6.0): """Calculates bundle adjacency score between two given bundles + See :footcite:p:`Garyfallidis2012a` for further details about the method. + Parameters ---------- recognized_bundle : Streamlines @@ -110,9 +112,7 @@ def ba_analysis(recognized_bundle, expert_bundle, *, nb_pts=20, threshold=6.0): References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ recognized_bundle = set_number_of_points(recognized_bundle, nb_pts) @@ -126,6 +126,8 @@ def ba_analysis(recognized_bundle, expert_bundle, *, nb_pts=20, threshold=6.0): def cluster_bundle(bundle, clust_thr, rng, *, nb_pts=20, select_randomly=500000): """Clusters bundles + See :footcite:p:`Garyfallidis2012a` for further details about the method. + Parameters ---------- bundle : Streamlines @@ -146,9 +148,7 @@ def cluster_bundle(bundle, clust_thr, rng, *, nb_pts=20, select_randomly=500000) References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ model_cluster_map = qbx_and_merge( @@ -166,6 +166,9 @@ def bundle_shape_similarity( """Calculates bundle shape similarity between two given bundles using bundle adjacency (BA) metric + See :footcite:p:`Garyfallidis2012a`, :footcite:p:`Chandio2020` for further + details about the method. + Parameters ---------- bundle1 : Streamlines @@ -189,15 +192,7 @@ def bundle_shape_similarity( References ---------- - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., Bullock, D., - Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and Garyfallidis, E. - Bundle analytics, a computational framework for investigating the - shapes and profiles of brain pathways across populations. - Sci Rep 10, 17149 (2020) - - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ if len(bundle1) == 0 or len(bundle2) == 0: @@ -235,7 +230,8 @@ def __init__( Extract bundles from a participants' tractograms using model bundles segmented from a different subject or an atlas of bundles. - See [Garyfallidis17]_ for the details. + + See :footcite:p:`Garyfallidis2018` for the details. Parameters ---------- @@ -268,9 +264,7 @@ def __init__( References ---------- - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. + .. footbibliography:: """ map_ind = np.zeros(len(streamlines)) for i in range(len(streamlines)): @@ -355,6 +349,8 @@ def recognize( ): """Recognize the model_bundle in self.streamlines + See :footcite:p:`Garyfallidis2018` for further details about the method. + Parameters ---------- model_bundle : Streamlines @@ -431,9 +427,7 @@ def recognize( References ---------- - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. + .. footbibliography:: """ if self.verbose: t = time() @@ -507,6 +501,9 @@ def refine( This time, search space is created using pruned bundle and not model bundle. + See :footcite:p:`Garyfallidis2018`, :footcite:p:`Chandio2020` for + further details about the method. + Parameters ---------- model_bundle : Streamlines @@ -577,15 +574,7 @@ def refine( References ---------- - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. - - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., - Bullock, D., Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and - Garyfallidis, E. Bundle analytics, a computational framework for - investigating the shapes and profiles of brain pathways across - populations. Sci Rep 10, 17149 (2020) + .. footbibliography:: """ if self.verbose: t = time() diff --git a/dipy/segment/clustering.py b/dipy/segment/clustering.py index 68e8a06438..fbaef118e4 100644 --- a/dipy/segment/clustering.py +++ b/dipy/segment/clustering.py @@ -441,14 +441,15 @@ def cluster(self, data, *, ordering=None): class QuickBundles(Clustering): - r"""Clusters streamlines using QuickBundles [Garyfallidis12]_. + r"""Clusters streamlines using QuickBundles. - Given a list of streamlines, the QuickBundles algorithm sequentially - assigns each streamline to its closest bundle in $\mathcal{O}(Nk)$ where - $N$ is the number of streamlines and $k$ is the final number of bundles. - If for a given streamline its closest bundle is farther than `threshold`, - a new bundle is created and the streamline is assigned to it except if the - number of bundles has already exceeded `max_nb_clusters`. + Given a list of streamlines, the QuickBundles algorithm + :footcite:p:`Garyfallidis2012a` sequentially assigns each streamline to its + closest bundle in $\mathcal{O}(Nk)$ where $N$ is the number of streamlines + and $k$ is the final number of bundles. If for a given streamline its + closest bundle is farther than `threshold`, a new bundle is created and the + streamline is assigned to it except if the number of bundles has already + exceeded `max_nb_clusters`. Parameters ---------- @@ -497,9 +498,7 @@ class QuickBundles(Clustering): References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ @warning_for_keywords() @@ -554,7 +553,9 @@ def cluster(self, streamlines, *, ordering=None): class QuickBundlesX(Clustering): - r"""Clusters streamlines using QuickBundlesX [Garyfallidis16]_. + r"""Clusters streamlines using QuickBundlesX. + + See :footcite:p:`Garyfallidis2016` for further details about the method. Parameters ---------- @@ -564,21 +565,13 @@ class QuickBundlesX(Clustering): as part of it. metric : str or `Metric` object (optional) The distance metric to use when comparing two streamlines. By default, - the Minimum average Direct-Flip (MDF) distance [Garyfallidis12]_ is - used and streamlines are automatically resampled so they have 12 - points. + the Minimum average Direct-Flip (MDF) distance + :footcite:p:`Garyfallidis2012a` is used and streamlines are + automatically resampled so they have 12 points. References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. - - .. [Garyfallidis16] Garyfallidis E. et al. QuickBundlesX: Sequential - clustering of millions of streamlines in multiple - levels of detail at record execution time. Proceedings - of the, International Society of Magnetic Resonance - in Medicine (ISMRM). Singapore, 4187, 2016. + .. footbibliography:: """ @warning_for_keywords() @@ -711,7 +704,7 @@ def _traverse(node, level=0): def qbx_and_merge( streamlines, thresholds, *, nb_pts=20, select_randomly=None, rng=None, verbose=False ): - """Run QuickBundlesX and then run again on the centroids of the last layer + """Run QuickBundlesX and then run again on the centroids of the last layer. Running again QuickBundles at a layer has the effect of merging some of the clusters that may be originally divided because of branching. @@ -719,6 +712,9 @@ def qbx_and_merge( QuickBundlesX speed. The merging phase has low cost because it is applied only on the centroids rather than the entire dataset. + See :footcite:p:`Garyfallidis2012a` and :footcite:p:`Garyfallidis2016` for + further details about the method. + Parameters ---------- streamlines : Streamlines @@ -742,15 +738,7 @@ def qbx_and_merge( References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. - - .. [Garyfallidis16] Garyfallidis E. et al. QuickBundlesX: Sequential - clustering of millions of streamlines in multiple - levels of detail at record execution time. Proceedings - of the, International Society of Magnetic Resonance - in Medicine (ISMRM). Singapore, 4187, 2016. + .. footbibliography:: """ t = time() len_s = len(streamlines) diff --git a/dipy/segment/clustering_algorithms.pyx b/dipy/segment/clustering_algorithms.pyx index be5544c831..e9a36306e1 100644 --- a/dipy/segment/clustering_algorithms.pyx +++ b/dipy/segment/clustering_algorithms.pyx @@ -68,6 +68,8 @@ def quickbundles(streamlines, Metric metric, double threshold, *, long max_nb_clusters=BIGGEST_INT, ordering=None): """ Clusters streamlines using QuickBundles. + See :footcite:p:`Garyfallidis2012a` for further details about the method. + Parameters ---------- streamlines : list of 2D arrays @@ -89,9 +91,7 @@ def quickbundles(streamlines, Metric metric, double threshold, *, References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ # Threshold of np.inf is not supported, set it to 'biggest_double' threshold = min(threshold, BIGGEST_DOUBLE) @@ -124,6 +124,9 @@ def quickbundles(streamlines, Metric metric, double threshold, *, def quickbundlesx(streamlines, Metric metric, thresholds, *, ordering=None): """ Clusters streamlines using QuickBundlesX. + See :footcite:p:`Garyfallidis2012a` and :footcite:p:`Garyfallidis2016` for + further details about the method. + Parameters ---------- streamlines : list of 2D arrays @@ -145,16 +148,7 @@ def quickbundlesx(streamlines, Metric metric, thresholds, *, ordering=None): References ---------- - - .. [Garyfallidis16] Garyfallidis E. et al. QuickBundlesX: Sequential - clustering of millions of streamlines in multiple - levels of detail at record execution time. Proceedings - of the, International Society of Magnetic Resonance - in Medicine (ISMRM). Singapore, 4187, 2016. - - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ if ordering is None: ordering = range(len(streamlines)) diff --git a/dipy/segment/fss.py b/dipy/segment/fss.py index 76f6d21f9d..366654cd13 100644 --- a/dipy/segment/fss.py +++ b/dipy/segment/fss.py @@ -26,7 +26,7 @@ def __init__( Generate the Binned K-D Tree structure with reference streamlines, using streamlines barycenter and mean-points. - See [StOnge2022]_ for further details. + See :footcite:p:`StOnge2022` for further details. Parameters ---------- @@ -53,9 +53,7 @@ def __init__( References ---------- - .. [StOnge2022] St-Onge E. et al. Fast Streamline Search: - An Exact Technique for Diffusion MRI Tractography. - Neuroinformatics, 2022. + .. footbibliography:: """ if max_radius <= 0.0: raise ValueError("max_radius needs to be a positive value") @@ -124,7 +122,8 @@ def radius_search(self, streamlines, radius, *, use_negative=True): """Radius Search using Fast Streamline Search For each given streamlines, return all reference streamlines - within the given radius. See [StOnge2022]_ for further details. + within the given radius. See :footcite:p:`StOnge2022` for further + details. Parameters ---------- @@ -150,9 +149,7 @@ def radius_search(self, streamlines, radius, *, use_negative=True): References ---------- - .. [StOnge2022] St-Onge E. et al. Fast Streamline Search: - An Exact Technique for Diffusion MRI Tractography. - Neuroinformatics, 2022. + .. footbibliography:: """ if radius > self.max_radius: raise ValueError( diff --git a/dipy/segment/metric.py b/dipy/segment/metric.py index c74e774f10..a0bbf6fa82 100644 --- a/dipy/segment/metric.py +++ b/dipy/segment/metric.py @@ -26,11 +26,13 @@ def mdf(s1, s2): - """Computes the MDF (Minimum average Direct-Flip) distance - [Garyfallidis12]_ between two streamlines. + """Computes the MDF (Minimum average Direct-Flip) distance between two + streamlines. Streamlines must have the same number of points. + See :footcite:p:`Garyfallidis2012a` for a definition of the distance. + Parameters ---------- s1 : 2D array @@ -45,9 +47,7 @@ def mdf(s1, s2): References ---------- - .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ return dist(MinimumAverageDirectFlipMetric(), s1, s2) diff --git a/dipy/sims/phantom.py b/dipy/sims/phantom.py index ec2fc5a854..62a10252e7 100644 --- a/dipy/sims/phantom.py +++ b/dipy/sims/phantom.py @@ -38,16 +38,14 @@ def add_noise(vol, *, snr=1.0, S0=None, noise_type="rician", rng=None): Notes ----- - SNR is defined here, following [1]_, as ``S0 / sigma``, where ``sigma`` is - the standard deviation of the two Gaussian distributions forming the real - and imaginary components of the Rician noise distribution (see [2]_). + SNR is defined here, following :footcite:p:`Descoteaux2007`, as + ``S0 / sigma``, where ``sigma`` is the standard deviation of the two + Gaussian distributions forming the real and imaginary components of the + Rician noise distribution (see :footcite:p:`Gudbjartsson1995`). References ---------- - .. [1] Descoteaux, Angelino, Fitzgibbons and Deriche (2007) Regularized, - fast and robust q-ball imaging. MRM, 58: 497-510 - .. [2] Gudbjartson and Patz (2008). The Rician distribution of noisy MRI - data. MRM 34: 910-914. + .. footbibliography:: Examples -------- diff --git a/dipy/sims/voxel.py b/dipy/sims/voxel.py index 66c654d9e0..6181bfc272 100644 --- a/dipy/sims/voxel.py +++ b/dipy/sims/voxel.py @@ -101,16 +101,14 @@ def add_noise(signal, snr, S0, *, noise_type="rician", rng=None): Notes ----- - SNR is defined here, following [1]_, as ``S0 / sigma``, where ``sigma`` is - the standard deviation of the two Gaussian distributions forming the real - and imaginary components of the Rician noise distribution (see [2]_). + SNR is defined here, following :footcite:p:`Descoteaux2007`, as + ``S0 / sigma``, where ``sigma`` is the standard deviation of the two + Gaussian distributions forming the real and imaginary components of the + Rician noise distribution (see :footcite:p:`Gudbjartsson1995`). References ---------- - .. [1] Descoteaux, Angelino, Fitzgibbons and Deriche (2007) Regularized, - fast and robust q-ball imaging. MRM, 58: 497-510 - .. [2] Gudbjartson and Patz (2008). The Rician distribution of noisy MRI - data. MRM 34: 910-914. + .. footbibliography:: Examples -------- @@ -148,6 +146,8 @@ def sticks_and_ball( ): """Simulate the signal for a Sticks & Ball model. + See :footcite:p:`Behrens2007` for a definition of the Sticks & Ball model. + Parameters ---------- gtab : GradientTable @@ -175,9 +175,7 @@ def sticks_and_ball( References ---------- - .. [1] Behrens et al., "Probabilistic diffusion - tractography with multiple fiber orientations: what can we gain?", - Neuroimage, 2007. + .. footbibliography:: """ fractions = [f / 100.0 for f in fractions] @@ -204,8 +202,12 @@ def sticks_and_ball( def callaghan_perpendicular(q, radius): r"""Calculates the perpendicular diffusion signal E(q) in a cylinder of - radius R using the Soderman model [1]_. Assumes that the pulse length - is infinitely short and the diffusion time is infinitely long. + radius R using the Soderman model. + + Assumes that the pulse length is infinitely short and the diffusion time is + infinitely long. + + See :footcite:p:`Soderman1995` for details about the Soderman model. Parameters ---------- @@ -221,9 +223,7 @@ def callaghan_perpendicular(q, radius): References ---------- - .. [1] Söderman, Olle, and Bengt Jönsson. "Restricted diffusion in - cylindrical geometry." Journal of Magnetic Resonance, Series A - 117.1 (1995): 94-97. + .. footbibliography:: """ # Eq. [6] in the paper @@ -269,12 +269,16 @@ def cylinders_and_ball_soderman( snr=20, ): r"""Calculates the three-dimensional signal attenuation E(q) originating - from within a cylinder of radius R using the Soderman approximation [1]_. - The diffusion signal is assumed to be separable perpendicular and parallel - to the cylinder axis [2]_. + from within a cylinder of radius R using the Soderman approximation. + + The diffusion signal is assumed to be separable perpendicular and parallel + to the cylinder axis :footcite:p:`Assaf2004`. + This function is basically an extension of the ball and stick model. Setting the radius to zero makes them equivalent. + See :footcite:p:`Soderman1995` for details about the Soderman model. + Parameters ---------- gtab : GradientTable @@ -304,12 +308,7 @@ def cylinders_and_ball_soderman( References ---------- - .. [1] Söderman, Olle, and Bengt Jönsson. "Restricted diffusion in - cylindrical geometry." Journal of Magnetic Resonance, Series A - 117.1 (1995): 94-97. - .. [2] Assaf, Yaniv, et al. "New modeling and experimental framework to - characterize hindered and restricted water diffusion in brain white - matter." Magnetic Resonance in Medicine 52.5 (2004): 965-978. + .. footbibliography:: """ qvals = np.sqrt(gtab.bvals / tau) / (2 * np.pi) @@ -342,6 +341,8 @@ def cylinders_and_ball_soderman( def single_tensor(gtab, S0=1, *, evals=None, evecs=None, snr=None, rng=None): """Simulate diffusion-weighted signals with a single tensor. + See :footcite:p:`Stejskal1965`, :footcite:p:`Descoteaux2008b`. + Parameters ---------- gtab : GradientTable @@ -370,12 +371,7 @@ def single_tensor(gtab, S0=1, *, evals=None, evecs=None, snr=None, rng=None): References ---------- - .. [1] M. Descoteaux, "High Angular Resolution Diffusion MRI: from Local - Estimation to Segmentation and Tractography", PhD thesis, - University of Nice-Sophia Antipolis, p. 42, 2008. - .. [2] E. Stejskal and J. Tanner, "Spin diffusion measurements: spin echos - in the presence of a time-dependent field gradient", Journal of - Chemical Physics, nr. 42, pp. 288--292, 1965. + .. footbibliography:: """ if rng is None: @@ -495,6 +491,8 @@ def multi_tensor_dki( r"""Simulate the diffusion-weight signal, diffusion and kurtosis tensors based on the DKI model + See :footcite:p:`NetoHenriques2015` for further details. + Parameters ---------- gtab : GradientTable @@ -547,10 +545,7 @@ def multi_tensor_dki( References ---------- - .. [1] R. Neto Henriques et al., "Exploring the 3D geometry of the - diffusion kurtosis tensor - Impact on the development of robust - tractography procedures and novel biomarkers", NeuroImage (2015) - 111, 85-99. + .. footbibliography:: """ if np.round(np.sum(fractions), 2) != 100.0: @@ -635,14 +630,12 @@ def kurtosis_element(D_comps, frac, ind_i, ind_j, ind_k, ind_l, *, DT=None, MD=N Notes ----- - wijkl is calculated using equation 8 given in [1]_ + wijkl is calculated using equation 8 given in + :footcite:p:`NetoHenriques2015`. References ---------- - .. [1] R. Neto Henriques et al., "Exploring the 3D geometry of the - diffusion kurtosis tensor - Impact on the development of robust - tractography procedures and novel biomarkers", NeuroImage (2015) - 111, 85-99. + .. footbibliography:: """ if DT is None: @@ -678,6 +671,8 @@ def dki_signal(gtab, dt, kt, *, S0=150, snr=None): tensors of a single voxel. Simulations are performed assuming the DKI model. + See :footcite:p:`NetoHenriques2015` for further details. + Parameters ---------- gtab : GradientTable @@ -702,10 +697,7 @@ def dki_signal(gtab, dt, kt, *, S0=150, snr=None): References ---------- - .. [1] R. Neto Henriques et al., "Exploring the 3D geometry of the - diffusion kurtosis tensor - Impact on the development of robust - tractography procedures and novel biomarkers", NeuroImage (2015) - 111, 85-99. + .. footbibliography:: """ dt = np.array(dt) @@ -729,6 +721,8 @@ def dki_signal(gtab, dt, kt, *, S0=150, snr=None): def single_tensor_odf(r, *, evals=None, evecs=None): """Simulated ODF with a single tensor. + See :footcite:p:`Aganj2010` for further details. + Parameters ---------- r : (N,3) or (M,N,3) ndarray @@ -748,10 +742,7 @@ def single_tensor_odf(r, *, evals=None, evecs=None): References ---------- - .. [1] Aganj et al., "Reconstruction of the Orientation Distribution - Function in Single- and Multiple-Shell q-Ball Imaging Within - Constant Solid Angle", Magnetic Resonance in Medicine, nr. 64, - pp. 554--566, 2010. + .. footbibliography:: """ if evals is None: @@ -849,6 +840,8 @@ def multi_tensor_odf(odf_verts, mevals, angles, fractions): def single_tensor_rtop(*, evals=None, tau=1.0 / (4 * np.pi**2)): """Simulate a Single-Tensor rtop. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- evals : 1D arrays, @@ -864,8 +857,7 @@ def single_tensor_rtop(*, evals=None, tau=1.0 / (4 * np.pi**2)): References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and Its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ if evals is None: @@ -879,6 +871,8 @@ def single_tensor_rtop(*, evals=None, tau=1.0 / (4 * np.pi**2)): def multi_tensor_rtop(mf, *, mevals=None, tau=1 / (4 * np.pi**2)): """Simulate a Multi-Tensor rtop. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- mf : sequence of floats, bounded [0,1] @@ -896,8 +890,7 @@ def multi_tensor_rtop(mf, *, mevals=None, tau=1 / (4 * np.pi**2)): References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and Its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ rtop = 0 @@ -916,6 +909,8 @@ def multi_tensor_rtop(mf, *, mevals=None, tau=1 / (4 * np.pi**2)): def single_tensor_pdf(r, *, evals=None, evecs=None, tau=1 / (4 * np.pi**2)): """Simulated ODF with a single tensor. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- r : (N,3) or (M,N,3) ndarray @@ -938,8 +933,7 @@ def single_tensor_pdf(r, *, evals=None, evecs=None, tau=1 / (4 * np.pi**2)): References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and Its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ if evals is None: @@ -967,6 +961,8 @@ def single_tensor_pdf(r, *, evals=None, evecs=None, tau=1 / (4 * np.pi**2)): def multi_tensor_pdf(pdf_points, mevals, angles, fractions, *, tau=1 / (4 * np.pi**2)): """Simulate a Multi-Tensor ODF. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- pdf_points : (N, 3) ndarray @@ -989,8 +985,7 @@ def multi_tensor_pdf(pdf_points, mevals, angles, fractions, *, tau=1 / (4 * np.p References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ mf = [f / 100.0 for f in fractions] @@ -1014,6 +1009,8 @@ def multi_tensor_pdf(pdf_points, mevals, angles, fractions, *, tau=1 / (4 * np.p def single_tensor_msd(*, evals=None, tau=1 / (4 * np.pi**2)): """Simulate a Multi-Tensor rtop. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- evals : 1D arrays, @@ -1029,8 +1026,7 @@ def single_tensor_msd(*, evals=None, tau=1 / (4 * np.pi**2)): References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and Its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ if evals is None: @@ -1044,6 +1040,8 @@ def single_tensor_msd(*, evals=None, tau=1 / (4 * np.pi**2)): def multi_tensor_msd(mf, *, mevals=None, tau=1 / (4 * np.pi**2)): """Simulate a Multi-Tensor rtop. + See :footcite:p:`Cheng2012` for further details. + Parameters ---------- mf : sequence of floats, bounded [0,1] @@ -1061,8 +1059,7 @@ def multi_tensor_msd(mf, *, mevals=None, tau=1 / (4 * np.pi**2)): References ---------- - .. [1] Cheng J., "Estimation and Processing of Ensemble Average Propagator - and Its Features in Diffusion MRI", PhD Thesis, 2012. + .. footbibliography:: """ msd = 0 diff --git a/dipy/stats/analysis.py b/dipy/stats/analysis.py index f66d24cf6b..99ce49d82e 100644 --- a/dipy/stats/analysis.py +++ b/dipy/stats/analysis.py @@ -112,6 +112,8 @@ def assignment_map(target_bundle, model_bundle, no_disks): Calculates assignment maps of the target bundle with reference to model bundle centroids. + See :footcite:p:`Chandio2020` for further details about the method. + Parameters ---------- target_bundle : streamlines @@ -129,11 +131,7 @@ def assignment_map(target_bundle, model_bundle, no_disks): References ---------- - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., Bullock, D., - Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and Garyfallidis, E. - Bundle analytics, a computational framework for investigating the - shapes and profiles of brain pathways across populations. - Sci Rep 10, 17149 (2020) + .. footbibliography:: """ @@ -246,7 +244,7 @@ def afq_profile( Calculates a summarized profile of data for a bundle or tract along its length. - Follows the approach outlined in [Yeatman2012]_. + Follows the approach outlined in :footcite:p:`Yeatman2012`. Parameters ---------- @@ -291,10 +289,7 @@ def afq_profile( References ---------- - .. [Yeatman2012] Yeatman, Jason D., Robert F. Dougherty, - Nathaniel J. Myall, Brian A. Wandell, and Heidi M. Feldman. 2012. - "Tract Profiles of White Matter Properties: Automating Fiber-Tract - Quantification" PloS One 7 (11): e49790. + .. footbibliography:: """ if orient_by is not None: diff --git a/dipy/stats/qc.py b/dipy/stats/qc.py index fe3b5ed4d4..41746f022a 100644 --- a/dipy/stats/qc.py +++ b/dipy/stats/qc.py @@ -71,8 +71,8 @@ def neighboring_dwi_correlation(dwi_data, gtab, *, mask=None): """Calculate the Neighboring DWI Correlation (NDC) from dMRI data. Using a mask is highly recommended, otherwise the FOV will influence the - correlations. According to [Yeh2019]_, an NDC less than 0.4 indicates a - low quality image. + correlations. According to :footcite:t:`Yeh2019`, an NDC less than 0.4 + indicates a low quality image. Parameters ---------- @@ -90,10 +90,7 @@ def neighboring_dwi_correlation(dwi_data, gtab, *, mask=None): References ---------- - - .. [Yeh2019] Yeh, Fang-Cheng, et al. "Differential tractography as a - track-based biomarker for neuronal injury." - NeuroImage 202 (2019): 116131. + .. footbibliography:: """ diff --git a/dipy/stats/resampling.py b/dipy/stats/resampling.py index 4078cf74d3..4c06aeabf1 100644 --- a/dipy/stats/resampling.py +++ b/dipy/stats/resampling.py @@ -13,12 +13,12 @@ def bs_se(bs_pdf): def bootstrap(x, *, statistic=bs_se, B=1000, alpha=0.95, rng=None): - """ - - Bootstrap resampling [1]_ to accurately estimate the standard error and + """Bootstrap resampling to accurately estimate the standard error and confidence interval of a desired statistic of a probability distribution function (pdf). + See :footcite:p`Efron1979` for further details about the method. + Parameters ---------- x : ndarray (N, 1) @@ -62,8 +62,7 @@ def bootstrap(x, *, statistic=bs_se, B=1000, alpha=0.95, rng=None): References ---------- - .. [1] Efron, B., 1979. 1977 Rietz lecture--Bootstrap methods--Another - look at the jackknife. Ann. Stat. 7, 1-26. + .. footbibliography:: """ N = len(x) @@ -82,6 +81,8 @@ def bootstrap(x, *, statistic=bs_se, B=1000, alpha=0.95, rng=None): def abc(x, *, statistic=bs_se, alpha=0.05, eps=1e-5): """Calculate the bootstrap confidence interval by approximating the BCa. + See :footcite:p`DiCiccio1996` for further details about the method. + Parameters ---------- x : np.ndarray @@ -111,8 +112,7 @@ def abc(x, *, statistic=bs_se, alpha=0.05, eps=1e-5): References ---------- - .. [2] DiCiccio, T.J., Efron, B., 1996. Bootstrap Confidence Intervals. - Statistical Science. 11, 3, 189-228. + .. footbibliography:: """ # define base variables -- n, p_0, sigma_hat, delta_hat @@ -223,9 +223,10 @@ def __tt_dot_dot(i, x, p_0, statistic, eps): def jackknife(pdf, *, statistic=np.std, M=None, rng=None): - """ - Jackknife resampling [3]_ to quickly estimate the bias and standard - error of a desired statistic in a probability distribution function (pdf). + """Jackknife resampling to quickly estimate the bias and standard error of a + desired statistic in a probability distribution function (pdf). + + See :footcite:p`Efron1979` for further details about the method. Parameters ---------- @@ -275,8 +276,7 @@ def jackknife(pdf, *, statistic=np.std, M=None, rng=None): References ---------- - .. [3] Efron, B., 1979. 1977 Rietz lecture--Bootstrap methods--Another - look at the jackknife. Ann. Stat. 7, 1-26. + .. footbibliography:: """ N = len(pdf) diff --git a/dipy/tracking/fbcmeasures.pyx b/dipy/tracking/fbcmeasures.pyx index f7f4b95ea8..2aa4734d8f 100644 --- a/dipy/tracking/fbcmeasures.pyx +++ b/dipy/tracking/fbcmeasures.pyx @@ -29,6 +29,9 @@ cdef class FBCMeasures: """ Compute the fiber to bundle coherence measures for a set of streamlines. + See :footcite:p`Meesters2016b` and :footcite:p:`Portegies2015b` for + further details about the method. + Parameters ---------- streamlines : list @@ -52,15 +55,7 @@ cdef class FBCMeasures: References ---------- - [Meesters2016_HBM] S. Meesters, G. Sanguinetti, E. Garyfallidis, - J. Portegies, P. Ossenblok, R. Duits. (2016) Cleaning - output of tractography via fiber to bundle coherence, - a new open source implementation. Human Brain Mapping - conference 2016. - [Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters, - G.Girard, and R. Duits. (2015) Improving Fiber Alignment - in HARDI by Combining Contextual PDE flow with - Constrained Spherical Deconvolution. PLoS One. + .. footbibliography:: """ self.compute(streamlines, kernel, diff --git a/dipy/tracking/life.py b/dipy/tracking/life.py index 24a8605b24..1d05bbb79e 100644 --- a/dipy/tracking/life.py +++ b/dipy/tracking/life.py @@ -1,10 +1,10 @@ """ This is an implementation of the Linear Fascicle Evaluation (LiFE) algorithm -described in: +described in :footcite:p:`Pestilli2014`. -Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell B.A. (2014). Validation -and statistical inference in living connectomes. Nature Methods 11: -1058-1063. doi:10.1038/nmeth.3098 +References +---------- +.. footbibliography:: """ import numpy as np @@ -311,11 +311,12 @@ class FiberModel(ReconstModel): Notes ----- - This is an implementation of the LiFE model described in [1]_ + This is an implementation of the LiFE model described in + :footcite:p:`Pestilli2014`. - [1] Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell - B.A. (2014). Validation and statistical inference in living - connectomes. Nature Methods. + References + ---------- + .. footbibliography:: """ def __init__(self, gtab): diff --git a/dipy/tracking/local_tracking.py b/dipy/tracking/local_tracking.py index cc0cf24889..4e3a6220bf 100644 --- a/dipy/tracking/local_tracking.py +++ b/dipy/tracking/local_tracking.py @@ -296,7 +296,9 @@ def __init__( initial_directions=None, ): r"""A streamline generator using the particle filtering tractography - method [1]_. + method. + + See :footcite:p:`Girard2014` for further details about the method. Parameters ---------- @@ -366,9 +368,7 @@ def __init__( References ---------- - .. [1] Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. - Towards quantitative connectivity analysis: reducing - tractography biases. NeuroImage, 98, 266-278, 2014. + .. footbibliography:: """ if not isinstance(stopping_criterion, AnatomicalStoppingCriterion): diff --git a/dipy/tracking/stopping_criterion.pyx b/dipy/tracking/stopping_criterion.pyx index 905df67e5f..6f5609d0a2 100644 --- a/dipy/tracking/stopping_criterion.pyx +++ b/dipy/tracking/stopping_criterion.pyx @@ -166,11 +166,14 @@ cdef class AnatomicalStoppingCriterion(StoppingCriterion): cdef class ActStoppingCriterion(AnatomicalStoppingCriterion): r""" - Anatomically-Constrained Tractography (ACT) stopping criterion from [1]_. + Anatomically-Constrained Tractography (ACT) stopping criterion. + + See :footcite:p:`Smith2012` for further details about the method. + This implements the use of partial volume fraction (PVE) maps to - determine when the tracking stops. The proposed ([1]_) method that - cuts streamlines going through subcortical gray matter regions is - not implemented here. The backtracking technique for + determine when the tracking stops. The proposed method + :footcite:p:`Smith2012` that cuts streamlines going through subcortical gray + matter regions is not implemented here. The backtracking technique for streamlines reaching INVALIDPOINT is not implemented either. cdef: double interp_out_double[1] @@ -179,10 +182,7 @@ cdef class ActStoppingCriterion(AnatomicalStoppingCriterion): References ---------- - .. [1] Smith, R. E., Tournier, J.-D., Calamante, F., & Connelly, A. - "Anatomically-constrained tractography: Improved diffusion MRI - streamlines tractography through effective use of anatomical - information." NeuroImage, 63(3), 1924-1938, 2012. + .. footbibliography:: """ def __cinit__(self, include_map, exclude_map): @@ -226,9 +226,10 @@ cdef class ActStoppingCriterion(AnatomicalStoppingCriterion): cdef class CmcStoppingCriterion(AnatomicalStoppingCriterion): r""" - Continuous map criterion (CMC) stopping criterion from [1]_. + Continuous map criterion (CMC) stopping criterion. + This implements the use of partial volume fraction (PVE) maps to - determine when the tracking stops. + determine when the tracking stops :footcite:p:`Girard2014`. cdef: double interp_out_double[1] @@ -240,9 +241,7 @@ cdef class CmcStoppingCriterion(AnatomicalStoppingCriterion): References ---------- - .. [1] Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. - "Towards quantitative connectivity analysis: reducing tractography biases." - NeuroImage, 98, 266-278, 2014. + .. footbibliography:: """ def __cinit__(self, include_map, exclude_map, step_size, average_voxel_size): diff --git a/dipy/tracking/streamline.py b/dipy/tracking/streamline.py index 45cd4407c8..b67a941e2a 100644 --- a/dipy/tracking/streamline.py +++ b/dipy/tracking/streamline.py @@ -349,8 +349,8 @@ def cluster_confidence( in a bundle of 100 streamlines that follow similar pathways has a high cci. - See: Jordan et al. 2017 - (Based on streamline MDF distance from Garyfallidis et al. 2012) + See :footcite:p:`Jordan2018` (based on the streamline MDF distance from + :footcite:t:`Garyfallidis2012a`). Parameters ---------- @@ -381,13 +381,7 @@ def cluster_confidence( References ---------- - [Jordan17] Jordan K. Et al., Cluster Confidence Index: A Streamline-Wise - Pathway Reproducibility Metric for Diffusion-Weighted MRI Tractography, - Journal of Neuroimaging, vol 28, no 1, 2017. - - [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for - tractography simplification, Frontiers in Neuroscience, - vol 6, no 175, 2012. + .. footbibliography:: """ diff --git a/dipy/tracking/streamlinespeed.pyx b/dipy/tracking/streamlinespeed.pyx index cb1128e34c..4dad04b41c 100644 --- a/dipy/tracking/streamlinespeed.pyx +++ b/dipy/tracking/streamlinespeed.pyx @@ -541,22 +541,23 @@ cdef cnp.npy_intp c_compress_streamline(Streamline streamline, Streamline out, @warning_for_keywords() def compress_streamlines(streamlines, *, tol_error=0.01, max_segment_length=10): - """ Compress streamlines by linearization as in [Presseau15]_. + """ Compress streamlines by linearization. - The compression consists in merging consecutive segments that are - nearly collinear. The merging is achieved by removing the point the two - segments have in common. + The compression :footcite:p:`Presseau2015` consists in merging consecutive + segments that are nearly collinear. The merging is achieved by removing the + point the two segments have in common. - The linearization process [Presseau15]_ ensures that every point being - removed are within a certain margin (in mm) of the resulting streamline. - Recommendations for setting this margin can be found in [Presseau15]_ - (in which they called it tolerance error). + The linearization process :footcite:p:`Presseau2015` ensures that every + point being removed are within a certain margin (in mm) of the resulting + streamline. Recommendations for setting this margin can be found in + :footcite:p:`Presseau2015` (in which they called it tolerance error). The compression also ensures that two consecutive points won't be too far from each other (precisely less or equal than `max_segment_length`mm). - This is a tradeoff to speed up the linearization process [Rheault15]_. A low - value will result in a faster linearization but low compression, whereas - a high value will result in a slower linearization but high compression. + This is a tradeoff to speed up the linearization process + :footcite:p:`Rheault2015`. A low value will result in a faster linearization + but low compression, whereas a high value will result in a slower + linearization but high compression. Parameters ---------- @@ -568,7 +569,8 @@ def compress_streamlines(streamlines, *, tol_error=0.01, max_segment_length=10): streamlines. max_segment_length : float (optional) Maximum length in mm of any given segment produced by the compression. - The default is 10mm. (In [Presseau15]_, they used a value of `np.inf`). + The default is 10mm. (In :footcite:p:`Presseau2015` they used a value of + `np.inf`). Returns ------- @@ -600,16 +602,11 @@ def compress_streamlines(streamlines, *, tol_error=0.01, max_segment_length=10): Notes ----- Be aware that compressed streamlines have variable step sizes. One needs to - be careful when computing streamlines-based metrics [Houde15]_. + be careful when computing streamlines-based metrics :footcite:p:`Houde2015`. References ---------- - .. [Presseau15] Presseau C. et al., A new compression format for fiber - tracking datasets, NeuroImage, no 109, 73-83, 2015. - .. [Rheault15] Rheault F. et al., Real Time Interaction with Millions of - Streamlines, ISMRM, 2015. - .. [Houde15] Houde J.-C. et al. How to Avoid Biased Streamlines-Based - Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015. + .. footbibliography:: """ only_one_streamlines = False if type(streamlines) is cnp.ndarray: diff --git a/dipy/tracking/utils.py b/dipy/tracking/utils.py index e87dc77fc3..041e18dfeb 100644 --- a/dipy/tracking/utils.py +++ b/dipy/tracking/utils.py @@ -612,6 +612,9 @@ def target_line_based(streamlines, affine, target_mask, *, include=True): This function never returns single-point streamlines, whatever the value of `include`. + See :footcite:`Bresenham1965` and :footcite:p:`Houde2015` for further + details about the method. + Parameters ---------- streamlines : iterable @@ -634,10 +637,7 @@ def target_line_based(streamlines, affine, target_mask, *, include=True): References ---------- - [Bresenham5] Bresenham, Jack Elton. "Algorithm for computer control of a - digital plotter", IBM Systems Journal, vol 4, no. 1, 1965. - [Houde15] Houde et al. How to avoid biased streamlines-based metrics for - streamlines with variable step sizes, ISMRM 2015. + .. footbibliography:: See Also -------- @@ -1010,6 +1010,8 @@ def _as_segments(streamline, break_points): def max_angle_from_curvature(min_radius_curvature, step_size): """Get the maximum deviation angle from the minimum radius curvature. + See :footcite:p:`Tournier2012` for further details about the method. + Parameters ---------- min_radius_curvature: float @@ -1025,8 +1027,7 @@ def max_angle_from_curvature(min_radius_curvature, step_size): References ---------- - For more information: - https://onlinelibrary.wiley.com/doi/full/10.1002/ima.22005 + .. footbibliography:: """ max_angle = 2.0 * np.arcsin(step_size / (2.0 * min_radius_curvature)) @@ -1041,6 +1042,8 @@ def max_angle_from_curvature(min_radius_curvature, step_size): def min_radius_curvature_from_angle(max_angle, step_size): """Get minimum radius of curvature from a deviation angle. + See :footcite:p:`Tournier2012` for further details about the method. + Parameters ---------- max_angle: float @@ -1057,8 +1060,7 @@ def min_radius_curvature_from_angle(max_angle, step_size): References ---------- - More information: - https://onlinelibrary.wiley.com/doi/full/10.1002/ima.22005 + .. footbibliography:: """ if np.isnan(max_angle) or max_angle > np.pi / 2 or max_angle <= 0: diff --git a/dipy/viz/horizon/app.py b/dipy/viz/horizon/app.py index f35811095c..3d7988a427 100644 --- a/dipy/viz/horizon/app.py +++ b/dipy/viz/horizon/app.py @@ -85,8 +85,8 @@ def __init__( roi_colors=(1, 0, 0), surface_colors=((1, 0, 0),), ): - """Interactive medical visualization - Invert the Horizon! [Horizon_ISMRM19]_. - + """Interactive medical visualization - Invert the Horizon! + :footcite:p:`Garyfallidis2019`. Parameters ---------- @@ -158,11 +158,7 @@ def __init__( References ---------- - .. [Horizon_ISMRM19] Garyfallidis E., M-A. Cote, B.Q. Chandio, - S. Fadnavis, J. Guaje, R. Aggarwal, E. St-Onge, K.S. Juneja, - S. Koudoro, D. Reagan, DIPY Horizon: fast, modular, unified and - adaptive visualization, Proceedings of: International Society of - Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019. + .. footbibliography:: """ if not has_fury: raise ImportError( @@ -753,8 +749,9 @@ def horizon( recorded_events=None, return_showm=False, ): - """Interactive medical visualization - Invert the Horizon! [Horizon_ISMRM19]_. + """Interactive medical visualization - Invert the Horizon! + See :footcite:p:`Garyfallidis2019` for further details about Horizon. Parameters ---------- @@ -823,11 +820,7 @@ def horizon( References ---------- - .. [Horizon_ISMRM19] Garyfallidis E., M-A. Cote, B.Q. Chandio, - S. Fadnavis, J. Guaje, R. Aggarwal, E. St-Onge, K.S. Juneja, - S. Koudoro, D. Reagan, DIPY Horizon: fast, modular, unified and - adaptive visualization, Proceedings of: International Society of - Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019. + .. footbibliography:: """ hz = Horizon( diff --git a/dipy/workflows/align.py b/dipy/workflows/align.py index 6ed10f8696..996b426761 100644 --- a/dipy/workflows/align.py +++ b/dipy/workflows/align.py @@ -154,6 +154,9 @@ def run( For efficiency we apply the registration on cluster centroids and remove small clusters. + See :footcite:p:`Garyfallidis2014`, :footcite:p:`Garyfallidis2015`, + :footcite:p:`Garyfallidis2018` for further details. + Parameters ---------- static_files : string @@ -201,20 +204,11 @@ def run( The order of operations is the following. First short or long streamlines are removed. Second the tractogram or a random selection of the tractogram is clustered with QuickBundlesX. Then SLR - [Garyfallidis15]_ is applied. + :footcite:p:`Garyfallidis2015` is applied. References ---------- - .. [Garyfallidis15] Garyfallidis et al. "Robust and efficient linear - registration of white-matter fascicles in the space of - streamlines", NeuroImage, 117, 124--140, 2015 - - .. [Garyfallidis14] Garyfallidis et al., "Direct native-space fiber - bundle alignment for group comparisons", ISMRM, 2014. - - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration - and clustering, NeuroImage, 2017. + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -974,8 +968,8 @@ def run( ): """BundleWarp: streamline-based nonlinear registration. - BundleWarp is nonrigid registration method for deformable registration - of white matter tracts. + BundleWarp :footcite:p:`Chandio2023` is a nonrigid registration method + for deformable registration of white matter tracts. Parameters ---------- @@ -1018,8 +1012,7 @@ def run( References ---------- - .. [Chandio2023] Chandio et al. "BundleWarp, streamline-based nonlinear - registration of white matter tracts." bioRxiv (2023): 2023-01. + .. footbibliography:: """ logging.info(f"Loading static file {static_file}") diff --git a/dipy/workflows/denoise.py b/dipy/workflows/denoise.py index 1b8029b604..baf35f1ef6 100644 --- a/dipy/workflows/denoise.py +++ b/dipy/workflows/denoise.py @@ -40,9 +40,9 @@ def run( ): """Workflow for Patch2Self denoising method. - It applies patch2self denoising on each file found by 'globing' - ``input_file`` and ``bval_file``. It saves the results in a directory - specified by ``out_dir``. + It applies patch2self denoising :footcite:p:`Fadnavis2020` on each file + found by 'globing' ``input_file`` and ``bval_file``. It saves the + results in a directory specified by ``out_dir``. Parameters ---------- @@ -85,9 +85,7 @@ def run( References ---------- - .. [Fadnavis20] S. Fadnavis, J. Batson, E. Garyfallidis, Patch2Self: - Denoising Diffusion MRI with Self-supervised Learning, - Advances in Neural Information Processing Systems 33 (2020) + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -136,11 +134,11 @@ def run( out_dir="", out_denoised="dwi_nlmeans.nii.gz", ): - """Workflow wrapping the nlmeans denoising method [Descoteaux08]_. + """Workflow wrapping the nlmeans denoising method. - It applies nlmeans denoise on each file found by 'globing' - ``input_files`` and saves the results in a directory specified by - ``out_dir``. + It applies nlmeans denoise :footcite:p:`Descoteaux2008a` on each file + found by 'globing' ``input_files`` and saves the results in a directory + specified by ``out_dir``. Parameters ---------- @@ -163,10 +161,7 @@ def run( References ---------- - .. [Descoteaux08] Descoteaux, Maxime and Wiest-Daesslé, Nicolas and - Prima, Sylvain and Barillot, Christian and Deriche, Rachid. - Impact of Rician Adapted Non-Local Means Filtering on - HARDI, MICCAI 2008 + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -218,6 +213,8 @@ def run( ): r"""Workflow wrapping LPCA denoising method. + See :footcite:p:`Veraart2016a` for further details about the method. + Parameters ---------- input_files : string @@ -231,8 +228,8 @@ def run( multiple bvectors files at once. sigma : float, optional Standard deviation of the noise estimated from the data. - Default 0: it means sigma value estimation with the Manjon2013 - algorithm [3]_. + 0 means sigma value estimation following the algorithm in + :footcite:t:`Manjon2013`. b0_threshold : float, optional Threshold used to find b0 volumes. bvecs_tol : float, optional @@ -256,10 +253,10 @@ def run( \tau = (\tau_{factor} \sigma)^2 - \tau_{factor} can be change to adjust the relationship between the - noise standard deviation and the threshold \tau. If \tau_{factor} - is set to None, it will be automatically calculated using the - Marcenko-Pastur distribution [2]_. + $\tau_{factor}$ can be change to adjust the relationship between the + noise standard deviation and the threshold $\tau$. If + $\tau_{factor}$ is set to None, it will be automatically calculated + using the Marcenko-Pastur distribution :footcite:p`Veraart2016b`. out_dir : string, optional Output directory. (default current directory) out_denoised : string, optional @@ -267,19 +264,7 @@ def run( References ---------- - .. [1] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random - matrix theory. Neuroimage 142:394-406. - doi: 10.1016/j.neuroimage.2016.08.016 - - .. [2] Veraart J, Fieremans E, Novikov DS. 2016. Diffusion MRI noise - mapping using random matrix theory. Magnetic Resonance in Medicine. - doi: 10.1002/mrm.26059. - - .. [3] Manjon JV, Coupe P, Concha L, Buades A, Collins DL (2013) - Diffusion Weighted Image Denoising Using Overcomplete Local - PCA. PLoS ONE 8(9): e73021. - https://doi.org/10.1371/journal.pone.0073021 + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -327,7 +312,9 @@ def run( out_denoised="dwi_mppca.nii.gz", out_sigma="dwi_sigma.nii.gz", ): - r"""Workflow wrapping Marcenko-Pastur PCA denoising method [1]_. + r"""Workflow wrapping Marcenko-Pastur PCA denoising method. + + See :footcite:p:`Veraart2016a` for further details about the method. Parameters ---------- @@ -346,7 +333,7 @@ def run( be more accurate. return_sigma : bool, optional If true, a noise standard deviation estimate based on the - Marcenko-Pastur distribution is returned [2]_. + Marcenko-Pastur distribution is returned :footcite:p:`Veraart2016b`. out_dir : string, optional Output directory. (default current directory) out_denoised : string, optional @@ -356,13 +343,7 @@ def run( References ---------- - .. [1] Veraart J, Novikov DS, Christiaens D, Ades-aron B, Sijbers, - Fieremans E, 2016. Denoising of Diffusion MRI using random matrix - theory. Neuroimage 142:394-406. doi: 10.1016/j.neuroimage.2016.08.016 - - .. [2] Veraart J, Fieremans E, Novikov DS. 2016. Diffusion MRI noise - mapping using random matrix theory. Magnetic Resonance in Medicine. - doi: 10.1002/mrm.26059. + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -403,7 +384,10 @@ def run( out_dir="", out_unring="dwi_unring.nii.gz", ): - r"""Workflow for applying Gibbs Ringing method [1]_, [2]_. + r"""Workflow for applying Gibbs Ringing method. + + See :footcite:p:`Kellner2016` and :footcite:p:`NetoHenriques2018` for + further details about the method. Parameters ---------- @@ -428,13 +412,7 @@ def run( References ---------- - .. [1] Neto Henriques, R., 2018. Advanced Methods for Diffusion MRI - Data Analysis and their Application to the Healthy Ageing Brain - (Doctoral thesis). https://doi.org/10.17863/CAM.29356 - - .. [2] Kellner E, Dhital B, Kiselev VG, Reisert M. Gibbs-ringing - artifact removal based on local subvoxel-shifts. Magn Reson Med. 2016 - doi: 10.1002/mrm.26054. + .. footbibliography:: """ io_it = self.get_io_iterator() diff --git a/dipy/workflows/nn.py b/dipy/workflows/nn.py index 66e3120889..2bd1a04c84 100644 --- a/dipy/workflows/nn.py +++ b/dipy/workflows/nn.py @@ -23,7 +23,9 @@ def run( out_mask="brain_mask.nii.gz", out_masked="dwi_masked.nii.gz", ): - """Extract brain using EVAC+ :footcite:p:`Park2024`. + """Extract brain using EVAC+. + + See :footcite:p:`Park2024` for further details about EVAC+. Parameters ---------- diff --git a/dipy/workflows/reconst.py b/dipy/workflows/reconst.py index ad912c8724..d036a83014 100644 --- a/dipy/workflows/reconst.py +++ b/dipy/workflows/reconst.py @@ -312,11 +312,11 @@ def run( out_gfa="gfa.nii.gz", ): """Workflow for tensor reconstruction and for computing DTI metrics - [1]_, [2]_. - using Weighted Least-Squares. - Performs a tensor reconstruction on the files by 'globing' - ``input_files`` and saves the DTI metrics in a directory specified by - ``out_dir``. + using Weighted Least-Squares. + + Performs a tensor reconstruction :footcite:p:`Basser1994b`, + :footcite:p:`Basser1996` on the files by 'globing' ``input_files`` and + saves the DTI metrics in a directory specified by ``out_dir``. Parameters ---------- @@ -334,19 +334,20 @@ def run( multiple masks at once. fit_method : string, optional can be one of the following: - 'WLS' for weighted least squares [4]_ - 'LS' or 'OLS' for ordinary least squares [4]_ + 'WLS' for weighted least squares :footcite:p:`Chung2006` + 'LS' or 'OLS' for ordinary least squares :footcite:p:`Chung2006` 'NLLS' for non-linear least-squares - 'RT' or 'restore' or 'RESTORE' for RESTORE robust tensor fitting [3]_. + 'RT' or 'restore' or 'RESTORE' for RESTORE robust tensor fitting + :footcite:p:`Chang2005`. b0_threshold : float, optional Threshold used to find b0 volumes. bvecs_tol : float, optional Threshold used to check that norm(bvec) = 1 +/- bvecs_tol sigma : float, optional - An estimate of the variance. [5]_ recommend to use - 1.5267 * std(background_noise), where background_noise is estimated - from some part of the image known to contain no signal (only noise) - b-vectors are unit vectors. + An estimate of the variance. :footcite:t:`Chang2005` recommend to + use 1.5267 * std(background_noise), where background_noise is + estimated from some part of the image known to contain no signal + (only noise) b-vectors are unit vectors. save_metrics : variable string, optional List of metrics to save. Possible values: fa, ga, rgb, md, ad, rd, mode, tensor, evec, eval @@ -410,20 +411,7 @@ def run( References ---------- - .. [1] Basser, P.J., Mattiello, J., LeBihan, D., 1994. Estimation of - the effective self-diffusion tensor from the NMR spin echo. J Magn - Reson B 103, 247-254. - - .. [2] Basser, P., Pierpaoli, C., 1996. Microstructural and - physiological features of tissues elucidated by quantitative - diffusion-tensor MRI. Journal of Magnetic Resonance 111, 209-219. - - .. [3] Chang, L-C, Jones D.K., Pierpaoli, C. 2005. RESTORE: Robust - estimation of tensors by outlier rejection. MRM 53: 1088-1095 - - .. [4] Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap - approaches for estimation of uncertainties of DTI parameters. - NeuroImage 33, 531-541. + .. footbibliography:: """ save_metrics = save_metrics or [] @@ -779,7 +767,9 @@ def run( out_peaks_indices="peaks_indices.nii.gz", out_gfa="gfa.nii.gz", ): - """Constrained spherical deconvolution [1]_. + """Constrained spherical deconvolution. + + See :footcite:p:`Tournier2007` for further details about the method. Parameters ---------- @@ -844,9 +834,7 @@ def run( References ---------- - .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of - the fibre orientation distribution in diffusion MRI: Non-negativity - constrained super-resolved spherical deconvolution. + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -995,7 +983,9 @@ def run( out_peaks_indices="peaks_indices.nii.gz", out_gfa="gfa.nii.gz", ): - """Constant Solid Angle [1]_. + """Constant Solid Angle. + + See :footcite:p:`Aganj2009` for further details about the method. Parameters ---------- @@ -1047,8 +1037,7 @@ def run( References ---------- - .. [1] Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging - with Solid Angle Consideration. + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -1172,9 +1161,11 @@ def run( out_gfa="gfa.nii.gz", ): """Workflow for Diffusion Kurtosis reconstruction and for computing - DKI metrics [1]_, [2]_. Performs a DKI reconstruction on the files by - 'globing' ``input_files`` and saves the DKI metrics in a directory - specified by ``out_dir``. + DKI metrics. + + Performs a DKI reconstruction :footcite:p:`Tabesh2011`, + :footcite:p:`Jensen2005` on the files by 'globing' ``input_files`` and + saves the DKI metrics in a directory specified by ``out_dir``. Parameters ---------- @@ -1197,9 +1188,10 @@ def run( b0_threshold : float, optional Threshold used to find b0 volumes. sigma : float, optional - An estimate of the variance. [3]_ recommend to use - 1.5267 * std(background_noise), where background_noise is estimated - from some part of the image known to contain no signal (only noise) + An estimate of the variance. :footcite:t:`Chang2005` recommend to + use 1.5267 * std(background_noise), where background_noise is + estimated from some part of the image known to contain no signal + (only noise) save_metrics : variable string, optional List of metrics to save. Possible values: fa, ga, rgb, md, ad, rd, mode, tensor, evec, eval @@ -1258,17 +1250,7 @@ def run( References ---------- - .. [1] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. - Estimation of tensors and tensor-derived measures in diffusional - kurtosis imaging. Magn Reson Med. 65(3), 823-836 - - .. [2] Jensen, Jens H., Joseph A. Helpern, Anita Ramani, Hanzhang Lu, - and Kyle Kaczynski. 2005. Diffusional Kurtosis Imaging: The - Quantification of Non-Gaussian Water Diffusion by Means of Magnetic - Resonance Imaging. MRM 53 (6):1432-40. - - .. [3] Chang, L-C, Jones, DK and Pierpaoli, C (2005). RESTORE: robust - estimation of tensors by outlier rejection. MRM, 53: 1088-95. + .. footbibliography:: """ save_metrics = save_metrics or [] @@ -1482,9 +1464,11 @@ def run( out_D="D.nii.gz", ): """Workflow for Intra-voxel Incoherent Motion reconstruction and for - computing IVIM metrics. Performs a IVIM reconstruction on the files - by 'globing' ``input_files`` and saves the IVIM metrics in a directory - specified by ``out_dir``. + computing IVIM metrics. + + Performs a IVIM reconstruction :footcite:p:`LeBihan1988`, + :footcite:p:`Stejskal1965` on the files by 'globing' ``input_files`` and + saves the IVIM metrics in a directory specified by ``out_dir``. Parameters ---------- @@ -1524,15 +1508,7 @@ def run( References ---------- - .. [Stejskal65] Stejskal, E. O.; Tanner, J. E. (1 January 1965). - "Spin Diffusion Measurements: Spin Echoes in the - Presence of a Time-Dependent Field Gradient". The - Journal of Chemical Physics 42 (1): 288. - Bibcode: 1965JChPh..42..288S. doi:10.1063/1.1695690. - - .. [LeBihan84] Le Bihan, Denis, et al. "Separation of diffusion - and perfusion in intravoxel incoherent motion MR - imaging." Radiology 168.2 (1988): 497-505. + .. footbibliography:: """ save_metrics = save_metrics or [] @@ -1647,10 +1623,11 @@ def run( out_gfa="gfa.nii.gz", ): """Reconstruct the fiber local orientations using the Robust and - Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) [1]_ model. The - fiber response function (FRF) is computed using the single-shell, + Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) model. + + The fiber response function (FRF) is computed using the single-shell, single-tissue model, and the voxel-wise fitting procedure is used for - RUMBA-SD. + RUMBA-SD :footcite:p:`CanalesRodriguez2015`. Parameters ---------- @@ -1751,14 +1728,7 @@ def run( References ---------- - .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., - Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., - Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., - Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R. - (2015). Spherical Deconvolution of Multichannel Diffusion MRI - Data with Non-Gaussian Noise Models and Spatial Regularization. - PLOS ONE, 10(10), e0138910. - https://doi.org/10.1371/journal.pone.0138910 + .. footbibliography:: """ io_it = self.get_io_iterator() diff --git a/dipy/workflows/segment.py b/dipy/workflows/segment.py index a0fba887cd..93c7b27bac 100644 --- a/dipy/workflows/segment.py +++ b/dipy/workflows/segment.py @@ -130,6 +130,9 @@ def run( ): """Recognize bundles + See :footcite:p:`Garyfallidis2018` and :footcite:p:`Chandio2020` for + further details about the method. + Parameters ---------- streamline_files : string @@ -181,15 +184,7 @@ def run( References ---------- - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. - - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., - Bullock, D., Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and - Garyfallidis, E. Bundle analytics, a computational framework for - investigating the shapes and profiles of brain pathways across - populations. Sci Rep 10, 17149 (2020) + .. footbibliography:: """ slr = not no_slr @@ -338,6 +333,8 @@ def run( ): """Extract bundles using existing indices (labels) + See :footcite:p:`Garyfallidis2018` for further details about the method. + Parameters ---------- streamline_files : string @@ -351,9 +348,7 @@ def run( References ---------- - .. [Garyfallidis17] Garyfallidis et al. Recognition of white matter - bundles using local and global streamline-based registration and - clustering, Neuroimage, 2017. + .. footbibliography:: """ logging.info("### Labels to Bundles ###") diff --git a/dipy/workflows/stats.py b/dipy/workflows/stats.py index e1bf94bc82..74d090a6bc 100755 --- a/dipy/workflows/stats.py +++ b/dipy/workflows/stats.py @@ -194,6 +194,8 @@ def buan_bundle_profiles( Applies statistical analysis on bundles and saves the results in a directory specified by ``out_dir``. + See :footcite:p:`Chandio2020` for further details about the method. + Parameters ---------- model_bundle_folder : string @@ -219,11 +221,7 @@ def buan_bundle_profiles( References ---------- - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., Bullock, D., - Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and Garyfallidis, E. - Bundle analytics, a computational framework for investigating the - shapes and profiles of brain pathways across populations. - Sci Rep 10, 17149 (2020) + .. footbibliography:: """ @@ -333,6 +331,8 @@ def run(self, model_bundle_folder, subject_folder, *, no_disks=100, out_dir=""): Applies statistical analysis on bundles of subjects and saves the results in a directory specified by ``out_dir``. + See :footcite:p:`Chandio2020` for further details about the method. + Parameters ---------- @@ -352,11 +352,7 @@ def run(self, model_bundle_folder, subject_folder, *, no_disks=100, out_dir=""): References ---------- - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., - Bullock, D., Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and - Garyfallidis, E. Bundle analytics, a computational framework for - investigating the shapes and profiles of brain pathways across - populations. Sci Rep 10, 17149 (2020) + .. footbibliography:: """ @@ -563,6 +559,8 @@ def run(self, subject_folder, *, clust_thr=(5, 3, 1.5), threshold=6, out_dir="") Applies bundle shape similarity analysis on bundles of subjects and saves the results in a directory specified by ``out_dir``. + See :footcite:p:`Chandio2020` for further details about the method. + Parameters ---------- @@ -581,11 +579,7 @@ def run(self, subject_folder, *, clust_thr=(5, 3, 1.5), threshold=6, out_dir="") References ---------- - .. [Chandio2020] Chandio, B.Q., Risacher, S.L., Pestilli, F., - Bullock, D., Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and - Garyfallidis, E. Bundle analytics, a computational framework for - investigating the shapes and profiles of brain pathways across - populations. Sci Rep 10, 17149 (2020) + .. footbibliography:: """ rng = np.random.default_rng() diff --git a/dipy/workflows/tracking.py b/dipy/workflows/tracking.py index 255f8eebbb..15d55d362c 100644 --- a/dipy/workflows/tracking.py +++ b/dipy/workflows/tracking.py @@ -155,6 +155,9 @@ def run( This workflow use a saved peaks and metrics (PAM) file as input. + See :footcite:p:`Garyfallidis2012b` and :footcite:p:`Amirbekian2016` + for further details about the method. + Parameters ---------- pam_files : string @@ -202,8 +205,7 @@ def run( References ---------- - Garyfallidis, University of Cambridge, PhD thesis 2012. - Amirbekian, University of California San Francisco, PhD thesis 2017. + .. footbibliography:: """ io_it = self.get_io_iterator() @@ -257,7 +259,9 @@ def run( ): """Workflow for Particle Filtering Tracking. - This workflow use a saved peaks and metrics (PAM) file as input. + This workflow uses a saved peaks and metrics (PAM) file as input. + + See :footcite:p:`Girard2014` for further details about the method. Parameters ---------- @@ -311,9 +315,7 @@ def run( References ---------- - Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards - quantitative connectivity analysis: reducing tractography biases. - NeuroImage, 98, 266-278, 2014. + .. footbibliography:: """ io_it = self.get_io_iterator() diff --git a/dipy/workflows/viz.py b/dipy/workflows/viz.py index de12675259..e2790980a7 100644 --- a/dipy/workflows/viz.py +++ b/dipy/workflows/viz.py @@ -54,7 +54,9 @@ def run( out_dir="", out_stealth_png="tmp.png", ): - """Interactive medical visualization - Invert the Horizon! [Horizon_ISMRM19]_. + """Interactive medical visualization - Invert the Horizon! + + See :footcite:p:`Garyfallidis2019` for further details about Horizon. Interact with any number of .trk, .tck or .dpy tractograms and anatomy files .nii or .nii.gz. Cluster streamlines on loading. @@ -125,11 +127,7 @@ def run( References ---------- - .. [Horizon_ISMRM19] Garyfallidis E., M-A. Cote, B.Q. Chandio, - S. Fadnavis, J. Guaje, R. Aggarwal, E. St-Onge, K.S. Juneja, - S. Koudoro, D. Reagan, DIPY Horizon: fast, modular, unified and - adaptive visualization, Proceedings of: International Society of - Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019. + .. footbibliography:: """ super(HorizonFlow, self).__init__(force=True) verbose = True diff --git a/doc/conf.py b/doc/conf.py index 9c37b80c7e..347197f6b3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,7 +40,7 @@ "sphinx.ext.todo", "sphinx.ext.ifconfig", "math_dollar", # has to go before numpydoc - # "numpydoc", + "numpydoc", "prepare_gallery", "sphinx_gallery.gen_gallery", "sphinxcontrib.bibtex",