diff --git a/docs/_config.yml b/docs/_config.yml
index 1938ef3..b034d32 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -1,8 +1,12 @@
# Book settings
-title: "dMRIPrep"
-author: The dMRIPrep developers
+title: "NiPreps"
+author: The NiPreps developers
copywright: 2020
-logo: images/logo.svg
+
+# Sphinx customizations
+sphinx:
+ extra_extensions:
+ - sphinx_exercise
# Execution settings
execute:
diff --git a/docs/_toc.yml b/docs/_toc.yml
index 6522554..359db79 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -1,8 +1,13 @@
# Table of content
# Learn more at https://jupyterbook.org/customize/toc.html
-#
+
- file: welcome
-- file: dmriprep/dmriprep
-- file: dmriprep/gradient_table
-- file: dmriprep/sdc
-- file: dmriprep/hmc
\ No newline at end of file
+- part: nipreps
+ chapters:
+ - file: nipreps/nipreps
+ - file: nipreps/community_development
+- part: dmriprep
+ chapters:
+ - file: dmriprep/dmriprep
+ - file: dmriprep/gradient_table
+ - file: dmriprep/hmc
\ No newline at end of file
diff --git a/docs/dmriprep/dmriprep.md b/docs/dmriprep/dmriprep.md
index dbe19d0..3b0beef 100644
--- a/docs/dmriprep/dmriprep.md
+++ b/docs/dmriprep/dmriprep.md
@@ -1,24 +1,9 @@
# 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.
+The pre-processing of dMRI data involves numerous steps to reduce noise, remove artifacts, and standardize the data before fitting a particular model or carrying out tractography.
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.
@@ -57,97 +42,8 @@ Proposed dMRI pre-processing workflow
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.
-
-
-
-```
-
-```{tabbed} doctest
-Also checks whether code behaves as expected and serves as an example for how to use the code.
-
-
-
-
-
-```
-
-```{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.
-
-
-
-```
-
-```{tabbed} build test
-Checks that code or software environment can be compiled and deployed.
-
-
-
-```
-
---
-## 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
+## References
-[^veraart2019]: Image Processing: Possible Guidelines for Standardization & Clinical Applications. https://www.ismrm.org/19/program_files/MIS15.htm
\ No newline at end of file
+[^veraart2019]: Image Processing: Possible Guidelines for Standardization & Clinical Applications. https://www.ismrm.org/19/program_files/MIS15.htm
diff --git a/docs/dmriprep/gradient_table.md b/docs/dmriprep/gradient_table.md
index 3d56ebf..fb2ee1d 100644
--- a/docs/dmriprep/gradient_table.md
+++ b/docs/dmriprep/gradient_table.md
@@ -217,4 +217,4 @@ $ dwigradcheck -fslgrad ../../data/sub-02_dwi.bvec ../../data/sub-02_dwi.bval ..
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/sdc.md b/docs/dmriprep/sdc.md
deleted file mode 100644
index 9521c8e..0000000
--- a/docs/dmriprep/sdc.md
+++ /dev/null
@@ -1 +0,0 @@
-# Susceptibility Distortion Correction
diff --git a/docs/images/contributors.svg b/docs/images/contributors.svg
deleted file mode 100644
index 404b333..0000000
--- a/docs/images/contributors.svg
+++ /dev/null
@@ -1,40216 +0,0 @@
-
-
diff --git a/docs/images/logo.svg b/docs/images/logo.svg
deleted file mode 100644
index 7bc327e..0000000
--- a/docs/images/logo.svg
+++ /dev/null
@@ -1,1680 +0,0 @@
-
-
diff --git a/docs/images/project_structure.png b/docs/images/project_structure.png
new file mode 100644
index 0000000..2f67d39
Binary files /dev/null and b/docs/images/project_structure.png differ
diff --git a/docs/nipreps/community_development.md b/docs/nipreps/community_development.md
new file mode 100644
index 0000000..e5049ec
--- /dev/null
+++ b/docs/nipreps/community_development.md
@@ -0,0 +1,108 @@
+# Community Development
+
+```{admonition} Overview
+**Objectives**
+- Discover how "open source" projects are organized (*NiPreps* in particular)
+- Describe what a contribution is
+- Learn where to get help before making a contribution
+```
+
+All *NiPreps* are open to community feedback and contributions.
+Contributing to seemingly big projects can feel scary at first. This lesson will help orient you to how an example *NiPreps* project is organized and how to begin making a contribution.
+
+## Getting started with GitHub
+
+For this example, let's take a look at the *dMRIPrep* repository found [here](https://github.com/nipreps/dmriprep).
+
+```{figure} ../images/project_structure.png
+:name: project_structure
+```
+
+The `README` is rendered on the main page of the project.
+If a project were a home, the `README` would be the door mat.
+It describes what the project does, who it is for, how to get started, and where to find key resources.
+
+Below is a more detailed breakdown of the project as well as a brief description of any areas of importance.
+
+```
+dmriprep
+├── CHANGES.rst
+├── CONTRIBUTING.md
+├── Dockerfile
+├── LICENSE
+├── MANIFEST.in
+├── Makefile
+├── README.rst
+├── dmriprep # contains all code
+│ ├── cli/ # contains code for adjusting the command line arguments
+│ ├── config/ # contains configuration files
+│ ├── data/ # contains sample data that can be used for testing code
+│ ├── interfaces/ # contains Nipype interfaces that act as building blocks for individual tasks
+│ ├── utils/ # contains functions called by NiPype interfaces
+│ └── workflows # contains NiPype workflows that are created by combining interfaces
+│ ├── base.py
+│ ├── dwi/
+│ └── fmap/
+├── docs/ # contains code for building documentation
+├── get_version.py
+├── pyproject.toml
+├── setup.cfg
+├── setup.py
+└── versioneer.py
+```
+
+## Checking the contributing guidelines
+
+Before contributing to an open-source initiative, your first move *should* be checking how the project is seeking external feedback.
+Typically, that is stated in a `CONTRIBUTING.md` file located in the project's root or `docs` folder.
+
+All *NiPreps* projects share a common set of [contributing guidelines](https://nipreps.org/community/).
+
+```{figure} ../images/contrib_guidelines.png
+:name: contributing_guidelines
+```
+
+## Preparing a proposal for a new feature, documentation, or a bug fix
+
+Impromptu contributions are typically difficult to absorb by projects involving several developers and/or with many users.
+For this reason, its best to first browse through the project's [home page](https://github.com/nipreps/dmriprep).
+
+There are two locations where you'll find details about ongoing and future work.
+The [existing and past pull requests tab](https://github.com/nipreps/dmriprep/pulls) will give you an idea of what new features/bug fixes are currently in progress, and you can also check the requirements to get a pull request accepted by looking at closed (and "merged") pull requests.
+
+Next to that tab, you'll find [the issue tracker tab](https://github.com/nipreps/dmriprep/issues/).
+There, you should check that the feature you have in mind is not already in the works.
+Opening a new issue, requesting feedback, and gauging interest are generally very welcome.
+
+Head to [the new features page](https://nipreps.org/community/features/) to learn more about the process of proposing a new feature.
+
+## Making a change
+
+Make sure your git credentials are configured.
+
+```
+git config --global user.name "Carl Jacobi"
+git config --global user.email "carl.jacobi@gmail.com"
+```
+
+Fork the project of interest and clone your forked repository to your computer.
+
+```
+git clone https://github.com/carljacobi/dmriprep.git
+```
+
+To keep up with changes, add the "upstream" repository as a remote to your locally cloned repository.
+
+```
+cd dmriprep
+
+git remote add upstream https://github.com/nipreps/dmriprep.git
+```
+
+Keep your fork up to date with the upstream repository.
+
+```{code-cell} bash
+git fetch upstream
+git checkout master
+git merge upstream/master
+``
diff --git a/docs/nipreps/nipreps.md b/docs/nipreps/nipreps.md
new file mode 100644
index 0000000..d70fea9
--- /dev/null
+++ b/docs/nipreps/nipreps.md
@@ -0,0 +1,166 @@
+# NeuroImaging PREProcessing toolS (NiPreps)
+
+Pre-processing MRI data is a necessary task before doing any kind of data analysis.
+
+Different kinds of artifacts can occur during a scan due to:
+
+- the subject
+ - head motion
+ - breathing, heart beating, blood vessels
+ - metal items
+- scanner hardware limitations
+ - distortions due to B0 and B1 inhomogeneities
+ - eddy currents
+ - signal drift
+- signal processing
+ - Gibbs ringing
+
+These physiological and acquisition artifacts can confound the interpretation of our analysis results.
+Thus, pre-processing is necessary to minimize their influence.
+
+Pre-processing can also help prepare the data for analysis in other ways. Some examples include:
+
+- image registration between acquisitions (e.g., sessions, runs, modalities, etc.)
+- image registration to normalized spaces
+- identifying spurious sources of signal
+- automated segmentation (eg. brain masking, tissue classification)
+
+## The problem of methodological variability
+
+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.
+
+In Botvinik et al., 2020 [^botvinik2020], 70 independent teams were tasked with analyzing the same fMRI dataset and testing 9 hypotheses.
+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 [^esteban2019], a standardized pipeline for fMRI data.
+
+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].
+
+Differences in methods or parameters chosen [^carp2012] [^bowring2019], implementations across software [^dickie2017], and even operating system or software version [^gronenschild2012] [^glatard2015] all contribute to variability.
+
+Doing reproducible neuroimaging research is hard.
+All of this points to a need for creating standardized pipelines for pre-processing MRI data that will reduce methodological variability and enable comparisons between different datasets and downstream analysis decisions.
+
+## Augmenting the scanner to produce "analysis grade" data
+
+```{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*!
+
+Below is a depiction of the projects currently maintained by the NiPreps community.
+These tools arose out of the need to extend *fMRIPrep* to new imaging modalities and populations.
+
+They can be organized into 3 layers:
+
+- Software infrastructure: deliver low-level interfaces and utilities
+- Middleware: contains functions that generalize across the end-user tools
+- End-user tools: perform pre-processing or quality control
+
+```{figure} ../images/nipreps-chart.svg
+:name: nipreps_chart
+
+```
+
+## NiPreps driving principles
+
+*NiPreps* are driven by 3 main principles, which are summarized below.
+These principles distill some design and organizational foundations.
+
+### 1. Robust
+
+*NiPreps* are meant to be robust to different datasets and attempt to provide the best possible results independent of scanner manufacturer, acquisition parameters, or the presence of additional correction scans (such as field maps).
+The end-user tools only impose a single constraint on the input dataset - being compliant with BIDS (Brain Imaging Data Structure) [^gorgolewski2016].
+BIDS enables consistency in how neuroimaging data is structured and ensures that the necessary metadata is complete.
+This minimizes human intervention in running the pipelines as they are able to adapt to the unique features of the input data and make decisions about whether a particular processing step is appropriate or not.
+
+The scope of these tools is strictly limited to pre-processing tasks.
+This eases the burden of maintaining these tools but also helps focus on standardizing each processing step and reducing the amount of methodological variability.
+*NiPreps* only support BIDS-Derivatives as output and so are agnostic to subsequent analysis.
+
+*NiPreps* also aim to be robust in their codebase.
+The pipelines are modular and rely on widely-used tools such as AFNI, ANTs, FreeSurfer, FSL, NiLearn, or DIPY and are extensible via plug-ins.
+This modularity in the code allows each step to be thoroughly tested. Some examples of tests performed on different parts of the pipeline are shown below:
+
+```{tabbed} unittest
+Checks whether a function or class method behaves as expected.
+
+
+
+```
+
+```{tabbed} doctest
+Also checks whether code behaves as expected and serves as an example for how to use the code.
+
+
+
+
+
+```
+
+```{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.
+
+
+
+```
+
+```{tabbed} build test
+Checks that code or software environment can be compiled and deployed.
+
+
+
+```
+
+### 2. Easy to use
+
+*NiPreps* are packaged as a fully-compliant BIDS-Apps [^gorgolewski2017].
+All of the software is containerized and the pipelines all share a common command-line interface:
+` [--options]`
+
+Thanks to limiting the input dataset to BIDS, manual parameter input is reduced to a minimum, allowing the pipelines to run in an automated fashion.
+
+### 3. "Glass box" philosophy
+
+*NiPreps* are thoroughly and transparently documented (including the generation of individual subject-level visual reports with a consistent format that serve as scaffolds for understanding the quality of each pre-processing step and any design decisions). Below is an example report:
+
+```{figure} ../images/dwi_reportlet.gif
+:name: reportlet
+
+```
+
+*NiPreps* are also community-driven.
+The success of these tools has largely been driven by their strong uptake in the neuroimaging community.
+This has allowed them to be exercised on diverse datasets and has brought the interest of a variety of domain experts to contribute their knowledge towards improving the tools.
+The tools are "open source" and all of the code and ideas are visible on GitHub.
+
+---
+
+[^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
+
+[^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
+
+[^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
+
+[^carp2012]: Carp J. On the plurality of (methodological) worlds: estimating the analytic flexibility of FMRI experiments. Front Neurosci. 2012 Oct 11;6:149. doi: 10.3389/fnins.2012.00149.
+
+[^bowring2019]: Bowring, A, Maumet, C, Nichols, TE. Exploring the impact of analysis software on task fMRI results. Hum Brain Mapp. 2019; 40: 3362– 3384. https://doi.org/10.1002/hbm.24603
+
+[^edickie2017]: Dickie E, Hodge S, Craddock R, Poline J, Kennedy D (2017) Tools Matter: Comparison of Two Surface Analysis Tools Applied to the ABIDE Dataset. Research Ideas and Outcomes 3: e13726. https://doi.org/10.3897/rio.3.e13726
+
+[^gronenschild2012]: Gronenschild EH, Habets P, Jacobs HI, Mengelers R, Rozendaal N, van Os J, Marcelis M. The effects of FreeSurfer version, workstation type, and Macintosh operating system version on anatomical volume and cortical thickness measurements. PLoS One. 2012;7(6):e38234. doi: 10.1371/journal.pone.0038234
+
+[^glatard2015]: Glatard T, Lewis LB, Ferreira da Silva R, Adalat R, Beck N, Lepage C, Rioux P, Rousseau M-E, Sherif T, Deelman E, Khalili-Mahani N and Evans AC (2015) Reproducibility of neuroimaging analyses across operating systems. Front. Neuroinform. 9:12. doi: 10.3389/fninf.2015.00012
+
+[^gorgolewski2016]: Gorgolewski, K., Auer, T., Calhoun, V. et al. The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments. Sci Data 3, 160044 (2016). https://doi.org/10.1038/sdata.2016.44
+
+[^gorgolewski2017]: Gorgolewski KJ, Alfaro-Almagro F, Auer T, Bellec P, Capotă M, Chakravarty MM, Churchill NW, Cohen AL, Craddock RC, Devenyi GA, Eklund A, Esteban O, Flandin G, Ghosh SS, Guntupalli JS, Jenkinson M, Keshavan A, Kiar G, Liem F, Raamana PR, Raffelt D, Steele CJ, Quirion PO, Smith RE, Strother SC, Varoquaux G, Wang Y, Yarkoni T, Poldrack RA. BIDS apps: Improving ease of use, accessibility, and reproducibility of neuroimaging data analysis methods. PLoS Comput Biol. 2017 Mar 9;13(3):e1005209. doi: 10.1371/journal.pcbi.1005209
diff --git a/docs/welcome.md b/docs/welcome.md
index 04cb56b..b36ed4c 100644
--- a/docs/welcome.md
+++ b/docs/welcome.md
@@ -1,4 +1,4 @@
-# dMRIPrep: a robust pre-processing pipeline for diffusion MRI
+# NiPreps
## Setup
diff --git a/requirements.txt b/requirements.txt
index 41259ab..8cbda30 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,6 +1,6 @@
+dipy
dmriprep
-flake8
ghp-import
jupyter-book
jupytext
-nbdime
\ No newline at end of file
+sphinx-exercise
\ No newline at end of file