enh: restructure docs

Author: oesteban

docs/apps/framework.md

@@ -111,10 +111,10 @@ derivatives/
 │ │ │ └── sub-01_from-orig_to-T1w_mode-image_xfm.txt
 │ │ ├── figures/
 │ │ └── func/
-│ │ ├── sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz
-│ │ ├── sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz
-│ │ ├── sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz
-│ │ └── sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz
+│ │   ├── sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz
+│ │   ├── sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz
+│ │   ├── sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz
+│ │   └── sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz
 │ ├── sub-02.html
 │ ├── sub-02/
 │ ├── sub-03.html

docs/devs/guidelines.md

@@ -48,7 +48,7 @@ We're excited you're here and want to contribute.
 These principles distill some design and organizational foundations:
 
   1. *NiPreps* only and fully support BIDS and BIDS-Derivatives for the input and output data.
-  1. *NiPreps* are packaged as a fully-compliant BIDS-Apps [6], not just in its user interface, but also in the continuous integration, testing, and delivery.
+  1. *NiPreps* are packaged as a fully-compliant [BIDS-Apps](../apps/framework.md), not just in its user interface, but also in the continuous integration, testing, and delivery.
   1. The scope of *NiPreps* is strictly limited to preprocessing tasks.
   1. *NiPreps* are agnostic to subsequent analysis, i.e., any software supporting BIDS-Derivatives for its inputs should be amenable to analyze data preprocessed with them.
   1. *NiPreps* are thoroughly and transparently documented (including the generation of individual, visual reports with a consistent format that serve as scaffolds for understanding the underpinnings and design decisions).

docs/index.md

@@ -1,36 +1,8 @@
-The current neuroimaging workflow has matured into a large chain of processing and analysis steps involving a large number of experts, across imaging modalities and applications.
-The development and fast adoption of [*fMRIPrep*][1] have revealed that neuroscientists need tools that simplify their research workflow, provide visual reports and checkpoints, and engender trust in the tool itself.
-The *NiPreps (NeuroImaging Preprocessing toolS)* framework extends *fMRIPrep*'s approach and principles to new imaging modalities.
-The vision for *NiPreps* is to provide end-users (i.e., researchers) with applications that allow them to perform quality control smoothly and to prepare their data for modeling and statistical analysis.
+# NeuroImaging PREProcessing toolS (NiPreps)
 
-## Projects
+*NiPreps* **augment the scanner to produce data *directly consumable* by analyses**.
 
-  * [*fMRIPrep*][1] ([GitHub](https://github.com/poldracklab/fmriprep)): fMRI Preprocessing
-  * [*dMRIPrep*][6] ([GitHub](https://github.com/nipreps/dmriprep)): dMRI Preprocessing
-  * [*sMRIPrep*][7] ([GitHub](https://github.com/poldracklab/smriprep)): Structural MRI Preprocessing
-  * [*MRIQC*][8] ([GitHub](https://github.com/poldracklab/mriqc)): MRI quality control
-  * [*SDCflows*][5] ([GitHub](https://github.com/nipreps/sdcflows)): Susceptibility-derived distortion correction (SDC) workflows
-  * [*NiWorkflows*][4] ([GitHub](https://github.com/nipreps/niworkflows)): General/miscellaneous workflow utilities
-  * [*TemplateFlow*][9]: A registry of neuroimaging templates and spatial mappings between them.
+We refer to data *directly consumable by analyses* as ***analysis-grade data*** by analogy with the concept of "*sushi-grade (or [sashimi-grade](https://en.wikipedia.org/wiki/Sashimi)) fish*" in that both are products that have been:
 
-## Overview of the framework
-
-The *NiPreps* framework (Figure 1) encompasses a wide array of software projects organized into three layers of scientific software:
-
-  * **Software infrastructure**: including quite mature projects such as [*NiPype*][2] and [*NiBabel*][3]; the standard specifications of the Brain Imaging Data Structure (BIDS, and BIDS-Derivatives); and some other tools such as *NiTransforms* or *TemplateFlow*, under development.
-    These tools deliver low-level interfaces (e.g., data access to images and spatial transforms) and utilities (see Figure 1).
-  * **Middleware**: these are utilities that generalize their functionalities across the end-user tools.
-    These utilities cover foundational processing methodologies (e.g., [*NiWorkflows*][4] and [*SDCflows*][5]), the crowdsourcing of metadata (e.g., *MRIQC Web-API*), and the support for deep learning models (*MRIQC-nets*).
-  * **End-user tools such as *fMRIPrep***: Some existing end-user tools include *sMRIPrep (Structural MRI Preprocessing)*, which lies in between an end-user tool and middleware, as it is involved in higher-level tools such as *fMRIPrep*. Finally, quality control tools (e.g., *MRIQC*) to be executed before any preprocessing happens.
-
-<!-- ![Branching](https://guides.github.com/activities/hello-world/branching.png) -->
-
-[1]: http://fmriprep.org/ "fMRIPrep documentation"
-[2]: https://nipype.readthedocs.io/ "NiPype documentation"
-[3]: https://nibabel.readthedocs.io/ "NiBabel documentation"
-[4]: https://www.nipreps.org/niworkflows/ "NiWorkflows documentation"
-[5]: https://www.nipreps.org/sdcflows/ "SDCflows documentation"
-[6]: https://www.nipreps.org/dmriprep/ "dMRIPrep documentation"
-[7]: https://poldracklab.github.io/smriprep "sMRIPrep documentation"
-[8]: https://mriqc.readthedocs.io/ "MRIQC Documentation"
-[9]: https://www.templateflow.org/ "TemplateFlow"
+  * **minimally preprocessed**, but are
+  * **safe to consume** directly.

docs/intro/nipreps.md

@@ -0,0 +1,46 @@
+# Framework
+
+## Building on *fMRIPrep*'s success story
+
+The current neuroimaging workflow has matured into a large chain of processing and analysis steps involving a large number of experts, across imaging modalities and applications.
+The development and fast adoption of [*fMRIPrep*][1] have revealed that neuroscientists need tools that simplify their research workflow, provide visual reports and checkpoints, and engender trust in the tool itself.
+The *NiPreps* framework extends *fMRIPrep*'s approach and principles to new imaging modalities.
+The vision for *NiPreps* is to provide end-users (i.e., researchers) with applications that allow them to perform quality control smoothly and to prepare their data for modeling and statistical analysis.
+
+## Leveraging BIDS
+
+*NiPreps* leverage the [Brain Imaging Data Structure (BIDS)](../apps/framework.md#what-is-bids) to understand all the particular
+features and available metadata (i.e., imaging parameters) of the input dataset.
+BIDS allows *NiPreps* to automatically stage the most adequate preprocessing workflow while minimizing manual intervention.
+
+## Architecture
+
+The *NiPreps* framework (Figure 1) encompasses a wide array of software projects organized into three layers of scientific software:
+
+  * **Software infrastructure**: including quite mature projects such as [*NiPype*][2] and [*NiBabel*][3]; the standard specifications of the Brain Imaging Data Structure (BIDS, and BIDS-Derivatives); and some other tools such as *NiTransforms* or *TemplateFlow*, under development.
+    These tools deliver low-level interfaces (e.g., data access to images and spatial transforms) and utilities (see Figure 1).
+  * **Middleware**: these are utilities that generalize their functionalities across the end-user tools.
+    These utilities cover foundational processing methodologies (e.g., [*NiWorkflows*][4] and [*SDCflows*][5]), the crowdsourcing of metadata (e.g., *MRIQC Web-API*), and the support for deep learning models (*MRIQC-nets*).
+  * **End-user tools such as *fMRIPrep***: Some existing end-user tools include *sMRIPrep (Structural MRI Preprocessing)*, which lies in between an end-user tool and middleware, as it is involved in higher-level tools such as *fMRIPrep*. Finally, quality control tools (e.g., *MRIQC*) to be executed before any preprocessing happens.
+
+## Projects
+
+  * [*fMRIPrep*][1] ([GitHub](https://github.com/poldracklab/fmriprep)): fMRI Preprocessing
+  * [*dMRIPrep*][6] ([GitHub](https://github.com/nipreps/dmriprep)): dMRI Preprocessing
+  * [*sMRIPrep*][7] ([GitHub](https://github.com/poldracklab/smriprep)): Structural MRI Preprocessing
+  * [*MRIQC*][8] ([GitHub](https://github.com/poldracklab/mriqc)): MRI quality control
+  * [*SDCflows*][5] ([GitHub](https://github.com/nipreps/sdcflows)): Susceptibility-derived distortion correction (SDC) workflows
+  * [*NiWorkflows*][4] ([GitHub](https://github.com/nipreps/niworkflows)): General/miscellaneous workflow utilities
+  * [*TemplateFlow*][9]: A registry of neuroimaging templates and spatial mappings between them.
+
+<!-- ![Branching](https://guides.github.com/activities/hello-world/branching.png) -->
+
+[1]: http://fmriprep.org/ "fMRIPrep documentation"
+[2]: https://nipype.readthedocs.io/ "NiPype documentation"
+[3]: https://nibabel.readthedocs.io/ "NiBabel documentation"
+[4]: https://www.nipreps.org/niworkflows/ "NiWorkflows documentation"
+[5]: https://www.nipreps.org/sdcflows/ "SDCflows documentation"
+[6]: https://www.nipreps.org/dmriprep/ "dMRIPrep documentation"
+[7]: https://poldracklab.github.io/smriprep "sMRIPrep documentation"
+[8]: https://mriqc.readthedocs.io/ "MRIQC Documentation"
+[9]: https://www.templateflow.org/ "TemplateFlow"

mkdocs.yml

@@ -12,8 +12,10 @@ copyright: Copyright © 2020
 
 nav:
     - Home: index.md
+    - NiPreps:
+      - Framework: intro/nipreps.md
     - BIDS-Apps:
-      - Framework: apps/framework.md
+      - Introduction: apps/framework.md
       - Executing with Docker: apps/docker.md
       - Executing with Singularity: apps/singularity.md
     - Developers: