diff --git a/data/sub-02_dwi.bval b/data/sub-02_dwi.bval index d2a6fae..1bab7ac 100644 --- a/data/sub-02_dwi.bval +++ b/data/sub-02_dwi.bval @@ -1 +1 @@ -0 0 0 3000 3000 2000 3000 1000 3000 3000 2000 3000 1000 3000 3000 500.001 3000 2000 3000 3000 999.999 3000 499.999 3000 3000 2000 3000 1000 3000 3000 2000 3000 1000 3000 3000 0 3000 2000 3000 1000 3000 3000 499.999 3000 2000 3000 3000 1000 3000 0 3000 3000 2000 3000 1000 3000 3000 2000 3000 1000 3000 3000 500 3000 2000 3000 3000 1000 3000 0 3000 2000 3000 3000 999.999 3000 500.001 3000 3000 2000 3000 1000 3000 3000 2000 3000 999.999 3000 3000 0 3000 2000 3000 3000 1000 3000 500.001 3000 3000 2000 3000 1000 3000 0 +5 5 610 1240 615 1225 625 1230 620 1230 610 1240 615 1225 620 1220 620 5 1225 615 1240 625 1230 620 1240 615 1225 615 1230 625 1230 610 1230 5 615 1235 615 1220 625 1245 620 1240 620 1225 615 1235 620 1225 605 5 1225 625 1235 615 1230 620 1230 610 1235 620 1230 620 1220 625 1235 5 610 1230 620 1240 615 1230 625 1230 610 1235 610 1240 620 1235 620 5 1220 615 1230 615 1230 620 1240 610 1215 620 1240 620 1225 620 1225 615 1230 5 890 1800 895 1785 910 1790 900 1795 890 1800 895 1785 905 1780 900 5 1785 895 1805 905 1795 900 1800 895 1780 895 1790 905 1790 890 1790 5 895 1795 895 1775 905 1805 900 1805 900 1785 895 1795 900 1785 885 5 1785 905 1795 895 1795 900 1790 890 1795 900 1790 900 1780 910 1795 5 890 1790 900 1805 895 1790 905 1790 890 1795 890 1800 905 1800 900 5 1780 895 1790 895 1790 900 1805 890 1775 900 1805 900 1785 900 1785 895 1790 diff --git a/data/sub-02_dwi.bvec b/data/sub-02_dwi.bvec index 98c7529..c5968be 100644 --- a/data/sub-02_dwi.bvec +++ b/data/sub-02_dwi.bvec @@ -1,3 +1,3 @@ -0 0 0 -0.654875 -0.271924 0.957387 0.11881 0.957387 0.326879 -0.394817 -0.190618 0.906253 -0.190617 0.56633 -0.55854 -0.0062266 0.648904 -0.325492 0.435216 -0.060085 0.325492 0.290295 -0.636679 0.008761 0.098843 0.0227962 -0.162887 -0.0227955 0.095045 -0.21496 -0.596978 0.741627 -0.596977 0.847852 0.943158 0 0.21565 0.416251 0.06036 0.41625 0.814723 -0.265965 -0.399916 -0.441982 -0.734448 0.566124 -0.716591 0.734448 -0.331272 0 -0.465735 -0.480716 0.581881 -0.961362 0.581881 -0.92036 0.393331 -0.928822 0.852276 0.928822 -0.571183 -0.535413 0.789559 0.442791 -0.86166 0.143848 0.89346 -0.86166 0.795825 0 0.399108 0.52577 0.806535 0.69138 -0.525769 0.973847 -0.88769 0.052107 0.696694 -0.0342733 0.626272 -0.0342738 0.994108 0.738939 -0.0845074 0.702182 -0.0845085 -0.505053 -0.37123 0 0.05087 -0.630413 0.170569 0.31216 -0.630413 -0.887018 0.152552 0.605767 -0.215791 -0.491239 0.210754 0.491239 0.787853 0 -0 0 0 0.355659 0.933965 0.187071 0.110437 0.18707 0.866547 0.108337 0.585245 0.349334 0.585244 0.470917 -0.665203 0.064446 -0.611989 -0.844583 0.497941 -0.972644 0.844583 0.619397 -0.653135 -0.548745 -0.63796 0.678409 0.917294 -0.678409 0.821836 -0.721063 0.258723 -0.039918 0.258722 -0.200363 0.304222 0 -0.732737 0.343103 -0.223624 0.343104 -0.56112 -0.335097 0.82842 -0.764517 0.292307 0.807614 -0.584614 -0.292308 -0.943028 0 0.168038 0.789299 0.362502 0.253123 0.362503 -0.003999 -0.915435 0.354407 -0.324551 -0.354407 0.799445 -0.167226 -0.38493 0.203222 -0.322776 0.431269 -0.41491 -0.322776 0.511407 0 -0.523871 -0.761172 0.590581 -0.710203 0.761173 -0.080055 -0.101313 -0.996034 0.03436 -0.991162 -0.2862 -0.991162 0.072683 -0.519516 -0.0561693 0.353175 -0.0561687 0.581614 0.77018 0 -0.85837 -0.756662 -0.325484 -0.422488 -0.756662 -0.152189 0.851204 0.776332 -0.937112 0.826626 0.013433 -0.826626 0.274495 0 -0 0 0 0.666817 0.231877 -0.220034 0.986756 -0.220034 0.377155 -0.91235 0.788133 -0.238058 0.788133 -0.676393 -0.495518 -0.997902 -0.452098 -0.425129 0.750095 -0.224396 0.425129 -0.729435 0.409944 0.835944 -0.7637 -0.734331 -0.363371 0.73433 -0.56174 -0.658681 -0.759395 -0.669624 -0.759395 0.49092 0.133799 0 0.645439 0.842031 0.972805 0.842031 -0.146185 0.903866 -0.392156 0.469218 0.612489 -0.165116 0.380425 -0.612489 -0.03094 0 0.868823 -0.381994 -0.728016 0.108216 -0.728016 0.391053 0.08526 -0.108098 -0.410233 0.108097 0.18611 0.82787 -0.477939 0.873291 -0.391608 0.890682 0.171983 -0.391608 0.32423 0 -0.752511 0.379714 -0.026762 0.132686 -0.379714 0.212633 -0.449158 0.072118 0.716545 0.128152 0.725171 0.128153 -0.080414 0.429037 0.994838 0.61823 0.994838 -0.637689 0.518664 0 -0.510502 0.173326 -0.930036 0.850917 0.173326 -0.435932 0.502174 0.174228 0.274326 0.274543 -0.977447 -0.274542 -0.551307 0 +0.531695 0.531695 -0.545977 0.483628 0.691191 -0.105459 -0.294575 -0.867939 -0.957356 0.14789 0.296586 -0.263343 -0.167652 -0.81816 0.568106 0.825166 -0.707535 0.531695 0.491263 -0.697671 0.247618 -0.297736 -0.778689 -0.942033 0.368183 -0.0645985 0.450837 -0.227713 0.988353 0.633661 0.611956 0.869951 -0.394799 0.531695 0.211295 -0.79625 -0.71349 0.0577723 -0.110309 -0.12057 -0.296779 -0.638925 -0.381349 -0.362386 -0.90571 -0.164736 -0.764349 0.881573 0.582101 0.531695 -0.511588 0.235808 -0.693941 0.173357 0.958996 0.766879 0.0119803 -0.409544 0.425315 0.982639 -0.73073 0.408617 -0.317282 0.0222084 0.561343 0.531695 -0.122333 0.658063 0.839668 -0.129015 -0.51021 -0.696646 0.536149 -0.163584 0.56363 0.902852 -0.724038 0.0750007 0.476689 0.68334 0.136501 0.531695 -0.186741 -0.903589 0.524559 -0.0124602 -0.977455 -0.802906 -0.315849 0.0979143 0.363383 -0.876238 0.453462 0.0771761 0.69704 -0.546704 0.946959 0.457953 -0.113123 0.531695 -0.544936 0.483667 0.690919 -0.105761 -0.295221 -0.868069 -0.957646 0.147654 0.296574 -0.263495 -0.167325 -0.818163 0.568269 0.824569 -0.707712 0.531695 0.491245 -0.696686 0.24725 -0.297772 -0.778943 -0.941885 0.368626 -0.0641064 0.450583 -0.228784 0.988407 0.633947 0.611876 0.86899 -0.394911 0.531695 0.211367 -0.796546 -0.713488 0.0576796 -0.110199 -0.120379 -0.296724 -0.639359 -0.381307 -0.362002 -0.904865 -0.164665 -0.765339 0.881319 0.581293 0.531695 -0.511303 0.235777 -0.694147 0.173465 0.959197 0.767218 0.0121282 -0.409605 0.425303 0.982425 -0.730638 0.408316 -0.317067 0.0218063 0.561006 0.531695 -0.123679 0.65794 0.840407 -0.129021 -0.509844 -0.696571 0.536687 -0.164075 0.563762 0.903298 -0.723724 0.0749389 0.476648 0.683608 0.135636 0.531695 -0.187123 -0.903731 0.524375 -0.0130766 -0.977257 -0.803017 -0.316274 0.0977579 0.363638 -0.876749 0.45367 0.0759775 0.697124 -0.547355 0.946716 0.457396 -0.113138 +0.58283 0.58283 0.121865 0.854567 -0.512577 0.288723 -0.941474 0.445659 -0.288893 -0.594316 0.26337 0.886353 -0.748207 -0.384613 -0.770115 0.0628862 -0.472155 0.58283 0.0442891 -0.447981 -0.942525 0.934804 0.482426 0.301846 0.799217 0.702844 0.462096 0.340428 0.150971 0.762401 -0.45612 -0.0786779 0.547192 0.58283 0.149505 -0.564176 0.433314 0.183068 0.955914 -0.989788 0.734683 0.769266 -0.706198 -0.489619 -0.0967702 -0.823982 0.63408 -0.0583448 -0.0405124 0.58283 0.079565 0.931015 -0.693473 -0.34494 -0.241181 0.622141 -0.723782 -0.423991 -0.75564 -0.111409 -0.402825 -0.652493 0.251743 -0.998248 -0.746255 0.58283 0.024262 0.290716 0.479636 -0.960859 0.424062 0.274791 -0.84412 -0.515091 0.350898 0.420225 -0.0727105 0.917063 0.736002 -0.653662 0.870117 0.58283 -0.221191 -0.243925 0.702476 -0.548266 0.126745 0.550065 0.946883 0.495776 0.149623 0.39115 0.878861 -0.89406 -0.164084 -0.788454 0.094938 -0.400783 0.532024 0.58283 0.121912 0.854112 -0.511209 0.287513 -0.940903 0.444569 -0.287904 -0.593459 0.262493 0.885784 -0.74656 -0.383118 -0.769135 0.0622394 -0.471158 0.58283 0.0438219 -0.446851 -0.942305 0.934524 0.481515 0.301062 0.798308 0.701373 0.461051 0.339449 0.150393 0.761973 -0.455249 -0.0768719 0.545989 0.58283 0.148737 -0.563409 0.431571 0.182186 0.955546 -0.989721 0.733506 0.768908 -0.704729 -0.488417 -0.0955991 -0.823485 0.632655 -0.057818 -0.040301 0.58283 0.0782924 0.930443 -0.69274 -0.344176 -0.239751 0.621009 -0.72284 -0.423305 -0.755001 -0.109278 -0.401929 -0.651377 0.250936 -0.998154 -0.745804 0.58283 0.0241904 0.28941 0.477565 -0.960595 0.421882 0.274129 -0.843759 -0.513902 0.349883 0.419104 -0.0723075 0.916624 0.734631 -0.652827 0.869069 0.58283 -0.220578 -0.240917 0.70134 -0.547476 0.125888 0.549227 0.946691 0.493615 0.148325 0.389783 0.878583 -0.893047 -0.162313 -0.7874 0.0941528 -0.399917 0.531251 +0.6145 0.6145 -0.82889 -0.189258 -0.509432 0.951587 0.163865 -0.219247 0.00330035 0.790517 -0.917972 0.380827 -0.641933 -0.427418 0.290135 -0.561379 0.525798 0.6145 0.869885 -0.559078 0.224348 0.193634 0.401135 -0.146504 0.475073 -0.708405 -0.763684 0.91228 -0.019154 0.131215 0.646115 -0.486822 0.738048 0.6145 0.965921 0.218384 -0.550611 -0.981401 -0.272139 -0.0760449 0.610052 0.00228013 0.596538 -0.793064 -0.412704 0.54214 0.117104 0.468428 -0.812106 0.6145 0.855539 0.278576 -0.193757 0.922477 -0.148859 -0.1576 -0.689925 -0.807778 0.498112 -0.148356 0.551149 0.638189 -0.914307 -0.0548447 -0.357767 0.6145 0.992193 0.694577 0.254768 0.245163 0.748236 0.662703 -0.00251417 0.841381 -0.747791 0.0909314 -0.685917 0.391625 0.480696 0.325226 -0.473566 0.6145 -0.957184 0.352176 -0.481005 -0.836211 -0.168868 -0.229719 0.060429 -0.862913 -0.919546 0.28144 0.148242 -0.441249 0.698005 0.281879 -0.30701 0.793506 0.839139 0.6145 -0.829567 -0.191203 -0.511171 0.951919 0.165973 -0.220939 0.00493084 0.791204 -0.918227 0.382044 -0.643934 -0.428754 0.292408 -0.562327 0.526454 0.6145 0.869918 -0.561206 0.225676 0.194926 0.401736 -0.149046 0.476255 -0.709906 -0.764465 0.912377 -0.0208293 0.13232 0.646804 -0.488822 0.738879 0.6145 0.966024 0.219285 -0.55198 -0.981571 -0.273475 -0.0772054 0.611493 0.000303432 0.598298 -0.79398 -0.414825 0.542916 0.11834 0.468971 -0.812696 0.6145 0.855827 0.28051 -0.195628 0.922742 -0.149867 -0.160387 -0.69091 -0.808107 0.499089 -0.151323 0.551925 0.63952 -0.914604 -0.0566807 -0.359235 0.6145 0.992027 0.695239 0.256218 0.246193 0.749717 0.663055 -0.00617345 0.842012 -0.748167 0.09167 -0.686291 0.392664 0.48283 0.326339 -0.475734 0.6145 -0.957251 0.353878 -0.482859 -0.83672 -0.170647 -0.231331 0.0612066 -0.864169 -0.919656 0.281746 0.149252 -0.443503 0.698335 0.283557 -0.308001 0.794264 0.839626 diff --git a/data/sub-02_dwi.nii.gz b/data/sub-02_dwi.nii.gz index b789634..50a2489 100644 Binary files a/data/sub-02_dwi.nii.gz and b/data/sub-02_dwi.nii.gz differ diff --git a/docs/_config.yml b/docs/_config.yml index d9bebce..1938ef3 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,8 +1,8 @@ # Book settings -title: "NiPreps" -author: Michael Joseph +title: "dMRIPrep" +author: The dMRIPrep developers copywright: 2020 -logo: images/logo.png +logo: images/logo.svg # Execution settings execute: diff --git a/docs/_toc.yml b/docs/_toc.yml index f2f26a1..6522554 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -2,6 +2,7 @@ # Learn more at https://jupyterbook.org/customize/toc.html # - file: welcome -- file: dwi/01-dmriprep -- file: dwi/02-intro_dmri -- file: dwi/03-issue_solution +- file: dmriprep/dmriprep +- file: dmriprep/gradient_table +- file: dmriprep/sdc +- file: dmriprep/hmc \ No newline at end of file diff --git a/docs/dmriprep/dmriprep.md b/docs/dmriprep/dmriprep.md new file mode 100644 index 0000000..dbe19d0 --- /dev/null +++ b/docs/dmriprep/dmriprep.md @@ -0,0 +1,153 @@ +# About dMRIPrep + +The pre-processing of dMRI involves numerous steps to reduce noise, remove artifacts, and standardize the data before fitting a particular model or carrying out tractography. + +Generally, researchers create ad-hoc pre-processing workflows for each dataset, building upon a large inventory of available tools. +The complexity of these workflows has snowballed with rapid advances in acquisition parameters and processing steps. + +dMRIPrep is an analysis-agnostic tool that addresses the challenge of robust and reproducible pre-processing for whole-brain dMRI data. + +## Motivation + +The development and fast adoption of fMRIPrep [^esteban2019] have revealed that neuroscientists need tools that simplify their research workflow, provide visual reports and checkpoints, and engender trust in the tool itself. + +In Botvinik et al., 2020 [^botvinik2020], 70 independent teams were tasked with analyzing the same fMRI dataset and testing 9 hypothesis. +The study demonstrated the huge amount of variability in analytic approaches as *no two teams* chose identical workflows. +One encouraging finding was that 48% of teams chose to pre-process the data using fMRIPrep. + +A similar predicament exists in the field of dMRI analysis. +There has been a lot of effort in recent years to compare the influence of various pre-processing steps on tractography and structural connectivity [^oldham2020] [^schilling2019] and harmonize different datasets [^tax2019]. +All of this points to a need for creating a standardized pipeline for pre-processing dMRI data that will reduce methodological variability and enable comparisons between different datasets and downstream analysis decisions. + +## Development + +In his 2019 ISMRM talk [^veraart2019], Jelle Veraart polled the developers of some of the major dMRI analysis software packages. +The goal was to understand how much consensus there was in the field on whether to proceed with certain pre-processing steps. +The poll showed that consensus is within reach. +However, different pre-processing steps have varying levels of support. +Head motion and eddy current correction, detecting outliers and denoising *must* be done. +Susceptibility distortion correction and removing Gibbs-ringing are also good to do but depend on the acquisition parameters. +Finally, for some steps such as correcting for B1 inhomogeneities or signal drift, their importance has not yet been demonstrated. + +```{figure} ../images/veraart-2019.png +:name: pre-processing_consensus + +Varying levels of support for different dMRI pre-processing steps +``` + +This information served as a starting point for the development of dMRIPrep. +It also introduced some new questions. +What are the minimal pre-processing steps for dMRI data? +How does the ordering in which the steps are conducted affect the final results? +How do different algorithms for the same method compare? + +Below is a figure of the proposed dMRI pre-processing steps dMRIPrep is working towards implementing. +The progress and more detailed discussion can be tracked at this [roadmap](https://nipreps.org/dmriprep/roadmap.html). + +```{figure} ../images/figure1.svg +:name: dmriprep_workflow + +Proposed dMRI pre-processing workflow +``` + +```{figure} ../images/contributors.png +:name: contributors +:width: 200px + +Current list of contributors to dMRIPrep +``` + +## Key Features + +There are several other dMRI pre-processing pipelines being developed. +Below are some of dMRIPrep's key features. + +### 1. Part of the NiPreps organization + +```{image} ../images/sashimi.jpg +:name: sashimi +:width: 200px +:align: right +``` + +NiPreps are a collection of tools that work as an extension of the scanner in that they minimally pre-process the data and make them "safe to consume" for analysis - kinda like *sashimi*! + +NiPreps pipelines are also: +- robust to different datasets +- easy to use (containerized software environment that can be run with single command) +- reproducible +- "glass box" architecture (all code/decisions visible on GitHub) +- regularly maintained + +```{figure} ../images/nipreps-chart.svg +:name: nipreps_chart + +Pipelines maintained by the NiPreps community +``` + +### 2. Automated workflows based on BIDS configuration + +dMRIPrep only imposes a single constraint on the input dataset - being compliant with BIDS (Brain Imaging Data Structure). +BIDS enables consistency in how neuroimaging data is structured and ensures that the necessary metadata is complete. +This also minimizes human intervention in running the pipeline as it is able to adapt to the unique features of the input data and make decisions about whether a particular processing step is appropriate or not. + +- head motion correction algorithm based on shell sampling + - FSL eddy or Sparse Fascicle Model (SFM) for single-shell + - 3D-SHORE for multi-shell/Cartesian grid +- distortion correction strategy based on input fieldmap +- parsing phase encoding direction and total readout time for applying distortion correction +- shell distribution - algorithms that require information redundancy cannot be applied to sparse sampling schemes + +### 3. Quality control reportlets + +```{figure} ../images/dwi_reportlet.gif +:name: reportlet +``` + +### 4. Continuous integration and deployment + +```{tabbed} unittest +Checks whether a function or class method behaves as expected. + +![unittest](../images/unittest.png) + +``` + +```{tabbed} doctest +Also checks whether code behaves as expected and serves as an example for how to use the code. + +![doctest1](../images/doctest1.png) + +![doctest2](../images/doctest2.png) + +``` + +```{tabbed} integration test +Checks the behaviour of a system (multiple pieces of code). +Can also be used to determine whether the system is behaving suboptimally. + +![integration_test](../images/integration_test.png) + +``` + +```{tabbed} build test +Checks that code or software environment can be compiled and deployed. + +![build_test](../images/build_test.png) + +``` + +--- +## References + +[^esteban2019]: Esteban, O., Markiewicz, C.J., Blair, R.W. et al. fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat Methods 16, 111–116 (2019). https://doi.org/10.1038/s41592-018-0235-4 + +[^botvinik2020]: Botvinik-Nezer, R., Holzmeister, F., Camerer, C.F. et al. Variability in the analysis of a single neuroimaging dataset by many teams. Nature 582, 84–88 (2020). https://doi.org/10.1038/s41586-020-2314-9 + +[^oldham2020]: Oldham, S., Arnatkevic̆iūtė, A., Smith, R.W., et al. The efficacy of different preprocessing steps in reducing motion-related confounds in diffusion MRI connectomics. NeuroImage 222 117252 (2020). https://doi.org/10.1016/j.neuroimage.2020.117252 + +[^schilling2019]: Schilling, K. G., Daducci, A., Maier-Hein, K., Poupon, C., Houde, J. C., Nath, V., Anderson, A. W., Landman, B. A., & Descoteaux, M. (2019). Challenges in diffusion MRI tractography - Lessons learned from international benchmark competitions. Magnetic resonance imaging, 57, 194–209. https://doi.org/10.1016/j.mri.2018.11.014 + +[^tax2019]: Tax, C. M., Grussu, F., Kaden, E., Ning, L., Rudrapatna, U., John Evans, C., St-Jean, S., Leemans, A., Koppers, S., Merhof, D., Ghosh, A., Tanno, R., Alexander, D. C., Zappalà, S., Charron, C., Kusmia, S., Linden, D. E., Jones, D. K., & Veraart, J. (2019). Cross-scanner and cross-protocol diffusion MRI data harmonisation: A benchmark database and evaluation of algorithms. NeuroImage, 195, 285–299. https://doi.org/10.1016/j.neuroimage.2019.01.077 + +[^veraart2019]: Image Processing: Possible Guidelines for Standardization & Clinical Applications. https://www.ismrm.org/19/program_files/MIS15.htm \ No newline at end of file diff --git a/docs/dmriprep/gradient_table.md b/docs/dmriprep/gradient_table.md new file mode 100644 index 0000000..3d56ebf --- /dev/null +++ b/docs/dmriprep/gradient_table.md @@ -0,0 +1,220 @@ +--- +jupytext: + formats: md:myst + text_representation: + extension: .md + format_name: myst +kernelspec: + display_name: Python 3 + language: python + name: python3 +--- + +# Introduction to dMRI Data + +```{code-cell} python +:tags: [hide-cell] + +import warnings +warnings.filterwarnings("ignore") +``` + +Diffusion imaging probes the random, microscopic motion of water protons by employing MRI sequences which are sensitive to the geometry and environmental organization surrounding the water protons. +This is a popular technique for studying the white matter of the brain. +The diffusion within biological structures, such as the brain, are often restricted due to barriers (eg. cell membranes), resulting in a preferred direction of diffusion (anisotropy). +A typical dMRI scan will acquire multiple volumes that are sensitive to a particular diffusion direction. + +## Diffusion Gradient Schemes + +In addition to the acquired diffusion images, two files are collected as part of the diffusion dataset. +These files correspond to the gradient amplitude (b-values) and directions (b-vectors) of the diffusion measurement and are named with the extensions `.bval` and `.bvec` respectively. + +```{code-cell} python +dwi = "../../data/sub-01_dwi.nii.gz" +bvec = "../../data/sub-01_dwi.bvec" +bval = "../../data/sub-01_dwi.bval" +``` + +The b-value is the diffusion-sensitizing factor, and reflects the timing & strength of the gradients (measured in s/mm2) used to acquire the diffusion-weighted images. + +```{code-cell} python +!cat ../../data/sub-01_dwi.bval +``` + +The b-vector corresponds to the direction of the diffusion sensitivity. Each row corresponds to a value in the x, y, or z axis. The numbers are combined column-wise to get an [x y z] coordinate per DWI volume. + +```{code-cell} python +!cat ../../data/sub-01_dwi.bvec +``` + +Together these two files define the dMRI measurement as a set of gradient directions and corresponding amplitudes. + +In the example data above, we see that 2 b-values were chosen for this scanning sequence. +The first few images were acquired with a b-value of 0 and are typically referred to as b=0 images. +In these images, no diffusion gradient is applied. +These images don't hold any diffusion information and are used as a reference (head motion correction) since they aren't subject to the same types of scanner artifacts that affect diffusion-weighted images. + +All of the remaining images have a b-value of 1000 and have a diffusion gradient associated with them. +Diffusion that exhibits directionality in the same direction as the gradient result in a loss of signal. +With further processing, the acquired images can provide measurements which are related to the microscopic changes and estimate white matter trajectories. + +```{code-cell} python +%matplotlib inline + +from nilearn import image +from nilearn.plotting import plot_epi + +selected_volumes = image.index_img(dwi, slice(3, 7)) + +for img in image.iter_img(selected_volumes): + plot_epi(img, display_mode="z", cut_coords=(30, 53, 75), cmap="gray") +``` + +After reading the `.bval` and `.bvec` files with the `read_bvals_bvecs()` function, we get both in a numpy array. Notice that the `.bvec` file has been transposed so that the x, y, and z-components are in column format. + +```{code-cell} python +from dipy.io import read_bvals_bvecs + +gt_bvals, gt_bvecs = read_bvals_bvecs(bval, bvec) +gt_bvecs +``` + +```{code-cell} python +import matplotlib.pyplot as plt + +fig = plt.figure() +ax = fig.add_subplot(111, projection="3d") +ax.scatter(gt_bvecs.T[0], gt_bvecs.T[1], gt_bvecs.T[2]) +plt.show() +``` + +It is important to note that in this format, the diffusion gradients are provided with respect to the image axes, not in real or scanner coordinates. Simply reformatting the image from sagittal to axial will effectively rotate the b-vectors, since this operation changes the image axes. Thus, a particular bvals/bvecs pair is only valid for the particular image that it corresponds to. + +## Diffusion Gradient Operations + +Because the diffusion gradient is critical for later analyzing the data, dMRIPrep performs several checks to ensure that the information is stored correctly. +### BIDS Validator + +At the beginning of the pipeline, the BIDS Validator is run. +This package ensures that the data is BIDS-compliant and also has several dMRI-specific checks summarized below: + +- all dMRI scans have a corresponding `.bvec` and `.bval` file +- the files aren't empty and formatted correctly + - single space delimited + - only contain numeric values + - correct number of rows and volume information + - volume information matches between image, `.bvec` and `.bval` files + +### DiffusionGradientTable + +In dMRIPrep, the `DiffusionGradientTable` class is used to read in the `.bvec` and `.bval` files, perform further sanity checks and make any corrections if needed. + +```{code-cell} python +from dmriprep.utils.vectors import DiffusionGradientTable + +dwi = "../../data/sub-02_dwi.nii.gz" +bvec = "../../data/sub-02_dwi.bvec" +bval = "../../data/sub-02_dwi.bval" + +gt_bvals, gt_bvecs = read_bvals_bvecs(bval, bvec) + +gtab = DiffusionGradientTable(dwi_file=dwi, bvecs=bvec, bvals=bval) +``` + +Below is a comparison of the `.bvec` and `.bval` files as read originally using `dipy` and after being corrected using `DiffusionGradientTable`. + +```{code-cell} python +gt_bvals +``` + +It looks like this data has 5 unique b-values: 0, 600, 900, 1200 and 1800. +However, the actual values that are reported look slightly different. + +```{code-cell} python +from collections import Counter +Counter(sorted(gt_bvals)) +``` + +dMRIPrep does a bit of rounding internally to cluster the b-values into shells. + +```{code-cell} python +gtab.bvals +``` + +```{code-cell} python +gt_bvecs[0:20] +``` + +It also replaces the b-vecs where a b-value of 0 is expected. + +```{code-cell} python +gtab.bvecs[0:20] +``` + +Inspired by MRtrix3 and proposed in the [BIDS spec](https://github.com/bids-standard/bids-specification/issues/349), dMRIPrep also creates an optional `.tsv` file where the diffusion gradients are reported in scanner coordinates as opposed to image coordinates. +The [x y z] values reported earlier are recalculated in [R A S]. + +```{code-cell} python +gtab.gradients[0:20] +``` + +Why is this important? + +Below is an example of how improperly encoded bvecs can affect tractography. +![incorrect_bvecs](../images/incorrect_bvecs.png) + +`MRtrix3` has actually created a handy tool called `dwigradcheck` to confirm whether the diffusion gradient table is oriented correctly. + +``` +$ dwigradcheck -fslgrad ../../data/sub-02_dwi.bvec ../../data/sub-02_dwi.bval ../../data/sub-02_dwi.nii.gz + +> Mean length Axis flipped Axis permutations Axis basis +52.41 none (0, 1, 2) image +51.68 none (0, 1, 2) scanner +32.70 1 (0, 1, 2) image +32.25 1 (0, 1, 2) scanner +31.23 0 (0, 2, 1) scanner +30.97 2 (0, 1, 2) scanner +30.82 0 (0, 2, 1) image +29.41 2 (0, 1, 2) image +29.31 none (0, 2, 1) image +28.61 none (1, 0, 2) image +28.57 2 (1, 0, 2) scanner +28.46 none (0, 2, 1) scanner +28.41 none (2, 1, 0) scanner +28.40 none (1, 0, 2) scanner +28.14 0 (0, 1, 2) scanner +28.04 none (2, 1, 0) image +27.92 1 (2, 1, 0) image +27.80 1 (2, 1, 0) scanner +27.71 2 (1, 0, 2) image +27.54 0 (0, 1, 2) image +23.43 1 (0, 2, 1) image +22.86 1 (0, 2, 1) scanner +21.55 2 (0, 2, 1) scanner +21.44 0 (1, 2, 0) scanner +21.35 2 (0, 2, 1) image +21.03 1 (1, 0, 2) image +20.88 0 (1, 0, 2) image +20.87 1 (1, 2, 0) image +20.80 0 (2, 0, 1) scanner +20.74 0 (1, 0, 2) scanner +20.41 2 (2, 0, 1) scanner +20.38 1 (1, 0, 2) scanner +20.25 0 (2, 1, 0) image +20.24 0 (1, 2, 0) image +20.21 1 (1, 2, 0) scanner +20.15 1 (2, 0, 1) image +20.13 2 (1, 2, 0) scanner +20.11 2 (2, 0, 1) image +20.04 1 (2, 0, 1) scanner +19.94 0 (2, 0, 1) image +19.87 none (2, 0, 1) scanner +19.86 none (2, 0, 1) image +19.83 2 (2, 1, 0) scanner +19.72 2 (1, 2, 0) image +19.59 none (1, 2, 0) image +19.49 0 (2, 1, 0) scanner +19.45 2 (2, 1, 0) image +19.43 none (1, 2, 0) scanner +``` \ No newline at end of file diff --git a/docs/dmriprep/hmc.md b/docs/dmriprep/hmc.md new file mode 100644 index 0000000..d8e4bc9 --- /dev/null +++ b/docs/dmriprep/hmc.md @@ -0,0 +1 @@ +# Head Motion Correction diff --git a/docs/dmriprep/sdc.md b/docs/dmriprep/sdc.md new file mode 100644 index 0000000..9521c8e --- /dev/null +++ b/docs/dmriprep/sdc.md @@ -0,0 +1 @@ +# Susceptibility Distortion Correction diff --git a/docs/dwi/01-dmriprep.ipynb b/docs/dwi/01-dmriprep.ipynb deleted file mode 100644 index 05771ba..0000000 --- a/docs/dwi/01-dmriprep.ipynb +++ /dev/null @@ -1,154 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# About dMRIPRep" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The development and fast adoption of fMRIPrep have revealed that neuroscientists need tools that simplify their research workflow, provide visual reports and checkpoints, and engender trust in the tool itself.\n", - "dMRIPrep extends fMRIPrep's approach and principles to diffusion MRI (dMRI).\n", - "The preprocessing of dMRI involves numerous steps to clean and standardize the data before fitting a particular model or carrying out tractography.\n", - "Generally, researchers create ad-hoc preprocessing workflows for each dataset, building upon a large inventory of available tools.\n", - "The complexity of these workflows has snowballed with rapid advances in acquisition and processing." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In his 2019 ISMRM talk on the state of consensus in diffusion MRI preprocessing, Jelle Veraart polled the developers of some major software packages. The results were pretty encouraging! It showed that there is a consensus on some preprocessing steps. Some steps require synchronization with the image acquisition parameters and some require further testing to prove their necessity.\n", - "\n", - "![preprocessing_consensus](../images/veraart-2019.png)\n", - "[Image Processing: Possible Guidelines for the Standardization & Clinical Applications](https://www.ismrm.org/19/program_files/MIS15.htm)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "*dMRIPrep* is part of the NiPreps organization\n", - "- robust: long-term goal is for it to be able to run on a diversity of datasets\n", - "- easy to use: BIDS App execution (` run /bids /output participant`)\n", - "- reproducible: QC reports, containerized, boilerplate languge\n", - "- \"glass box\" architecture: all code and decisions made on GitHub\n", - "- regular maintenance and upgrading of methods\n", - "![nipreps_chart](../images/nipreps-chart.svg)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This led us to create a roadmap for *dMRIPrep*'s development\n", - "![dmriprep_workflow](../images/figure1.svg)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Below is a list of contributors to the project so far!\n", - "![contributors](../images/contributors.png)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Project Structure\n", - "\n", - "The project can be found here: https://github.com/nipreps/dmriprep\n", - "\n", - "```\n", - "dmriprep\n", - "├── CHANGES.rst\n", - "├── Dockerfile\n", - "├── LICENSE\n", - "├── MANIFEST.in\n", - "├── Makefile\n", - "├── README.rst\n", - "├── dmriprep # contains all code\n", - "│ ├── __about__.py\n", - "│ ├── __init__.py\n", - "│ ├── _version.py\n", - "│ ├── cli/ # contains code for adjusting the command line arguments\n", - "│ ├── config\n", - "│ │ ├── __init__.py\n", - "│ │ ├── reports-spec.yml\n", - "│ │ └── testing.py\n", - "│ ├── conftest.py\n", - "│ ├── data/ # contains sample data that can be used to create function tests\n", - "│ ├── interfaces # contains Nipype interfaces that act as building blocks for individual tasks\n", - "│ │ ├── __init__.py\n", - "│ │ ├── images.py\n", - "│ │ ├── reports.py\n", - "│ │ └── vectors.py\n", - "│ ├── utils # contains functions called by interfaces\n", - "│ │ ├── __init__.py\n", - "│ │ ├── bids.py\n", - "│ │ ├── images.py\n", - "│ │ ├── misc.py\n", - "│ │ ├── tests/\n", - "│ │ └── vectors.py\n", - "│ └── workflows # contains workflows that are created by combining interfaces\n", - "│ ├── __init__.py\n", - "│ ├── base.py\n", - "│ ├── dwi\n", - "│ │ ├── __init__.py\n", - "│ │ ├── base.py\n", - "│ │ ├── outputs.py\n", - "│ │ └── util.py\n", - "│ └── fmap\n", - "│ ├── __init__.py\n", - "│ └── base.py\n", - "├── docs/ # contains code for building documentation\n", - "├── get_version.py\n", - "├── pyproject.toml\n", - "├── setup.cfg\n", - "├── setup.py\n", - "└── versioneer.py\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Resources\n", - "\n", - "- [BIDS Specification](https://bids-specification.readthedocs.io/en/stable/)\n", - "- [PyBIDS User Guide](https://bids-standard.github.io/pybids/user_guide.html)\n", - "- [Nipype Tutorials by Michael Notter](https://miykael.github.io/nipype_tutorial/)\n", - "- [NiBabel Tutorials](https://nipy.org/nibabel/tutorials.html#tutorials)\n", - "- [Contemporary Python Packaging by Chris Markiewicz](https://gist.github.com/effigies/9bbb424535d6a1d838d6325191c0a736)\n" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.7.7" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/dwi/02-intro_dmri.ipynb b/docs/dwi/02-intro_dmri.ipynb deleted file mode 100644 index d36656f..0000000 --- a/docs/dwi/02-intro_dmri.ipynb +++ /dev/null @@ -1,318 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Introduction to Diffusion MRI" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import warnings\n", - "warnings.filterwarnings(\"ignore\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Diffusion Weighted Imaging (DWI)\n", - "\n", - "Diffusion imaging probes the random, microscopic motion of water protons by employing MRI sequences which are sensitive to the geometry and environmental organization surrounding the water protons. This is a popular technique for studying the white matter of the brain. The diffusion within biological structures, such as the brain, are often restricted due to barriers (eg. cell membranes), resulting in a preferred direction of diffusion (anisotropy). A typical diffusion MRI scan will acquire multiple volumes that are sensitive to a particular diffusion direction and result in diffusion-weighted images (DWI). Diffusion that exhibits directionality in the same direction result in an attenuated signal. With further processing, the acquired images can provide measurements which are related to the microscopic changes and estimate white matter trajectories. Images with no diffusion weighting are also acquired as part of the acquisition protocol." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dwi = \"../../data/sub-01_dwi.nii.gz\"\n", - "bvec = \"../../data/sub-01_dwi.bvec\"\n", - "bval = \"../../data/sub-01_dwi.bval\"" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "%matplotlib inline\n", - "\n", - "from nilearn import image\n", - "from nilearn.plotting import plot_epi" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "selected_volumes = image.index_img(dwi, slice(0, 10))\n", - "\n", - "for img in image.iter_img(selected_volumes):\n", - " plot_epi(img, display_mode=\"z\", cut_coords=(30, 53, 75), cmap=\"gray\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Diffusion Gradient Scheme\n", - "\n", - "The diffusion-weighted gradient scheme is essential for pre-processing DWI data.\n", - "\n", - "In addition to the acquired diffusion images, two files are collected as part of the diffusion dataset. These files correspond to the gradient amplitude (b-values) and directions (b-vectors) of the diffusion measurement and are named with the extensions `.bval` and `.bvec` respectively. The b-value is the diffusion-sensitizing factor, and reflects the timing & strength of the gradients used to acquire the diffusion-weighted images. The b-vector corresponds to the direction of the diffusion sensitivity. Together these two files define the diffusion MRI measurement as a set of gradient directions and corresponding amplitudes." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### FSL format\n", - "\n", - "The bvals consists a single row of space-separated floating-point values with one value per volume in the DWI dataset. \n", - "The bvecs file consists of 3 rows of space-separated floating-point values. The first row corresponds to the x-component of the DW gradient vectors, one value per volume in the dataset; the second row corresponding to the y-component, and the third row to the z-component. A typical `.bval` and `.bvec` file are shown below:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "!cat ../../data/sub-01_dwi.bval" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "!cat ../../data/sub-01_dwi.bvec" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the example data above, we see that 2 b-values were chosen for this scanning sequence. The first few images were acquired with a b-value of 0 and are typically referred to as b=0 images. In these images, no DW gradient vector is applied either. These images don't hold any diffusion information and are used as a reference since they aren't subject to the same types of scanner artefacts that affect diffusion-weighted images. \n", - "\n", - "All of the remaining images have a b-value of 1000 and have a DW gradient vector associated with them. In these images, you can assess the diffusion of water in different directions based on the gradient vector that is applied." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from dipy.io.gradients import read_bvals_bvecs" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "After reading the `.bval` and `.bvec` files with the `read_bvals_bvecs()` function, we get both in a numpy array. Notice that the `.bvec` file has been transposed so that the x, y, and z-components are in column format." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gt_bvals, gt_bvecs = read_bvals_bvecs(bval, bvec)\n", - "\n", - "print(\"bvals:\\n\", gt_bvals, \"\\n\\nbvecs:\\n\", gt_bvecs)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "import matplotlib.pyplot as plt\n", - "\n", - "fig = plt.figure()\n", - "ax = fig.add_subplot(111, projection=\"3d\")\n", - "ax.scatter(gt_bvecs.T[0] * gt_bvals, gt_bvecs.T[1] * gt_bvals, gt_bvecs.T[2] * gt_bvals)\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### `.bval` and `.bvec` handling in `dMRIPRep`\n", - "\n", - "`dMRIPrep` includes a Python class called `DiffusionGradientTable` that does a lot of heavy lifting." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from dmriprep.utils.vectors import DiffusionGradientTable" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "?DiffusionGradientTable" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gtab = DiffusionGradientTable(dwi_file=dwi, bvecs=bvec, bvals=bval)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now, let's take a look at another dwi sequence. This one has multiple b-values." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dwi = \"../../data/sub-02_dwi.nii.gz\"\n", - "bvec = \"../../data/sub-02_dwi.bvec\"\n", - "bval = \"../../data/sub-02_dwi.bval\"" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gt_bvals, gt_bvecs = read_bvals_bvecs(bval, bvec)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "fig = plt.figure()\n", - "ax = fig.add_subplot(111, projection=\"3d\")\n", - "ax.scatter(gt_bvecs.T[0] * gt_bvals, gt_bvecs.T[1] * gt_bvals, gt_bvecs.T[2] * gt_bvals)\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The figure below shows an axial view of the brain under different b-values: 0, 1000, and 3000\n", - "\n", - "![bvalue](../images/bvalue.jpg) \n", - "http://mriquestions.com/what-is-the-b-value.html" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Diffusion Spectrum MRI (DSI)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from dipy.data import get_fnames" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "fraw, fbval, fbvec = get_fnames(\"taiwan_ntu_dsi\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gt_bvals, gt_bvecs = read_bvals_bvecs(fbval, fbvec)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "fig = plt.figure()\n", - "ax = fig.add_subplot(111, projection=\"3d\")\n", - "ax.scatter(gt_bvecs.T[0] * gt_bvals, gt_bvecs.T[1] * gt_bvals, gt_bvecs.T[2] * gt_bvals)\n", - "plt.show()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.7.7" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/dwi/03-issue_solution.ipynb b/docs/dwi/03-issue_solution.ipynb deleted file mode 100644 index cd503e4..0000000 --- a/docs/dwi/03-issue_solution.ipynb +++ /dev/null @@ -1,120 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Issue Solution: Determining the number of shells" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import warnings\n", - "warnings.filterwarnings(\"ignore\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from dmriprep.utils.vectors import DiffusionGradientTable\n", - "\n", - "import numpy as np" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "dwi = \"../../data/sub-02_dwi.nii.gz\"\n", - "bvec = \"../../data/sub-02_dwi.bvec\"\n", - "bval = \"../../data/sub-02_dwi.bval\"" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gtab = DiffusionGradientTable(dwi_file=dwi, bvecs=bvec, bvals=bval)\n", - "\n", - "gtab._bvals" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from dipy.core.gradients import unique_bvals" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "unique_bvals(gtab._bvals)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from collections import Counter" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "Counter(sorted(gtab._bvals))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "gtab.count_shells" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.7.7" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/images/build_test.png b/docs/images/build_test.png new file mode 100644 index 0000000..4e93acc Binary files /dev/null and b/docs/images/build_test.png differ diff --git a/docs/images/bvalue.jpg b/docs/images/bvalue.jpg deleted file mode 100644 index 977ae75..0000000 Binary files a/docs/images/bvalue.jpg and /dev/null differ diff --git a/docs/images/contributors.png b/docs/images/contributors.png index 40bc378..0bf125b 100644 Binary files a/docs/images/contributors.png and b/docs/images/contributors.png differ diff --git a/docs/images/contributors.svg b/docs/images/contributors.svg new file mode 100644 index 0000000..404b333 --- /dev/null +++ b/docs/images/contributors.svg @@ -0,0 +1,40216 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/doctest1.png b/docs/images/doctest1.png new file mode 100644 index 0000000..9537659 Binary files /dev/null and b/docs/images/doctest1.png differ diff --git a/docs/images/doctest2.png b/docs/images/doctest2.png new file mode 100644 index 0000000..57d98c1 Binary files /dev/null and b/docs/images/doctest2.png differ diff --git a/docs/images/dwi_reportlet.gif b/docs/images/dwi_reportlet.gif new file mode 100644 index 0000000..03f4ac5 Binary files /dev/null and b/docs/images/dwi_reportlet.gif differ diff --git a/docs/images/figure1.svg b/docs/images/figure1.svg index 7c3c766..0c0c5f4 100644 --- a/docs/images/figure1.svg +++ b/docs/images/figure1.svg @@ -1,24 +1,54 @@ + + + + + + + @@ -44,39 +74,9 @@ - - - - - - - - - @@ -214,7 +199,7 @@ inkscape:stockid="Arrow1Mend"> @@ -276,8 +261,8 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + id="base" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> @@ -471,16 +604,27 @@ + inkscape:label="Layer 1" + style="display:inline" + transform="translate(-53.656364,40.611259)"> + + + style="opacity:0.353086;fill:#dde9af;fill-opacity:1;stroke:#cdde87;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.952941" /> Calculate a non-weighted, average T2* map for Calculate a non-weighted, average T2* map each run, which will serve for reference in spatial for each run, which will serve for reference in spatial alignments of data. Head-motion & Eddy-currentsHead-motion & eddy-currents the head across diffusion orientations, as well as the distortions derived from Eddy currents. + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:0.95;font-family:Helvetica;-inkscape-font-specification:'Helvetica, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">the distortions derived from eddy currents. DenoisingEdge-preserving smoothing with a regularization Compensate for variance in dMRI signal due term accounting for Rician bias -TBD: nonlocal means and/or PCA + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:0.95;font-family:Helvetica;-inkscape-font-specification:'Helvetica, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">to thermal noise Estimate the parameters bringing the b=0 Necessary for the combination of multi-part DWI reference of each DWI chunk into alignment instances. Estimate the parameters bringing the b=0 with the rest of them. + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:0.95;font-family:Helvetica;-inkscape-font-specification:'Helvetica, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">reference of each DWI run into alignment with the rest of them. Convert fieldmap to displacementsConvert fieldmap to displacements and estimate distortion The distortion is proportional to the B0 nonuniformity map (or "fieldmap"), scaled by the nonuniformity map (or "fieldmap"), scaled by sequence's readout time. + y="39.26685">the sequence's readout time. One-shot resamplingapplicable. - - - Preprocessed fieldmaps -Output of SDCFlows. Preprocessed anatomical imagingAnatomical preprocessing Output of sMRIPrep (T1w, Output of sMRIPrep (T1w, reconstructed reconstructed surfaces, spatial surfaces, spatial normalization transforms, normalization transforms, etc.) + y="37.714627">etc.) Set of DWI runsDWI run and strength information. - Set of preprocessed DWI runsSet of preprocessed DWI runs Data ready for analysis, following the same multi-part structure of the inputs, and consistent gradient orientation and strength information. - - - - - Data ready for analysis, following Spatial transforms -the same multi-part structure of Necessary for the combination the inputs, and consistent of multipart DWI instances and gradient orientation and strength more sophisticated analyses. - - - + y="44.303254">information. Including: fitted signal drift, estimated rician bias, head-motion (6p), Including: fitted signal drift, head-motion (6p), noise variance estimation, framewise displacement. + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:0.95;font-family:Helvetica;-inkscape-font-specification:'Helvetica, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">noise variance estimation, framewise displacement. + Diffusion preprocessing + + + Fieldmap preprocessing +Output of SDCFlows (Estimate fieldmap and calculate B-spline coefficients). + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/incorrect_bvecs.png b/docs/images/incorrect_bvecs.png new file mode 100644 index 0000000..fde9de1 Binary files /dev/null and b/docs/images/incorrect_bvecs.png differ diff --git a/docs/images/integration_test.png b/docs/images/integration_test.png new file mode 100644 index 0000000..ade70b6 Binary files /dev/null and b/docs/images/integration_test.png differ diff --git a/docs/images/logo.png b/docs/images/logo.png deleted file mode 100644 index 06d56f4..0000000 Binary files a/docs/images/logo.png and /dev/null differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..7bc327e --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,1680 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + +   + Image processing methods for human brain connectivity analysis from in-vivo diffusion MRI + Óscar Esteban Sanz-Dranguet + + + + + + + + diff --git a/docs/images/nipreps-chart.svg b/docs/images/nipreps-chart.svg index 5eb8a99..77b9e6f 100644 --- a/docs/images/nipreps-chart.svg +++ b/docs/images/nipreps-chart.svg @@ -13,7 +13,7 @@ viewBox="0 0 483.50942 379.35749" version="1.1" id="svg21114" - inkscape:version="1.0 (4035a4f, 2020-05-01)" + inkscape:version="1.0.1 (c497b03c, 2020-09-10)" sodipodi:docname="nipreps-chart.svg" inkscape:export-filename="/Volumes/GoogleDrive/My Drive/NiPreps/art/nipreps-chart.png" inkscape:export-xdpi="300.02673" @@ -1673,7 +1673,7 @@ inkscape:cx="1192.5197" inkscape:cy="590.40092" inkscape:document-units="mm" - inkscape:current-layer="layer1" + inkscape:current-layer="g15822" inkscape:document-rotation="0" showgrid="false" units="in" @@ -1694,7 +1694,7 @@ image/svg+xml - + @@ -6118,22 +6118,6 @@ x="33.724834" y="65.158661" /> - Projects maintained by theNiPreps community diff --git a/docs/images/sashimi.jpg b/docs/images/sashimi.jpg new file mode 100644 index 0000000..6e6bc3d Binary files /dev/null and b/docs/images/sashimi.jpg differ diff --git a/docs/images/unittest.png b/docs/images/unittest.png new file mode 100644 index 0000000..e2b93c8 Binary files /dev/null and b/docs/images/unittest.png differ diff --git a/docs/images/veraart-2019.png b/docs/images/veraart-2019.png index 9f0ea15..071160c 100644 Binary files a/docs/images/veraart-2019.png and b/docs/images/veraart-2019.png differ diff --git a/docs/welcome.md b/docs/welcome.md index f118702..04cb56b 100644 --- a/docs/welcome.md +++ b/docs/welcome.md @@ -1,36 +1,18 @@ -Contributing to an Open Source Project: An Example with dMRIPrep -================================================================ +# dMRIPrep: a robust pre-processing pipeline for diffusion MRI -Overview --------- - -dMRIPrep is an analysis-agnostic tool that addresses the challenge of robust and reproducible preprocessing for whole-brain dMRI data. - -In this tutorial we will demonstrate how to engage as a new contributor to dMRIPrep with the implementation of a longstanding request for a [new feature in the software](https://github.com/nipreps/dmriprep/issues/64). -We will describe the overall process of contributing to an open-source project step-by-step, particularizing steps to the neuroimaging field whenever possible. - -Workshop Contents ------------------ - -| # | Episode | Time | -|--:|:---------|:-----| -| 1 | About dMRIPrep | 5 | -| 2 | Intro to dMRI | 10 | -| 3 | Contributing to an Open Source Project | 10 | -| 4 | Review GitHub Issue | 5 | -| 5 | Coding Solution | 20 | -| 6 | Pushing changes to GitHub | 10 | -| 7 | Open Issues | 5 | - -Setup ------ +## Setup This tutorial contains a mix of lecture-based and interactive components. You are welcome to follow along however you like, whether you just want to listen or code along with us. Each of the chapters involving code are actually IPython notebooks! -Clicking the Binder icon in the top right corner will launch an interactive Jupyter Lab environment with all of the necessary software packages pre-installed. -![binder_link](images/binder_link.png) +Clicking the Binder icon in the top right corner will launch an interactive computing environment with all of the necessary software packages pre-installed. + +```{figure} images/binder_link.png +:name: binder_link + +Binder Link +``` If you would like to follow along using your own setup, you can: 1. clone this repository diff --git a/requirements.txt b/requirements.txt index 6299169..41259ab 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,5 @@ -dmriprep==0.3.0 +dmriprep +flake8 ghp-import jupyter-book jupytext