diff --git a/assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer/index.html b/assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer/index.html
index c98c677..6854fd8 100644
--- a/assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer/index.html
+++ b/assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer/index.html
@@ -3,7 +3,7 @@
   <head>
     <title>fMRIPrep Bootcamp | Day 1 :: Introduction</title>
     <meta charset="utf-8">
-    <link rel="stylesheet" type="text/css" href="/talks/assets/asciinema-player/asciinema-player.css" />
+    <link rel="stylesheet" type="text/css" href="/assets/asciinema-player/asciinema-player.css" />
     <style>
       @import url(https://fonts.googleapis.com/css?family=Roboto+Mono:400,700,400italic);
 
@@ -340,7 +340,7 @@
     </style>
   </head>
   <body>
-<script src="/talks/assets/asciinema-player/asciinema-player.min.js"></script>
+<script src="/assets/asciinema-player/asciinema-player.min.js"></script>
 <script src="https://kit.fontawesome.com/7e31cfd31d.js" crossorigin="anonymous"></script>
 <script type="text/javascript"
   src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_CHTML">
diff --git a/assets/fmriprep-bootcamp-geneva2024/day1-02-bids/index.html b/assets/fmriprep-bootcamp-geneva2024/day1-02-bids/index.html
index dfb013f..b64a6af 100644
--- a/assets/fmriprep-bootcamp-geneva2024/day1-02-bids/index.html
+++ b/assets/fmriprep-bootcamp-geneva2024/day1-02-bids/index.html
@@ -3,7 +3,7 @@
   <head>
     <title>fMRIPrep Bootcamp | Day 1 :: Brain Imaging Data Structure</title>
     <meta charset="utf-8">
-    <link rel="stylesheet" type="text/css" href="/talks/assets/asciinema-player/asciinema-player.css" />
+    <link rel="stylesheet" type="text/css" href="/assets/asciinema-player/asciinema-player.css" />
     <style>
       @import url(https://fonts.googleapis.com/css?family=Roboto+Mono:400,700,400italic);
 
@@ -36,27 +36,35 @@
         transform: translateY(-50%);
       }
 
-      .remark-slide-content { height: 100%; padding: 0; }
-      .remark-slide-content h1 { font-size: 3em; }
-      .remark-slide-content h2 { font-size: 2em; }
-      .remark-slide-content h3 { font-size: 1.6em; }
+      .remark-slide-content { height: 100%; padding: 0; font-size: 16pt;}
+      .remark-slide-content h1 { font-size: 2em; color: #324989; }
+      .remark-slide-content h2 { font-size: 1.5em; color: #324989; }
+      .remark-slide-content h3 { font-size: 1.2em; color: #324989; }
       .footnote {
         position: absolute;
-        bottom: 3em;
+        bottom: 0.5em;
         font-size: 0.7em;
 	left: 6em;
       }
       li p { line-height: 1.25em; }
-      
+
       .remark-slide-content>p { margin-left: 60px; }
       .remark-slide-content>ul { margin-left: 60px; }
       .remark-slide-content>ul li { margin-left: 0.8em; }
 
+      .no-bullet > ul {
+        list-style-type: none;
+        padding-left:  0;
+      }
+
+      .no-bullet > ul > li > ul {
+        padding-left:  2.8em;
+      }
 
       .red { color: #fa0000; }
       .blue { color: #0000fa; }
       .green { color: #698b69; }
-      .large { font-size: 2em; }
+
       a, a > code {
         color: rgb(249, 38, 114);
         text-decoration: none;
@@ -68,7 +76,6 @@
       .remark-code, .remark-inline-code { font-family: 'Roboto Mono'; }
       .large .remark-code, .large .remark-inline-code { font-size: 0.8em; }
       .remark-code-line-highlighted     { background-color: #373832; }
-      .remark-code { width: 85%; }
       .pull-left {
         float: left;
         width: 45%;
@@ -93,6 +100,28 @@
         width: 80%;
       }
 
+      .fa-solid {
+        color: #324989;
+      }
+      .fa-blank {
+	color: #ffffff;
+      }
+
+      em {
+        color: #324989;
+      }
+
+      strong {
+        color: #324989;
+      }
+
+      .gray-text {
+        color: #888;
+      }
+      .gray-text em, .gray-text strong {
+        color: #888;
+      }
+
       .perma-sidebar {
         float: left;
         background-color: #324989;
@@ -133,7 +162,7 @@
         left: 20px;
       }
       #slide-how .slides {
-        font-size: 0.9em;
+        /*font-size: .9em;*/
         position: absolute;
         top:  151px;
         right: 140px;
@@ -172,7 +201,7 @@
           color: #000;
         }
       .right-column {
-        width: 55%;
+        width: 65%;
         float: right;
         padding-top: 1em;
       }
@@ -186,9 +215,10 @@
           color: #000;
         }
       .right-column2 {
-        width: 43%;
+        width: 50%;
         float: right;
         padding-top: 1em;
+        margin-right: 2.5em;
       }
       /* Two-column layout (60% left) */
       .left-column3 {
@@ -252,22 +282,27 @@
       }
 
       .small {
-        font-size: 12pt;
+        font-size: 0.7em;
       }
 
       .larger {
-        font-size: 20pt;
+        font-size: 1.4em;
       }
 
       .large {
-        font-size: 24pt;
+        font-size: 1.6em;
       }
 
       .boxed-content {
         float: left;
         display: block;
         width: 89%;
-        height: 70%;
+        padding-right: 4%;
+      }
+
+      .boxed-bottom {
+        clear: both;
+        margin-top: 0px;
       }
 /*
       .distribute {
@@ -306,8 +341,9 @@
         color: transparent; /* make the text invisible */
         user-select: none; /* prevent selection of the text */
       }
-      .gray-text {
-        color: #aaa;
+
+      .pad-left {
+        padding-left: 2.0em;
       }
       .install-cmd {
           top: 20px;
@@ -323,14 +359,11 @@
       figcaption {
 	  text-align: right;
       }
-      figcaption a {
-        color: #444444;
-        text-decoration: underline dotted;
-      }
+
     </style>
   </head>
   <body>
-<script src="/talks/assets/asciinema-player/asciinema-player.min.js"></script>
+<script src="/assets/asciinema-player/asciinema-player.min.js"></script>
 <script src="https://kit.fontawesome.com/7e31cfd31d.js" crossorigin="anonymous"></script>
 <script type="text/javascript"
   src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_CHTML">
@@ -374,7 +407,9 @@
 
 ## The Brain Imaging Data Structure (BIDS)
 
-#### Chris Markiewicz &lt;<code>markiewicz@stanford.edu</code>> & Oscar Esteban &lt;<code>phd@oscaresteban.es</code>>
+Chris Markiewicz &lt;<code>markiewicz@stanford.edu</code>>
+
+Oscar Esteban &lt;<code>phd@oscaresteban.es</code>>
 
 ]
 
@@ -395,7 +430,7 @@
 
 ---
 
-## Outlook
+# Outlook
 
 .right-column3.center[
 <a href="https://www.nipreps.org/assets/fmriprep-bootcamp-geneva2024/day1-02-bids/">
@@ -409,20 +444,7 @@
 
 .large[
 
-<br />
-
-* Overview of the neuroimaging pipeline structure
-
-* Why do data require preprocessing?
-
-* *fMRIPrep*
-
-    * [Hi]story behind the tool
-    * Why — just preprocessing
-    * Why — standardization
-    * Why — community
-
-* *NiPreps*
+* 
 
 ]]
 
@@ -435,15 +457,46 @@
 
 # BIDS: Brain Imaging Data Structure
 
----
-layout: true
-template: BIDS
-
-.pull-left[![Bids Layout](images/bids.png)]
+.left-column2.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> CHANGES]<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> README]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> dataset_description.json]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> participants.json]<br />
+.pad-left[<i class="fa-solid fa-table"></i> participants.tsv]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> scans.json]<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> anat/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_T2w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_T2w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-denoised_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-mp2rage_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-mp2rage_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> fmap/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude1.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude1.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude2.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude2.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_phasediff.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_phasediff.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> func/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-mixed_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_bold.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_task-mixed_events.tsv]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-rest_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-rest_bold.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_scans.tsv]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
+]
 
 ---
 
-.pull-right[
+.right-column2.larger[
+
 * BIDS is a directory structure, based on common practices
 
 * Builds on existing standards (NIfTI, JSON, TSV)
@@ -459,107 +512,397 @@
 
 ---
 
-.pull-right[
+.right-column2[.no-bullet[* .larger[Basic metadata in the file names]
+  * Subject, session, imaging modality, etc.
+  * Generally just enough to assign unique names]]
+--
+.right-column2[.no-bullet[* .larger[NIfTI headers and *JSON sidecars* contain detailed,
+  image-related metadata]]]
+--
+.right-column2[.no-bullet[* .larger[Study-level metadata]
+  * Not necessarily associated with specific files
+  * [`dataset_description.json`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#dataset_descriptionjson),
+    [`participants.tsv`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#participants-file),
+    [`sessions.tsv`](https://bids-specification.readthedocs.io/en/stable/05-longitudinal-and-multi-site-studies.html#sessions-file),
+    and [`scans.tsv`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#scans-file)
+]]
 
-* Basic metadata in the file names
+---
+template: newsection
+layout: true
 
-  * Subject, session, imaging modality, etc.
-  * Generally just enough to assign unique names
+---
 
+# Converting from DICOM into BIDS
+
+.left-column-mid.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 10 - anat-T1w_acq-mp2rage_run-01_UNI_Images.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 11 - anat-T1w_acq-mp2rage_run-01_UNI-DEN.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 12 - anat-T1w_acq-mp2rage_run-01_INV2.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 16 - fmap-gre_acq-siemens_run-01/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 17 - fmap-gre_acq-siemens_run-01.dicom ]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 18 - func-bold_acq-midRes_task-rest_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 20 - func-bold_acq-midRes_task-mixed_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 22 - anat-T2w_acq-p6_run-01.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 7 - anat-T1w_acq-mp2rage_run-01_INV1.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 8 - anat-T1w_acq-mp2rage_run-01_T1_Images.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 9 - anat-T1w_acq-mp2rage_run-01_T1_Images.dicom]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
 ]
 
----
-count: false
+.right-column-mid[
+.no-bullet[
+* .larger[DICOM (Digital Imaging and Communications in Medicine)]
+   * was originally meant for storage and transmission within/between machines.
+* .larger[DICOM structures store their relevant metadata internally,]
+   * but structure and fields tend to be vendor- & institution-specific.
 
-.pull-right[
-* Basic metadata in the file names
-  * Subject, session, imaging modality, etc.
-  * Generally just enough to assign unique names
+* .larger[Constructing a BIDS dataset can be tedious and error-prone, so there are several
+[converters](https://bids.neuroimaging.io/benefits.html#converters).] 
+   * The [Heuristic DICOM Converter](https://heudiconv.readthedocs.io/) (HeuDiConv) and
+[BIDSCoin](https://bidscoin.readthedocs.io/en/stable/) allow you to specify the mapping and
+apply in bulk. Both build off of [dcm2niix](https://github.com/rordenlab/dcm2niix/).
+]
+]
+
+---
 
-* NIfTI headers and JSON sidecars contain detailed,
-  image-related metadata
+# Converting from DICOM into BIDS
+
+.left-column-mid.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 10 - anat-T1w_acq-mp2rage_run-01_UNI_Images.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 11 - anat-T1w_acq-mp2rage_run-01_UNI-DEN.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 12 - anat-T1w_acq-mp2rage_run-01_INV2.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 16 - fmap-gre_acq-siemens_run-01/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 17 - fmap-gre_acq-siemens_run-01.dicom ]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 18 - func-bold_acq-midRes_task-rest_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 20 - func-bold_acq-midRes_task-mixed_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 22 - anat-T2w_acq-p6_run-01.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 7 - anat-T1w_acq-mp2rage_run-01_INV1.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 8 - anat-T1w_acq-mp2rage_run-01_T1_Images.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 9 - anat-T1w_acq-mp2rage_run-01_T1_Images.dicom]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
+]
 
+.right-column-mid.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> CHANGES]<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> README]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> dataset_description.json]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> participants.json]<br />
+.pad-left[<i class="fa-solid fa-table"></i> participants.tsv]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> scans.json]<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> anat/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_T2w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_T2w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-denoised_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-mp2rage_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-mp2rage_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> fmap/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude1.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude1.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude2.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude2.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_phasediff.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_phasediff.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> func/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-mixed_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_bold.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_task-mixed_events.tsv]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-rest_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-rest_bold.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_scans.tsv]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
 ]
+]
+
+<i class="fa-solid fa-circle-right" style="margin-top: 20%; font-size: 1.7em"></i>
 
 ---
-count: false
 
-.pull-right[
-* Basic metadata in the file names
-  * Subject, session, imaging modality, etc.
-  * Generally just enough to assign unique names
+# DICOM-to-BIDS: ReproIn
+
+.center[[ReproIn](https://github.com/ReproNim/reproin) standardizes scanner conventions:]
+
+<figure style="width: 60%">
+![:img HCPh-sops-naming, 100%](https://www.axonlab.org/hcph-sops/assets/images/launch_sequence.jpg)
+<figcaption>From <a href="https://www.axonlab.org/hcph-sops">the HCPh SOPs</a>;
+doi:![:doi](10.6084/m9.figshare.19579873.v1)</figcaption>
+</figure>
+
+---
+
+<figure style="width: 60%">
+![:img ReproIn conversion schema, 100%](images/dbic-conversions_cropped.png)
+<figcaption>From <a href="https://github.com/ReproNim/reproin/blob/master/README.md#overall-workflow">ReproIn</a>;
+doi:![:doi](10.5281/zenodo.1207117)</figcaption>
+
+???
+
+Please note that this figure is OUT OF DATE. For example, the anatomicals are called anat-T1W__, anat-T2w__ etc.
+
+---
+
+# DICOM-to-BIDS: HeuDiConv
+
+.boxed-content.no-bullet[
+
+* .large[<i class="fa-solid fa-circle-chevron-right"></i> **Heu**ristic **DI**COM** Conv**erter: maps DICOM metadata into BIDS]
+
+* .large[<i class="fa-solid fa-circle-chevron-right"></i> Mappings are encoded within the *heuristic file*]
 
-* NIfTI headers and JSON sidecars contain detailed,
-  image-related metadata
+   * The `.heudiconv/` folder contains the metadata that can be employed in the *heuristic file* to define mappings.<br /><br />
+
+<figure style="width: 100%">
+![:img HeuDiConv workflow, 100%](https://raw.githubusercontent.com/nipy/heudiconv/master/figs/workflow.png)
+<figcaption>From <a href="https://github.com/nipy/heudiconv?tab=readme-ov-file#howto-101">HeuDiConv</a>;
+doi:![:doi](10.5281/zenodo.1012598)</figcaption>
 
-* [`dataset_description.json`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#dataset_descriptionjson),
-  [`participants.tsv`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#participants-file),
-  [`sessions.tsv`](https://bids-specification.readthedocs.io/en/stable/05-longitudinal-and-multi-site-studies.html#sessions-file),
-  and [`scans.tsv`](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#scans-file)
-  record study-level metadata that may not be associated
-  with specific images
 ]
 
 ---
-layout: true
-template: newsection
+
+# DICOM-to-BIDS: HeuDiConv
+
+.boxed-content[
+
+.no-bullet.large[
+* <i class="fa-solid fa-1"></i> &nbsp; Generate a **heuristic file**
+
+* <i class="fa-solid fa-2"></i> &nbsp; Edit the **heuristic file**
+]
+
+.small[
+```Python
+data = create_key('run-{item:03d}')
+
+t1w = create_key('sub-{subject}/{session}/anat/sub-{subject}_{session}_T1w')
+
+dwi = create_key('sub-{subject}/{session}/dwi/sub-{subject}_{session}_dir-AP_dwi')
+
+# Save the RPE (reverse phase-encode) B0 image as a fieldmap (fmap).  It will be used to correct
+# the distortion in the DWI
+fmap_rev_phase =  create_key('sub-{subject}/{session}/fmap/sub-{subject}_{session}_dir-PA_epi')
+
+fmap_mag =  create_key('sub-{subject}/{session}/fmap/sub-{subject}_{session}_magnitude')
+
+fmap_phase = create_key('sub-{subject}/{session}/fmap/sub-{subject}_{session}_phasediff')
+
+# Even if this is resting state, you still need a task key
+func_rest = create_key('sub-{subject}/{session}/func/sub-{subject}_{session}_task-rest_run-01_bold')
+func_rest_post = create_key('sub-{subject}/{session}/func/sub-{subject}_{session}_task-rest_run-02_bold')
+```
+]
+
+.no-bullet.large[
+* <i class="fa-solid fa-3"></i> &nbsp; Execute *HeuDiConv*
+]
+
+]
 
 ---
 
-# Bidsification
+# DICOM-to-BIDS: ReproIn + HeuDiConv
 
-Constructing a BIDS dataset can be tedious and error-prone, so there are several
-[converters](https://bids.neuroimaging.io/benefits.html#converters).
+.no-bullet.large[
+* <i class="fa-solid fa-circle-chevron-right"></i> &nbsp; Just run *HeuDiConv* directly! *Heuristic file* is pre-defined.
 
-<figure style="width: 50%">
-![:img DICOM to BIDS conversion, 100%](images/dicom-reorganization-transparent-black_1000x477.png)
-</figure>
+* <i class="fa-solid fa-circle-question"></i> &nbsp; What if I **did not** follow *ReproIn* namings?
+]
 
-DICOM images store their relevant metadata internally, but naming conventions tend
-to be scanner/institution-specific.
+--
 
-The [Heuristic DICOM Converter](https://heudiconv.readthedocs.io/) (HeuDiConv) and
-[BIDSCoin](https://bidscoin.readthedocs.io/en/stable/) allow you to specify the mapping and
-apply in bulk. Both build off of [dcm2niix](https://github.com/rordenlab/dcm2niix/).
+.boxed-content.small[
+
+``` Python
+# A dictionary containing fixes/remapping for sequence names per study.
+# Keys are md5sum of study_description from DICOMs, in the form of PI-Experimenter^protocolname
+# You can use `heudiconv -f reproin --command ls --files  PATH
+# to list the "study hash".
+# Values are list of tuples in the form (regex_pattern, substitution).
+# If the  key is an empty string "", it would apply to any study.
+protocols2fix: dict[str | re.Pattern[str], list[tuple[str, str]]] = {
+    "": [  # <-- empty string means apply to whole study
+        ("anat-T1w_acq-mp2rage_run-01", "anat-mp2rage"),
+        ("_UNI_", "_acq-mp2rage__"),
+        ("_UNI-DEN", "_acq-denoised__"),
+        ("_INV", "_inv-"),
+        ("_T1_", "_acq-T1map__"),
+        ("fmap_acq-siemens", "fmap-phasediff"),
+        ("fmap-gre_acq-siemens", "fmap-phasediff"),
+        ("_acq-midRes", ""),
+        ("_acq-p6", ""),
+        ("_run-01", ""),
+    ]
+}
+```
+
+]
 
 ---
 
-# Bidsification: ReproIn
+# DICOM-to-BIDS: ReproIn + HeuDiConv
+
+.left-column-mid[
+Our dataset's DICOM had some non-compliant names:
+.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 10 - anat-T1w_acq-mp2rage_run-01<mark>_UNI_Images</mark>.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 11 - anat-T1w_acq-mp2rage_run-01<mark>_UNI-DEN</mark>.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 12 - anat-T1w_acq-mp2rage_run-01<mark>_INV2</mark>.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 16 - fmap-gre_acq-siemens_run-01/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 17 - <mark>fmap-gre</mark>_acq-siemens_run-01.dicom ]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 18 - func-bold_acq-midRes_task-rest_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> 20 - func-bold_acq-midRes_task-mixed_run-01/ ]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[...]25.MR.dcm]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-ellipsis"></i>]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 1.3.12.2.1107.5.2.61.237203.20[..]33.MR.dcm]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 22 - anat-T2w_acq-p6_run-01.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 7 - anat-T1w_acq-mp2rage_run-01<mark>_INV1</mark>.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 8 - anat-T1w_acq-mp2rage_run-01<mark>_T1_Images</mark>.dicom]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-layer-group"></i> 9 - anat-T1w_acq-mp2rage_run-01<mark>_T1_Images</mark>.dicom]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
+]]
 
-The [ReproIn](https://github.com/ReproNim/reproin) project aims to
-standardize scanner conventions, to eliminate the need to rewrite these mappings.
+.right-column-mid.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> my_dataset/<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> CHANGES]<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> README]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> dataset_description.json]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> participants.json]<br />
+.pad-left[<i class="fa-solid fa-table"></i> participants.tsv]<br />
+.pad-left[<i class="fa-solid fa-paperclip"></i> scans.json]<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> anat/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_T2w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_T2w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-denoised_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_acq-mp2rage_T1w.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-mp2rage_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> fmap/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude1.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude1.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_magnitude2.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_magnitude2.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_phasediff.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_phasediff.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> func/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-mixed_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_bold.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_task-mixed_events.tsv]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-paperclip"></i> sub-11_task-rest_bold.json]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-rest_bold.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-table"></i> sub-11_scans.tsv]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
+]
 
-<figure style="width: 40%">
-![:img ReproIn conversion schema, 100%](images/dbic-conversions_cropped.png)
-<figcaption>From <a href="https://github.com/ReproNim/reproin/blob/master/README.md#overall-workflow">ReproIn</a>;
-doi:![:doi](10.5281/zenodo.1207117)</figcaption>
-</figure>
+<i class="fa-solid fa-circle-right" style="margin-top: 20%; font-size: 1.7em"></i>
 
 ---
 
 # BIDS Validator
 
+.boxed-content[
 The machine-readable structure makes validation possible:
 
-```bash
-$ deno run -A jsr:@bids/validator /data/bids/openneuro/ds000228
-        [WARNING] JSON_KEY_RECOMMENDED A JSON file is missing a key listed as recommended.
-                DatasetType
-                /dataset_description.json
+``` bash
+$ bids-validator .
+bids-validator@1.14.6
+
+  1: [WARN] The recommended file /README is very small. Please consider expanding it with additional information about the dataset. (code: 213 - README_FILE_SMALL)
+    ./README
 
-                GeneratedBy
-                /dataset_description.json
+  Please visit https://neurostars.org/search?q=README_FILE_SMALL for existing conversations about this issue.
 
-                SourceDatasets
-                /dataset_description.json
+        Summary:                Available Tasks:                            Available Modalities: 
+        96 Files, 6.63GB        Mixed-stimuli, positive-control task        MRI                   
+        5 - Subjects            Resting-state fMRI                                                
+        1 - Session                                                                               
 
-        Please visit https://neurostars.org/search?q=JSON_KEY_RECOMMENDED for existing 
-	conversations about this issue.
-...
+
+  If you have any questions, please post on https://neurostars.org/tags/bids.
 ```
 
 .center[
 ## https://bids-standard.github.io/bids-validator/
+]]
+
+---
+
+# BIDS Validator
+
+.boxed-content[
+Once all warnings and errors are addressed:
+
+``` bash
+$ bids-validator .
+bids-validator@1.14.6
+
+This dataset appears to be BIDS compatible.
+        Summary:                Available Tasks:                            Available Modalities: 
+        96 Files, 6.63GB        Mixed-stimuli, positive-control task        MRI                   
+        5 - Subjects            Resting-state fMRI                                                
+        1 - Session                                                                               
+
+
+  If you have any questions, please post on https://neurostars.org/tags/bids.
+```
+
+.center[
+## https://bids-standard.github.io/bids-validator/
+]]
+
+---
+
+# Sharing through OpenNeuro
+
+.boxed-content[
+.center[[https://openneuro.org/datasets/ds005454/versions/1.0.0](https://openneuro.org/datasets/ds005454/versions/1.0.0)]
+
+<iframe src="https://openneuro.org/datasets/ds005454/versions/1.0.0" width="100%" height="500px" style="border: 0" />
 ]
 
 ---
@@ -570,12 +913,10 @@
 # BIDS Applications
 
 ---
-
 A common specification of neuroimaging datasets affords queries for and
 adaptation to the available data.
-
 --
-
+.boxed-content[
 Queryable (meta)data allows a very simple protocol for a
 [BIDS App](https://bids-apps.neuroimaging.io/apps/):
 
@@ -586,10 +927,11 @@
 .footnote[
 \* Note that `participant` is an analysis level. Apps may also operate
 at the `run`, `session` or `group` levels.
-]
+]]
 
 --
 
+.boxed-content[
 ## Examples
 
 **MRIQC**
@@ -597,16 +939,17 @@
 ```Bash
 mriqc /data/bids/openneuro/ds000228 /data/processed/ds000228-mriqc group
 ```
-
+]
 --
 
+.boxed-content[
 **fMRIPrep**
 
 ```Bash
 fmriprep /data/bids/openneuro/ds000228 /data/processed/ds000228-fmriprep \
     participant --participant-label pixar001
 ```
-
+]
 ---
 
 .pull-left[
@@ -707,8 +1050,156 @@
 ]
 
 ---
+template: newsection
+layout: true
+name: Derivatives
+
+# BIDS Derivatives
+
+---
+
+BIDS Derivatives generally mirror the raw dataset.
+
+.small[
+.pad-left[
+<i class="fa-solid fa-folder-open"></i> fmriprep/<br />
+.pad-left[<i class="fa-solid fa-file-lines"></i> README]<br />
+.pad-left[<i class="fa-solid fa-circle-info"></i> dataset_description.json]<br />
+.pad-left[<i class="fa-solid fa-folder-open"></i> sub-11]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> anat/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_desc-preproc_T2w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_desc-preproc_T1w.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_desc-brain_mask.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_acq-denoised_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-blank fa-brain"></i> ...]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> fmap/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_fmapid-auto00000_desc-coeff_fieldmap.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_fmapid-auto00000_desc-magnitude_fieldmap.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_fmapid-auto00000_desc-preproc_fieldmap.nii.gz]]]<br />
+.pad-left[.pad-left[<i class="fa-solid fa-folder-open"></i> func/]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_desc-coreg_boldref.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_desc-hmc_boldref.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-file-lines"></i> sub-11_task-mixed_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-file-lines"></i> sub-11_task-mixed_from-boldref_to-auto00000_mode-image_desc-fmapreg_xfm.txt]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-solid fa-brain"></i> sub-11_task-mixed_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz]]]<br />
+.pad-left[.pad-left[.pad-left[<i class="fa-blank fa-brain"></i> ...]]]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-14]<br />
+.pad-left[<i class="fa-solid fa-folder"></i> sub-15]<br />
+]
+]
+
+--
+
+New file suffixes, extensions and entities are possible.
+
+---
+template: newsection
+layout: true
+name: PyBIDS
+
+.install-cmd[
+```Bash
+pip install pybids
+```
+]
+
+---
+
+# PyBIDS
+
+.boxed-content[
+A common specification of neuroimaging datasets affords queries for and
+adaptation to the available data.
+
+[PyBIDS](https://github.com/bids-standard/pybids/) is a Python library for
+querying and manipulating BIDS datasets.
+
+
+```Python
+>>> from bids import BIDSLayout
+>>> layout = BIDSLayout('/my_dataset')
+>>> bold = layout.get(subject='11', task='rest', suffix='bold', extension='.nii.gz')
+>>> bold
+[<BIDSImageFile filename='/my_dataset/sub-11/func/sub-11_task-rest_bold.nii.gz'>]
+>>> md = bold[0].get_metadata()
+>>> md['RepetitionTime']
+1.5
+>>> bold[0].get_entities()
+{'datatype': 'func',
+ 'extension': '.nii.gz',
+ 'subject': '11',
+ 'suffix': 'bold',
+ 'task': 'rest'}
+```
+]
+---
+
+# PyBIDS | Derivatives
+
+.boxed-content[
+PyBIDS layouts support BIDS derivatives:
+
+```Python
+>>> fmri_derivs = BIDSLayout(
+...     '/my_dataset-fmriprep',
+...     config=['bids', 'derivatives'],
+...     validate=False,
+... )
+>>> spaces = fmri_derivs.get_spaces(desc='preproc', suffix='bold')
+>>> spaces
+['MNI152NLin2009cAsym']
+```
+]
+--
+
+.boxed-content[
+It is also possible to provide your own config:
+
+```Python
+>>> import niworkflows
+>>> nipreps_config = niworkflows.data.load('nipreps.json')
+>>> fmri_derivs = BIDSLayout('/my_dataset-fmriprep', config=[nipreps_config], validate=False)
+```
+]
+---
+
+# PyBIDS | Large datasets
+
+.boxed-content[
+<br />
+.larger[*BIDS Apps* can spend long time indexing if they rely on *PyBIDS* ]
+.no-bullet[
+* <i class="fa-solid fa-circle-right"></i> **create a cache**:
+]
+
+```Bash
+$ pybids layout --reset-db --no-validate --index-metadata . /my_dataset/.bids-index/
+```
+
+.larger[And then inform your *BIDS App*.]
+
+<br />
+
+In the case of *MRIQC* and *fMRIPrep*, point the `--bids-database-dir` argument to the newly created cache:
+
+```Bash
+$ mriqc /data/input /derivatives/output participant [OPTIONS] \
+    --bids-database-dir /my_dataset/.bids-index/
+```
+
+```Bash
+$ fmriprep /data/input /derivatives/output participant [OPTIONS] \
+    --bids-database-dir /my_dataset/.bids-index/
+```
+
+]
+
+---
+
+template: newsection
 
-## Conclusion
+# Conclusion
 
 .boxed-content[
 .distribute.large[
diff --git a/search/search_index.json b/search/search_index.json
index e8f452b..f3db462 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"NeuroImaging PREProcessing toolS (NiPreps)","text":"<p>NiPreps augment the scanner to produce data directly consumable by analyses.</p> <p>We refer to data directly consumable by analyses as analysis-grade data by analogy with the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are products that have been:</p> <ul> <li>minimally preprocessed, but are</li> <li>safe to consume directly.</li> </ul> <p> </p>"},{"location":"#building-on-the-success-story-of-fmriprep","title":"Building on the success story of fMRIPrep","text":"<p>NiPreps were conceived as a generalization of fMRIPrep across new modalities, populations, cohorts, and species. fMRIPrep is widely adopted, as our telemetry with Sentry (and now, in-house with migas) shows:</p> fMRIPrep is executed an average of 9,500 times every week, of which, around 7,000 times it finishes successfully (72.9% success rate). The average number of executions started includes debug and dry runs where researchers do not intend actually process data. Therefore, the effective (that is, discarding test runs) success ratio of fMRIPrep is likely higher."},{"location":"apps/docker/","title":"Executing with Docker","text":"<p>Summary</p> <p>Here, we describe how to run NiPreps with Docker containers. To illustrate the process, we will show the execution of fMRIPrep, but these guidelines extend to any other end-user NiPrep.</p>"},{"location":"apps/docker/#before-you-start-install-docker","title":"Before you start: install Docker","text":"<p>Probably, the most popular framework to execute containers is Docker. If you are to run a NiPrep on your PC/laptop, this is the RECOMMENDED way of execution. Please make sure you follow the Docker installation instructions. You can check your Docker Runtime installation running their <code>hello-world</code> image:</p> <pre><code>$ docker run --rm hello-world\n</code></pre> <p>If you have a functional installation, then you should obtain the following output:</p> <pre><code>Hello from Docker!\nThis message shows that your installation appears to be working correctly.\n\nTo generate this message, Docker took the following steps:\n 1. The Docker client contacted the Docker daemon.\n 2. The Docker daemon pulled the \"hello-world\" image from the Docker Hub.\n    (amd64)\n 3. The Docker daemon created a new container from that image which runs the\n    executable that produces the output you are currently reading.\n 4. The Docker daemon streamed that output to the Docker client, which sent it\n    to your terminal.\n\nTo try something more ambitious, you can run an Ubuntu container with:\n $ docker run -it ubuntu bash\n\nShare images, automate workflows, and more with a free Docker ID:\n https://hub.docker.com/\n\nFor more examples and ideas, visit:\n https://docs.docker.com/get-started/\n</code></pre> <p>After checking your Docker Engine is capable of running Docker images, you are ready to pull your first NiPreps container image.</p>"},{"location":"apps/docker/#docker-images","title":"Docker images","text":"<p>For every new version of the particular NiPrep app that is released, a corresponding Docker image is generated. The Docker image becomes a container when the execution engine loads the image and adds an extra layer that makes it runnable. In order to run NiPreps Docker images, the Docker Runtime must be installed.</p> <p>Taking fMRIPrep to illustrate the usage, first you might want to make sure of the exact version of the tool to be used:</p> <pre><code>$ docker pull nipreps/fmriprep:&lt;latest-version&gt;\n</code></pre> <p>You can run NiPreps interacting directly with the Docker Engine via the <code>docker run</code> interface.</p>"},{"location":"apps/docker/#running-a-niprep-with-a-lightweight-wrapper","title":"Running a NiPrep with a lightweight wrapper","text":"<p>Some NiPreps include a lightweight wrapper script for convenience. That is the case of fMRIPrep and its <code>fmriprep-docker</code> wrapper. Before starting, make sure you have the wrapper installed. When you run <code>fmriprep-docker</code>, it will generate a Docker command line for you, print it out for reporting purposes, and then execute it without further action needed, e.g.:</p> <pre><code>$ fmriprep-docker /path/to/data/dir /path/to/output/dir participant\nRUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \\\n    -v /path/to_output/dir:/out nipreps/fmriprep:20.2.2 \\\n    /data /out participant\n...\n</code></pre> <p><code>fmriprep-docker</code> implements the unified command-line interface of BIDS Apps, and automatically translates directories into Docker mount points for you.</p> <p>We have published a step-by-step tutorial illustrating how to run <code>fmriprep-docker</code>. This tutorial also provides valuable troubleshooting insights and advice on what to do after fMRIPrep has run.</p>"},{"location":"apps/docker/#running-a-niprep-directly-interacting-with-the-docker-engine","title":"Running a NiPrep directly interacting with the Docker Engine","text":"<p>If you need a finer control over the container execution, or you feel comfortable with the Docker Engine, avoiding the extra software layer of the wrapper might be a good decision.</p> <p>Accessing filesystems in the host within the container: Containers are confined in a sandbox, so they can't access the host in any ways unless you explicitly prescribe acceptable accesses to the host. The Docker Engine provides mounting filesystems into the container with the <code>-v</code> argument and the following syntax: <code>-v some/path/in/host:/absolute/path/within/container:ro</code>, where the trailing <code>:ro</code> specifies that the mount is read-only. The mount permissions modifiers can be omitted, which means the mount will have read-write permissions. In general, you'll want to at least provide two mount-points: one set in read-only mode for the input data and one read/write to store the outputs. Potentially, you'll want to provide one or two more mount-points: one for the working directory, in case you need to debug some issue or reuse pre-cached results; and a TemplateFlow folder to preempt the download of your favorite templates in every run.</p> <p>Running containers as a user: By default, Docker will run the container as root. Some share systems my limit this feature and only allow running containers as a user. When the container is run as root, files written out to filesystems mounted from the host will have the user id <code>1000</code> by default. In other words, you'll need to be able to run as root in the host to change permissions or manage these files. Alternatively, running as a user allows preempting these permissions issues. It is possible to run as a user with the <code>-u</code> argument. In general, we will want to use the same user ID as the running user in the host to ensure the ownership of files written during the container execution. Therefore, you will generally run the container with <code>-u $( id -u )</code>.</p> <p>You may also invoke <code>docker</code> directly:</p> <pre><code>$ docker run -ti --rm \\\n    -v path/to/data:/data:ro \\\n    -v path/to/output:/out \\\n    nipreps/fmriprep:&lt;latest-version&gt; \\\n    /data /out/out \\\n    participant\n</code></pre> <p>For example: :</p> <pre><code>$ docker run -ti --rm \\\n    -v $HOME/ds005:/data:ro \\\n    -v $HOME/ds005/derivatives:/out \\\n    -v $HOME/tmp/ds005-workdir:/work \\\n    nipreps/fmriprep:&lt;latest-version&gt; \\\n    /data /out/fmriprep-&lt;latest-version&gt; \\\n    participant \\\n    -w /work\n</code></pre> <p>Once the Docker Engine arguments are written, the remainder of the command line follows the usage. In other words, the first section of the command line is all equivalent to the <code>fmriprep</code> executable in a bare-metal installation: :</p> <pre><code>$ docker run -ti --rm \\                      # These lines\n    -v $HOME/ds005:/data:ro \\                # are equivalent to\n    -v $HOME/ds005/derivatives:/out \\        # a call to the App's\n    -v $HOME/tmp/ds005-workdir:/work \\       # entry-point.\n    nipreps/fmriprep:&lt;latest-version&gt; \\  #\n    \\\n    /data /out/fmriprep-&lt;latest-version&gt; \\   # These lines correspond\n    participant \\                            # to the particular BIDS\n    -w /work                                 # App arguments.\n</code></pre>"},{"location":"apps/framework/","title":"Introduction","text":""},{"location":"apps/framework/#what-is-bids","title":"What is BIDS?","text":"<p>The Brain Imaging Data Structure (BIDS) is a standard for organizing and describing brain datasets, including MRI. The common naming convention and folder structure allow researchers to easily reuse BIDS datasets, re-apply analysis protocols, and run standardized automatic data preprocessing pipelines (and particularly, BIDS Apps). The BIDS starter-kit contains a wide collection of educational resources. Validity of the structure can be assessed with the online BIDS-Validator. The tree of a typical, valid (BIDS-compliant) dataset is shown below:</p> <pre><code>ds000003/\n \u251c\u2500 CHANGES\n \u251c\u2500 dataset_description.json\n \u251c\u2500 participants.tsv\n \u251c\u2500 README\n \u251c\u2500 sub-01/\n \u2502 \u251c\u2500 anat/\n \u2502 \u2502 \u251c\u2500 sub-01_inplaneT2.nii.gz\n \u2502 \u2502 \u2514\u2500 sub-01_T1w.nii.gz\n \u2502 \u2514\u2500 func/\n \u2502 \u251c\u2500 sub-01_task-rhymejudgment_bold.nii.gz\n \u2502 \u2514\u2500 sub-01_task-rhymejudgment_events.tsv\n \u251c\u2500 sub-02/\n \u251c\u2500 sub-03/\n</code></pre>"},{"location":"apps/framework/#what-is-a-bids-app","title":"What is a BIDS App?","text":"<p>(Taken from the BIDS Apps paper)</p> <p>A BIDS App is a container image capturing a neuroimaging pipeline that takes a BIDS-formatted dataset as input. Since the input is a whole dataset, apps are able to combine multiple modalities, sessions, and/or subjects, but at the same time need to implement ways to query input datasets. Each BIDS App has the same core set of command-line arguments, making them easy to run and integrate into automated platforms. BIDS Apps are constructed in a way that does not depend on any software outside of the container image other than the container engine.</p> <p>BIDS Apps rely upon two technologies for container computing:</p> <ol> <li>Docker \u2014 for building, hosting as well as running containers on local hardware (running Windows, Mac OS X or Linux) or in the cloud.</li> <li>Singularity \u2014 for running containers on HPCs (high-performance computing).</li> </ol> <p>BIDS Apps are deposited in the Docker Hub repository, making them openly accessible. Each app is versioned and all of the historical versions are available to download. By reporting the BIDS App name and version in a manuscript, authors can provide others with the ability to exactly replicate their analysis workflow.</p> <p>Docker is used for its excellent documentation, maturity, and the Docker Hub service for storage and distribution of the images. Docker containers are easily run on personal computers and cloud services. However, the Docker Runtime was originally designed to run different components of web services (HTTP servers, databases etc.) using cloud resources. Docker thus requires root or root-like permissions, as well as modern versions of Linux kernel (to perform user mapping and management of network resources); though this is not a problem in context of renting cloud resources (which are not shared with other users), it makes it difficult or impossible to use in a multi-tenant environment such as an HPC system, which is often the most cost-effective computational resource available to researchers.</p> <p>Singularity, on the other hand, is a unique container technology designed from the ground up with the encapsulation of binary dependencies and HPC use in mind. Its main advantage over Docker is that it does not require root access for container execution and thus is safe to use on multi-tenant systems. In addition, it does not require recent Linux kernel functionalities (such as namespaces, cgroups and capabilities), making it easy to install on legacy systems.</p>"},{"location":"apps/framework/#analysis-levels","title":"Analysis levels","text":"<p>BIDS Apps decouple the individual level analysis (processing of independent subjects) from group-level analyses aggregating participants. For the analysis of individual subjects, Apps need to understand the BIDS structure of the input dataset, so that the required inputs for the designated subject are found. Apps are designed to easily process derivatives generated by the participant-level or other Apps. The overall workflow has an entry-point and an end-point responsible of setting-up the map-reduce tasks and the tear-down including organizing the outputs for its archiving, respectively. Each App may implement multiple map and reduce steps.</p> <p></p>"},{"location":"apps/framework/#a-unified-command-line-interface","title":"A unified command-line interface","text":"<p>To improve user experience and ability to integrate BIDS Apps into various computational platforms, each App follows a set of core command-line arguments:</p> <pre><code>$ &lt;entrypoint&gt; &lt;bids_dataset&gt; &lt;output_path&gt; &lt;analysis_level&gt;\n</code></pre> <p>For instance, to run fMRIPrep on a dataset located in <code>/data/bids_root</code> and write the outputs to <code>/data/bids_root/derivatives/</code>:</p> <pre><code>$ fmriprep /data/bids_root /data/bids_root/derivatives/ participant\n</code></pre> <p>In this case, we have selected to run the <code>participant</code> level (to process individual subjects). fMRIPrep does not have a <code>group</code> level, but other BIDS Apps may have. For instance, MRIQC generates group-level reports with the following command-line:</p> <pre><code>$ mriqc /data/bids_root /data/bids_root/derivatives/ group\n</code></pre>"},{"location":"apps/framework/#what-are-bids-derivatives","title":"What are BIDS Derivatives?","text":"<p>NiPreps generate derivatives of the original data, and they fulfill the BIDS specification for the results of Apps that are created for subsequent consumption by other BIDS-Apps. These derivatives must follow the BIDS Derivatives specification (draft). An example of BIDS Derivatives filesystem tree, generated with fMRIPrep 1.5: <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u251c\u2500\u2500 sub-02.html\n\u2502 \u251c\u2500\u2500 sub-02/\n\u2502 \u251c\u2500\u2500 sub-03.html\n\u2502 \u2514\u2500\u2500 sub-03/\n</code></pre></p>"},{"location":"apps/singularity/","title":"Executing with Singularity","text":"<p>Summary</p> <p>Here, we describe how to run NiPreps with Singularity containers. To illustrate the process, we will show the execution of fMRIPrep, but these guidelines extend to any other end-user NiPrep.</p>"},{"location":"apps/singularity/#preparing-a-singularity-image","title":"Preparing a Singularity image","text":"<p>Singularity version &gt;= 2.5: If the version of Singularity installed on your HPC (High-Performance Computing) system is modern enough you can create Singularity image directly on the system. This is as simple as:</p> <pre><code>$ singularity build /my_images/fmriprep-&lt;version&gt;.simg \\\n                    docker://nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>where <code>&lt;version&gt;</code> should be replaced with the desired version of fMRIPrep that you want to download.</p> <p>Singularity version &lt; 2.5: In this case, start with a machine (e.g., your personal computer) with Docker installed. Use docker2singularity to create a singularity image. You will need an active internet connection and some time:</p> <pre><code>$ docker run --privileged -t --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v D:\\host\\path\\where\\to\\output\\singularity\\image:/output \\\n    singularityware/docker2singularity \\\n    nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>Where <code>&lt;version&gt;</code> should be replaced with the desired version of fMRIPrep that you want to download.</p> <p>Beware of the back slashes, expected for Windows systems. For *nix users the command translates as follows: :</p> <pre><code>$ docker run --privileged -t --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v /absolute/path/to/output/folder:/output \\\n    singularityware/docker2singularity \\\n    nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>Transfer the resulting Singularity image to the HPC, for example, using <code>scp</code> or <code>rsync</code>:</p> <pre><code>$ scp nipreps_fmriprep*.img user@hcpserver.edu:/my_images\n</code></pre>"},{"location":"apps/singularity/#running-a-singularity-image","title":"Running a Singularity Image","text":"<p>If the data to be preprocessed is also on the HPC, you are ready to run the NiPrep:</p> <pre><code>$ singularity run --cleanenv fmriprep.simg \\\n    path/to/data/dir path/to/output/dir \\\n    participant \\\n    --participant-label label\n</code></pre>"},{"location":"apps/singularity/#handling-environment-variables","title":"Handling environment variables","text":"<p>Singularity by default exposes all environment variables from the host inside the container. Because of this, your host libraries (e.g., NiPype or a Python environment) could be accidentally used instead of the ones inside the container. To avoid such a situation, we strongly recommend using the <code>--cleanenv</code> argument in all scenarios. For example:</p> <pre><code>$ singularity run --cleanenv fmriprep.simg \\\n  /work/04168/asdf/lonestar/ $WORK/lonestar/output \\\n  participant \\\n  --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \\\n  --omp-nthreads 16\n</code></pre> <p>Alternatively, conflicts might be preempted and some problems mitigated by unsetting potentially problematic settings, such as the <code>PYTHONPATH</code> variable, before running:</p> <pre><code>$ unset PYTHONPATH; singularity run fmriprep.simg \\\n  /work/04168/asdf/lonestar/ $WORK/lonestar/output \\\n  participant \\\n  --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \\\n  --omp-nthreads 16\n</code></pre> <p>It is possible to define environment variables scoped within the container by using the <code>SINGULARITYENV_*</code> magic, in combination with <code>--cleanenv</code>. For example, we can set the FreeSurfer license variable (see fMRIPrep's documentation on this) as follows: :</p> <pre><code>$ export SINGULARITYENV_FS_LICENSE=$HOME/.freesurfer.txt\n$ singularity exec --cleanenv fmriprep.simg env | grep FS_LICENSE\nFS_LICENSE=/home/users/oesteban/.freesurfer.txt\n</code></pre> <p>As we can see, the export in the first line tells Singularity to set a corresponding environment variable of the same name after dropping the prefix <code>SINGULARITYENV_</code>.</p>"},{"location":"apps/singularity/#accessing-the-hosts-filesystem","title":"Accessing the host's filesystem","text":"<p>Depending on how Singularity is configured on your cluster it might or might not automatically bind (mount or expose) host's folders to the container (e.g., <code>/scratch</code>, or <code>$HOME</code>). This is particularly relevant because, if you can't run Singularity in privileged mode (which is almost certainly true in all the scenarios), Singularity containers are read only. This is to say that you won't be able to write anything unless Singularity can access the host's filesystem in write mode.</p> <p>By default, Singularity automatically binds (mounts) the user's home directory and a scratch directory. In addition, Singularity generally allows binding the necessary folders with the <code>-B &lt;host_folder&gt;:&lt;container_folder&gt;[:&lt;permissions&gt;]</code> Singularity argument. For example:</p> <pre><code>$ singularity run --cleanenv -B /work:/work fmriprep.simg \\\n  /work/my_dataset/ /work/my_dataset/derivatives/fmriprep \\\n  participant \\\n  --participant-label 387 --nthreads 16 \\\n  --omp-nthreads 16\n</code></pre> <p>Warning</p> <p>If your Singularity installation doesn't allow you to bind non-existent bind points, you'll get an error saying <code>WARNING: Skipping user bind, non existent bind point (directory) in container</code>. In this scenario, you can either try to bind things onto some other bind point you know it exists in the image or rebuild your singularity image with <code>docker2singularity</code> as follows:</p> <pre><code>$ docker run --privileged -ti --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n         -v $PWD:/output singularityware/docker2singularity \\\n         -m \"/gpfs /scratch /work /share /lscratch /opt/templateflow\"\n</code></pre> <p>In the example above, the following bind points are created: <code>/gpfs</code>, <code>/scratch</code>, <code>/work</code>, <code>/share</code>, <code>/opt/templateflow</code>.</p> <p>Important</p> <p>One great feature of containers is their confinement or isolation from the host system. Binding mount points breaks this principle, as the container has now access to create changes in the host. Therefore, it is generally recommended to use binding scarcely and granting very limited access to the minimum necessary resources. In other words, it is preferred to bind just one subdirectory of <code>$HOME</code> than the full <code>$HOME</code> directory of the host (see nipreps/fmriprep#1778 (comment)).</p> <p>Relevant aspects of the <code>$HOME</code> directory within the container: By default, Singularity will bind the user's <code>$HOME</code> directory in the host into the <code>/home/$USER</code> (or equivalent) in the container. Most of the times, it will also redefine the <code>$HOME</code> environment variable and update it to point to the corresponding mount point in <code>/home/$USER</code>. However, these defaults can be overwritten in your system. It is recommended to check your settings with your system's administrators. If your Singularity installation allows it, you can workaround the <code>$HOME</code> specification combining the bind mounts argument (<code>-B</code>) with the home overwrite argument (<code>--home</code>) as follows:</p> <pre><code>$ singularity run -B $HOME:/home/fmriprep --home /home/fmriprep \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#templateflow-and-singularity","title":"TemplateFlow and Singularity","text":"<p>TemplateFlow is a helper tool that allows neuroimaging workflows to programmatically access a repository of standard neuroimaging templates. In other words, TemplateFlow allows NiPreps to dynamically change the templates that are used, e.g., in the atlas-based brain extraction step or spatial normalization.</p> <p>Default settings in the Singularity image should get along with the Singularity installation of your system. However, deviations from the default configurations of your installation may break this compatibility. A particularly problematic case arises when the home directory is mounted in the container, but the <code>$HOME</code> environment variable is not correspondingly updated. Typically, you will experience errors like <code>OSError: [Errno 30] Read-only file system</code> or <code>FileNotFoundError: [Errno 2] No such file or directory: '/home/fmriprep/.cache'</code>.</p> <p>If it is not explicitly forbidden in your installation, the first attempt to overcome this issue is manually setting the <code>$HOME</code> directory as follows:</p> <pre><code>$ singularity run --home $HOME --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre> <p>If the user's home directory is not automatically bound, then the second step would include manually binding it as in the section above: :</p> <pre><code>$ singularity run -B $HOME:/home/fmriprep --home /home/fmriprep \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre> <p>Finally, if the <code>--home</code> argument cannot be used, you'll need to provide the container with writable filesystems where TemplateFlow's files can be downloaded. In addition, you will need to indicate fMRIPrep to update the default paths with the new mount points setting the <code>SINGULARITYENV_TEMPLATEFLOW_HOME</code> variable. :</p> <pre><code># Tell the NiPrep where TemplateFlow will place downloads\n$ export SINGULARITYENV_TEMPLATEFLOW_HOME=/opt/templateflow\n$ singularity run -B &lt;writable-path-on-host&gt;:/opt/templateflow \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#restricted-internet-access","title":"Restricted Internet access","text":"<p>We have identified several conditions in which running NiPreps might fail because of spotty or impossible access to Internet.</p> <p>If your compute node cannot have access to Internet, then you'll need to pull down from TemplateFlow all the resources that will be necessary ahead of run-time.</p> <p>If that is not the case (i.e., you should be able to hit HTTP/s endpoints), then you can try the following:</p> <ul> <li> <p><code>VerifiedHTTPSConnection ... Failed to establish a new connection: [Errno 110] Connection timed out</code>.   If you encounter an error like this, probably you'll need to set up an   http proxy exporting <code>SINGULARITYENV_http_proxy</code> (see nipreps/fmriprep#1778 (comment).   For example:</p> <pre><code>$ export SINGULARITYENV_https_proxy=http://&lt;ip or proxy name&gt;:&lt;port&gt;\n</code></pre> </li> <li> <p><code>requests.exceptions.SSLError: HTTPSConnectionPool ...</code>. In this case,   your container seems to be able to reach the Internet, but unable to use   SSL encription. There are two potential solutions to the issue. The   recommended one   is setting <code>REQUESTS_CA_BUNDLE</code> to the appropriate path, and/or binding   the appropriate filesystem:</p> <p><pre><code>$ export SINGULARITYENV_REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt\n$ singularity run -B &lt;path-to-certs-folder&gt;:/etc/ssl/certs \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>   Otherwise, some users have succeeded pre-fetching the necessary   templates onto the TemplateFlow directory to then bind the folder at   execution:</p> <pre><code>$ export TEMPLATEFLOW_HOME=/path/to/keep/templateflow\n$ python -m pip install -U templateflow  # Install the client\n$ python\n&gt;&gt;&gt; import templateflow.api\n&gt;&gt;&gt; templateflow.api.TF_S3_ROOT = 'http://templateflow.s3.amazonaws.com'\n&gt;&gt;&gt; api.get(\u2018MNI152NLin6Asym\u2019)\n</code></pre> </li> </ul> <p>Finally, run the singularity image binding the appropriate folder:</p> <pre><code>$ export SINGULARITYENV_TEMPLATEFLOW_HOME=/templateflow\n$ singularity run -B ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}:/templateflow \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#troubleshooting","title":"Troubleshooting","text":"<p>Setting up a functional execution framework with Singularity might be tricky in some HPC (high-performance computing) systems. Please make sure you have read the relevant documentation of Singularity, and checked all the defaults and configuration in your system. The next step is checking the environment and access to fMRIPrep resources, using <code>singularity shell</code>.</p> <ol> <li> <p>Check access to input data folder, and BIDS validity:       <pre><code>$ singularity shell -B path/to/data:/data fmriprep.simg\nSingularity fmriprep.simg:~&gt; ls /data\nCHANGES  README  dataset_description.json  participants.tsv  sub-01  sub-02  sub-03  sub-04  sub-05  sub-06  sub-07  sub-08  sub-09  sub-10  sub-11  sub-12  sub-13  sub-14  sub-15  sub-16  task-balloonanalogrisktask_bold.json\nSingularity fmriprep.simg:~&gt; bids-validator /data\n   1: [WARN] You should define 'SliceTiming' for this file. If you don't provide this information slice time correction will not be possible. (code: 13 - SLICE_TIMING_NOT_DEFINED)\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-04/func/sub-04_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ... and 38 more files having this issue (Use --verbose to see them all).\n  Please visit https://neurostars.org/search?q=SLICE_TIMING_NOT_DEFINED for existing conversations about this issue.\n</code></pre></p> </li> <li> <p>Check access to output data folder, and whether you have write    permissions       <pre><code>$ singularity shell -B path/to/data/derivatives/fmriprep-1.5.0:/out fmriprep.simg\nSingularity fmriprep.simg:~&gt; ls /out\nSingularity fmriprep.simg:~&gt; touch /out/test\nSingularity fmriprep.simg:~&gt; rm /out/test\n</code></pre></p> </li> <li> <p>Check access and permissions to <code>$HOME</code>:       <pre><code>$ singularity shell fmriprep.simg\nSingularity fmriprep.simg:~&gt; mkdir -p $HOME/.cache/testfolder\nSingularity fmriprep.simg:~&gt; rmdir $HOME/.cache/testfolder\n</code></pre></p> </li> <li> <p>Check TemplateFlow operation:       <pre><code>$ singularity shell -B path/to/templateflow:/templateflow fmriprep.simg\nSingularity fmriprep.simg:~&gt; echo ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}\n/home/users/oesteban/.cache/templateflow\nSingularity fmriprep.simg:~&gt; python -c \"from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])\"\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th0_dseg.nii.gz\n   304B [00:00, 1.28kB/s]\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th25_dseg.nii.gz\n   261B [00:00, 1.04kB/s]\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th50_dseg.nii.gz\n   219B [00:00, 867B/s]\n   ...\n</code></pre></p> </li> </ol>"},{"location":"apps/singularity/#running-singularity-on-a-slurm-system","title":"Running Singularity on a SLURM system","text":"<p>An example of <code>sbatch</code> script to run fMRIPrep on a SLURM system<sup>1</sup> is given below. The submission script will generate one task per subject using a job array. <pre><code>#!/bin/bash\n#\n#SBATCH -J fmriprep\n#SBATCH --time=48:00:00\n#SBATCH -n 1\n#SBATCH --cpus-per-task=16\n#SBATCH --mem-per-cpu=4G\n#SBATCH -p normal,mygroup  # Queue names you can submit to\n# Outputs ----------------------------------\n#SBATCH -o log/%x-%A-%a.out\n#SBATCH -e log/%x-%A-%a.err\n#SBATCH --mail-user=%u@domain.tld\n#SBATCH --mail-type=ALL\n# ------------------------------------------\n\nBIDS_DIR=\"$STUDY/data\"\nDERIVS_DIR=\"derivatives/fmriprep-20.2.2\"\nLOCAL_FREESURFER_DIR=\"$STUDY/data/derivatives/freesurfer-6.0.1\"\n\n# Prepare some writeable bind-mount points.\nTEMPLATEFLOW_HOST_HOME=$HOME/.cache/templateflow\nFMRIPREP_HOST_CACHE=$HOME/.cache/fmriprep\nmkdir -p ${TEMPLATEFLOW_HOST_HOME}\nmkdir -p ${FMRIPREP_HOST_CACHE}\n\n# Prepare derivatives folder\nmkdir -p ${BIDS_DIR}/${DERIVS_DIR}\n\n# Make sure FS_LICENSE is defined in the container.\nexport SINGULARITYENV_FS_LICENSE=$HOME/.freesurfer.txt\n\n# Designate a templateflow bind-mount point\nexport SINGULARITYENV_TEMPLATEFLOW_HOME=\"/templateflow\"\nSINGULARITY_CMD=\"singularity run --cleanenv -B $BIDS_DIR:/data -B ${TEMPLATEFLOW_HOST_HOME}:${SINGULARITYENV_TEMPLATEFLOW_HOME} -B $L_SCRATCH:/work -B ${LOCAL_FREESURFER_DIR}:/fsdir $STUDY/images/fmriprep_20.2.2.simg\"\n\n# Parse the participants.tsv file and extract one subject ID from the line corresponding to this SLURM task.\nsubject=$( sed -n -E \"$((${SLURM_ARRAY_TASK_ID} + 1))s/sub-(\\S*)\\&gt;.*/\\1/gp\" ${BIDS_DIR}/participants.tsv )\n\n# Remove IsRunning files from FreeSurfer\nfind ${LOCAL_FREESURFER_DIR}/sub-$subject/ -name \"*IsRunning*\" -type f -delete\n\n# Compose the command line\ncmd=\"${SINGULARITY_CMD} /data /data/${DERIVS_DIR} participant --participant-label $subject -w /work/ -vv --omp-nthreads 8 --nthreads 12 --mem_mb 30000 --output-spaces MNI152NLin2009cAsym:res-2 anat fsnative fsaverage5 --use-aroma --fs-subjects-dir /fsdir\"\n\n# Setup done, run the command\necho Running task ${SLURM_ARRAY_TASK_ID}\necho Commandline: $cmd\neval $cmd\nexitcode=$?\n\n# Output results to a table\necho \"sub-$subject   ${SLURM_ARRAY_TASK_ID}    $exitcode\" \\\n      &gt;&gt; ${SLURM_JOB_NAME}.${SLURM_ARRAY_JOB_ID}.tsv\necho Finished tasks ${SLURM_ARRAY_TASK_ID} with exit code $exitcode\nexit $exitcode\n</code></pre> Submission is then as easy as:</p> <pre><code>$ export STUDY=/path/to/some/folder\n$ sbatch --array=1-$(( $( wc -l $STUDY/data/participants.tsv | cut -f1 -d' ' ) - 1 )) fmriprep.slurm\n</code></pre> <ol> <li> <p>assuming that job arrays and Singularity are available\u00a0\u21a9</p> </li> </ol>"},{"location":"assets/ORN-Workshop/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#building-communities-around-reproducible-workflows","title":"Building communities around reproducible workflows","text":""},{"location":"assets/ORN-Workshop/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/ORN-Workshop/presentation/#chuv-lausanne-university-hospital","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#building-communities-around-reproducible-workflows_1","title":"Building communities around reproducible workflows","text":""},{"location":"assets/ORN-Workshop/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/ORN-Workshop/presentation/#chuv-lausanne-university-hospital_1","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":"<p>]</p> <p>???</p>"},{"location":"assets/ORN-Workshop/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/ORN-Workshop/presentation/#data-processing","title":"Data Processing","text":""},{"location":"assets/ORN-Workshop/presentation/#day-2-15h-cet","title":"(Day 2, 15h CET)","text":""},{"location":"assets/ORN-Workshop/presentation/#workflows","title":"Workflows","text":"<p>]</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/ORN-Workshop/presentation/#data-processing_1","title":"Data Processing","text":""},{"location":"assets/ORN-Workshop/presentation/#day-2-15h-cet_1","title":"(Day 2, 15h CET)","text":""},{"location":"assets/ORN-Workshop/presentation/#workflows_1","title":"Workflows","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/ORN-Workshop/presentation/#neuroimaging-is-now-mature","title":"Neuroimaging is now mature","text":"<ul> <li>many excellent tools available (from specialized to foundational)</li> <li>large toolboxes (AFNI, ANTs/ITK, FreeSurfer, FSL, Nilearn, SPM, etc.)</li> <li>workflow software (Nipype, Shellscripts, Nextflow, CWL)</li> <li> <p>container technology, CI/CD</p> </li> <li> <p>a wealth of prior knowledge (esp. about humans)</p> </li> <li> <p>LOTS of data acquired everyday</p> </li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#workflows-games-on","title":"Workflows - game's on!","text":"<ul> <li> <p>although many neuroimaging areas are still in search of methodological breakthroughs,</p> </li> <li> <p>challenges have moved on to the workflows:</p> </li> <li>workflows within traditional toolboxes - usually not flexible to adapt to new data</li> <li>BIDS and BIDS-Apps.</li> </ul> <p>???</p> <ul> <li>researchers have a large portfolio of image processing components readily available</li> <li>toolboxes with great support and active maintenance:</li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#new-questions-changing-the-focus","title":"New questions changing the focus:","text":""},{"location":"assets/ORN-Workshop/presentation/#-validity-does-the-workflow-actually-work-out","title":"- validity (does the workflow actually work out?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-transparency-is-it-a-black-box-how-precise-is-reporting","title":"- transparency (is it a black-box? how precise is reporting?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-vibration-how-each-tool-choice-parameters-affect-overall","title":"- vibration (how each tool choice &amp; parameters affect overall?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-throughput-how-much-datatime-can-it-possible-take","title":"- throughput (how much data/time can it possible take?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-robustness-can-i-use-it-on-diverse-studies","title":"- robustness (can I use it on diverse studies?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-evaluation-what-is-it-unique-about-the-workflow-wrt-existing-alternatives","title":"- evaluation (what is it unique about the workflow, w.r.t. existing alternatives?)","text":""},{"location":"assets/ORN-Workshop/presentation/#the-garden-of-forking-paths","title":"The garden of forking paths","text":"<p>(Botvinik-Nezer et al., 2020)</p> <p>Around 50% of teams used fMRIPrep'ed inputs.</p>"},{"location":"assets/ORN-Workshop/presentation/#the-fmriprep-story","title":"The fMRIPrep story","text":""},{"location":"assets/ORN-Workshop/presentation/#fmriprep-produces-analysis-ready-data-from-diverse-data","title":"fMRIPrep produces analysis-ready data from diverse data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> <li>robust against inhomogeneity of data across studies</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p>"},{"location":"assets/ORN-Workshop/presentation/#fmriprep-was-not-originally-envisioned-as-a-community-project","title":"fMRIPrep was not originally envisioned as a community project ...","text":"<p>(we just wanted a robust tool to automatically preprocess incoming data of OpenNeuro.org)</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#but-a-community-built-up-quickly-around-it","title":"... but a community built up quickly around it","text":"<p>--</p> <p>.pull-left[</p>"},{"location":"assets/ORN-Workshop/presentation/#why","title":"Why?","text":"<ul> <li> <p>Preprocessing of fMRI was in need for division of labor.</p> </li> <li> <p>Obsession with transparency made early-adopters confident of the recipes they were applying.</p> </li> <li> <p>Responsiveness to feedback. ]</p> </li> </ul> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Preprocessing is a time-consuming effort, requires expertise converging imaging foundations &amp; CS, typically addressed with legacy in-house pipelines.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p>"},{"location":"assets/ORN-Workshop/presentation/#key-aspect-credit-all-direct-contributors","title":"Key aspect: credit all direct contributors","text":"<p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#and-indirect-citation-boilerplate","title":".. and indirect: citation boilerplate.","text":""},{"location":"assets/ORN-Workshop/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p>"},{"location":"assets/ORN-Workshop/presentation/#the-dmriprep-story","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, some neuroimagers asked \"when a diffussion MRI fMRIPrep?\"</p>"},{"location":"assets/ORN-Workshop/presentation/#neurostarsorg","title":"NeuroStars.org","text":"<p>(please note this down)</p> <p>--</p> <p>Same situation in the field of diffusion MRI:</p>"},{"location":"assets/ORN-Workshop/presentation/#image-processing-possible-guidelines-for-the-standardization-clinical-applications-j-veraart","title":"Image Processing: Possible Guidelines for the Standardization &amp; Clinical Applications (J. Veraart)","text":"<p>(https://www.ismrm.org/19/program_files/MIS15.htm)</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#please-join","title":"Please join!","text":"<p>Joseph, M.; Pisner, D.; Richie-Halford, A.; Lerma-Usabiaga, G.; Keshavan, A.; Kent, JD.; Cieslak, M.; Poldrack, RA.; Rokem, A.; Esteban, O.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg_2","title":"www.nipreps.org","text":""},{"location":"assets/ORN-Workshop/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/ORN-Workshop/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/ORN-Workshop/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/ORN-Workshop/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/ORN-Workshop/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/ORN-Workshop/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/ORN-Workshop/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/ORN-Workshop/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/ORN-Workshop/presentation/#nibabies-fmriprep-babies","title":"NiBabies | fMRIPrep-babies","text":"<ul> <li>Mathias Goncalves</li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#nirodents-fmriprep-rodents","title":"NiRodents | fMRIPrep-rodents","text":"<ul> <li>Eilidh MacNicol</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p>"},{"location":"assets/ORN-Workshop/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p>"},{"location":"assets/ORN-Workshop/presentation/#the-nmind-story","title":"The NMiND story","text":"<p>NMiND = NeverMIND, this Neuroimaging Method Is Not Duplicated</p>"},{"location":"assets/ORN-Workshop/presentation/#pis-worried-about-methodological-duplicity","title":"PIs worried about methodological duplicity","text":"<p>M. Milham, D. Fair, T. Satterthwaite, S. Ghosh, R. Poldrack, etc.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#nminds-workgroups","title":"NMiND's workgroups","text":"<p>nosology group, coding standards &amp; patterns, sharing standards, testing standards, crediting contributors, funding strategy, benchmarking datasets.</p>"},{"location":"assets/ORN-Workshop/presentation/#nminds-nosology-goals","title":"NMiND's nosology goals","text":"<ul> <li>Consensus glossary of terms</li> <li>Landscape the portfolio of methodological solutions along several experimental and computational dimensions</li> <li>Organize and document a taxonomy along those dimensions</li> <li>Index existing software (from unit methods to workflows) in the taxonomy</li> </ul> <p>Please Join!</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/ORN-Workshop/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"assets/bhd2020/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"NiPreps | NeuroImaging PREProcessing toolS","text":""},{"location":"assets/bhd2020/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/bhd2020/presentation/#chuv-lausanne-university-hospital","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorgassetsbhd2020","title":"www.nipreps.org/assets/bhd2020","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools_1","title":"NiPreps | NeuroImaging PREProcessing toolS","text":""},{"location":"assets/bhd2020/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/bhd2020/presentation/#chuv-lausanne-university-hospital_1","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorgassetsbhd2020_1","title":"www.nipreps.org/assets/bhd2020","text":"<p>]</p> <p>???</p>"},{"location":"assets/bhd2020/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/bhd2020/presentation/#bhd2020","title":"BHD2020","text":""},{"location":"assets/bhd2020/presentation/#day-2-14h-cet","title":"(Day 2, 14h CET)","text":""},{"location":"assets/bhd2020/presentation/#nipreps","title":"NiPreps","text":"<p>]</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/bhd2020/presentation/#bhd2020_1","title":"BHD2020","text":""},{"location":"assets/bhd2020/presentation/#day-2-14h-cet_1","title":"(Day 2, 14h CET)","text":""},{"location":"assets/bhd2020/presentation/#nipreps_1","title":"NiPreps","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/bhd2020/presentation/#outlook","title":"Outlook","text":""},{"location":"assets/bhd2020/presentation/#1-understand-what-preprocessing-is-from-fmri","title":"1. Understand what preprocessing is - from fMRI","text":""},{"location":"assets/bhd2020/presentation/#2-the-fmriprep-experience","title":"2. The fMRIPrep experience","text":""},{"location":"assets/bhd2020/presentation/#3-the-dmriprep-experience","title":"3. The dMRIPrep experience","text":""},{"location":"assets/bhd2020/presentation/#4-importance-of-the-visual-reports","title":"4. Importance of the visual reports","text":""},{"location":"assets/bhd2020/presentation/#5-introducing-nipreps","title":"5. Introducing NiPreps","text":""},{"location":"assets/bhd2020/presentation/#6-open-forum-first-steps-and-contributing","title":"6. Open forum: first steps and contributing","text":""},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-nowadays","title":"The research workflow of functional MRI (nowadays)","text":"<p>(source: next slide)</p>"},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-2006","title":"The research workflow of functional MRI (2006)","text":"<p>(Strother, 2006; 10.1109/MEMB.2006.1607667)</p>"},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-ab","title":"The research workflow of functional MRI (a.B.<sup>*</sup>)","text":"<p>Adapted (Strother, 2006)</p> <p><sup>*</sup>a.B. = after BIDS (Brain Imaging Data Structure; Gorgolewski et al. (2016))</p>"},{"location":"assets/bhd2020/presentation/#neuroimaging-is-now-mature","title":"Neuroimaging is now mature","text":"<ul> <li>many excellent tools available (from specialized to foundational)</li> <li>large toolboxes (AFNI, ANTs/ITK, FreeSurfer, FSL, Nilearn, SPM, etc.)</li> <li>workflow software (Nipype, Shellscripts, Nextflow, CWL)</li> <li> <p>container technology, CI/CD</p> </li> <li> <p>a wealth of prior knowledge (esp. about humans)</p> </li> <li> <p>LOTS of data acquired everyday</p> </li> </ul>"},{"location":"assets/bhd2020/presentation/#bids-a-thrust-of-technology-driven-development","title":"BIDS - A thrust of technology-driven development","text":"<ul> <li> <p>A uniform and complete interface to data:</p> </li> <li> <p>Uniform: enables the workflow adapt to the data</p> </li> <li> <p>Complete: enables validation and minimizes human-intervention</p> </li> <li> <p>Extensible reproducibility:</p> </li> <li> <p>BIDS-Derivatives</p> </li> <li>BIDS-Apps (Gorgolewski et al., 2017)</li> </ul> <p>???</p> <ul> <li>researchers have a large portfolio of image processing components readily available</li> <li>toolboxes with great support and active maintenance:</li> </ul>"},{"location":"assets/bhd2020/presentation/#new-questions-changing-the-focus","title":"New questions changing the focus:","text":""},{"location":"assets/bhd2020/presentation/#-validity-does-the-workflow-actually-work-out","title":"- validity (does the workflow actually work out?)","text":""},{"location":"assets/bhd2020/presentation/#-transparency-is-it-a-black-box-how-precise-is-reporting","title":"- transparency (is it a black-box? how precise is reporting?)","text":""},{"location":"assets/bhd2020/presentation/#-vibration-how-each-tool-choice-parameters-affect-overall","title":"- vibration (how each tool choice &amp; parameters affect overall?)","text":""},{"location":"assets/bhd2020/presentation/#-throughput-how-much-datatime-can-it-possible-take","title":"- throughput (how much data/time can it possible take?)","text":""},{"location":"assets/bhd2020/presentation/#-robustness-can-i-use-it-on-diverse-studies","title":"- robustness (can I use it on diverse studies?)","text":""},{"location":"assets/bhd2020/presentation/#-evaluation-what-is-it-unique-about-the-workflow-wrt-existing-alternatives","title":"- evaluation (what is it unique about the workflow, w.r.t. existing alternatives?)","text":""},{"location":"assets/bhd2020/presentation/#the-garden-of-forking-paths","title":"The garden of forking paths","text":"<p>(Botvinik-Nezer et al., 2020)</p> <p>Around 50% of teams used fMRIPrep'ed inputs.</p>"},{"location":"assets/bhd2020/presentation/#the-fmriprep-story","title":"The fMRIPrep story","text":""},{"location":"assets/bhd2020/presentation/#fmriprep-produces-analysis-ready-data-from-diverse-data","title":"fMRIPrep produces analysis-ready data from diverse data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> <li>robust against inhomogeneity of data across studies</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p>"},{"location":"assets/bhd2020/presentation/#fmriprep-was-not-originally-envisioned-as-a-community-project","title":"fMRIPrep was not originally envisioned as a community project ...","text":"<p>(we just wanted a robust tool to automatically preprocess incoming data of OpenNeuro.org)</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#but-a-community-built-up-quickly-around-it","title":"... but a community built up quickly around it","text":"<p>--</p> <p>.pull-left[</p>"},{"location":"assets/bhd2020/presentation/#why","title":"Why?","text":"<ul> <li> <p>Preprocessing of fMRI was in need for division of labor.</p> </li> <li> <p>Obsession with transparency made early-adopters confident of the recipes they were applying.</p> </li> <li> <p>Responsiveness to feedback. ]</p> </li> </ul> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Preprocessing is a time-consuming effort, requires expertise converging imaging foundations &amp; CS, typically addressed with legacy in-house pipelines.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p>"},{"location":"assets/bhd2020/presentation/#key-aspect-credit-all-direct-contributors","title":"Key aspect: credit all direct contributors","text":"<p>--</p>"},{"location":"assets/bhd2020/presentation/#and-indirect-citation-boilerplate","title":".. and indirect: citation boilerplate.","text":""},{"location":"assets/bhd2020/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p> <p> </p> <p> (Esteban et al., 2019) </p>"},{"location":"assets/bhd2020/presentation/#the-dmriprep-story","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, Dr. A. Keshavan asked \"when a dMRIPrep?\"</p>"},{"location":"assets/bhd2020/presentation/#neurostarsorg","title":"NeuroStars.org","text":"<p>(please note this down)</p>"},{"location":"assets/bhd2020/presentation/#the-dmriprep-story_1","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, Dr. A. Keshavan asked \"when a dMRIPrep?\"</p> <p> </p> <p>Image Processing: Possible Guidelines for the Standardization &amp; Clinical Applications</p> <p>(Veraart, 2019)</p>"},{"location":"assets/bhd2020/presentation/#please-join","title":"Please join!","text":"<p>Joseph, M.; Pisner, D.; Richie-Halford, A.; Lerma-Usabiaga, G.; Keshavan, A.; Kent, JD.; Veraart, J.; Cieslak, M.; Poldrack, RA.; Rokem, A.; Esteban, O.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#understanding-what-preprocessing-is-with-visual-reports","title":"Understanding what preprocessing is with visual reports","text":"<p>]</p>"},{"location":"assets/bhd2020/presentation/#the-individual-report","title":"The individual report","text":"<p>???</p> <p>Let's walk through one example of report. Reports have several sections, starting with a summary indicating the particularities of this dataset and workflow choices made based on the input data.</p> <p>The anatomical section follows with several visualizations to assess the anatomical processing steps mentioned before, spatial normalization to template spaces (the flickering panel helps assess alignment) and finally surface reconstruction.</p> <p>Then, all functional runs are concatenated, and all show the same structure. After an initial summary of this particular run, the alignment to the same subject's anatomical image is presented, with contours of the white and pial surfaces as cues. Next panel shows the brain mask and ROIs utilized by the CompCor denoising. For each run we then find some visualizations to assess the generated confounding signals.</p> <p>After all functional runs are presented, the About section keeps information to aid reproducibility of results, such as the software's version, or the exact command line run.</p> <p>The boilerplate is found next, with a text version shown by default and tabs to convert to Markdown and LaTeX.</p> <p>Reports conclude with a list of encountered errors (if any).</p>"},{"location":"assets/bhd2020/presentation/#reports-are-a-crucial-element-to-ensure-transparency","title":"Reports are a crucial element to ensure transparency","text":"<p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p>.distribute[ fMRIPrep generates one participant-wide report after execution.</p> <p>Reports describe the data as found, and the steps applied (providing .blue[visual support to look inside the box]):</p> <ol> <li> <p>show researchers their data;</p> </li> <li> <p>show how fMRIPrep interpreted the data (describing the actual preprocessing steps);</p> </li> <li> <p>quality control of results, facilitating early error detection. ] ]</p> </li> </ol> <p>???</p> <p>Therefore, reports have become a fundamental feature of fMRIPrep because they not only allow assessing the quality of the processing, but also provide an insight about the logic supporting such processing.</p> <p>In other words, reports help respond to the what was done and the why was it done in addition to the how well it did.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":""},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools_2","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/bhd2020/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/bhd2020/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/bhd2020/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/bhd2020/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/bhd2020/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/bhd2020/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/bhd2020/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/bhd2020/presentation/#nibabies-fmriprep-babies","title":"NiBabies | fMRIPrep-babies","text":"<ul> <li>Mathias Goncalves</li> </ul>"},{"location":"assets/bhd2020/presentation/#nirodents-fmriprep-rodents","title":"NiRodents | fMRIPrep-rodents","text":"<ul> <li>Eilidh MacNicol</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p>"},{"location":"assets/bhd2020/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#where-to-start","title":"Where to start?","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":""},{"location":"assets/bhd2020/presentation/#githubcomnipreps","title":"github.com/nipreps","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/bhd2020/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"assets/torw2020/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#building-next-generation-preprocessing-pipelines","title":"Building next-generation preprocessing pipelines:","text":""},{"location":"assets/torw2020/presentation/#the-fmriprep-experience","title":"the fMRIPrep experience","text":""},{"location":"assets/torw2020/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/torw2020/presentation/#center-for-reproducible-neuroscience","title":"Center for Reproducible Neuroscience","text":""},{"location":"assets/torw2020/presentation/#stanford-university","title":"Stanford University","text":""},{"location":"assets/torw2020/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#building-next-generation-preprocessing-pipelines_1","title":"Building next-generation preprocessing pipelines:","text":""},{"location":"assets/torw2020/presentation/#the-fmriprep-experience_1","title":"the fMRIPrep experience","text":""},{"location":"assets/torw2020/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/torw2020/presentation/#center-for-reproducible-neuroscience_1","title":"Center for Reproducible Neuroscience","text":""},{"location":"assets/torw2020/presentation/#stanford-university_1","title":"Stanford University","text":""},{"location":"assets/torw2020/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":"<p>]</p> <p>???</p>"},{"location":"assets/torw2020/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/torw2020/presentation/#torw2020","title":"TORW2020","text":""},{"location":"assets/torw2020/presentation/#talk-12","title":"Talk 12","text":""},{"location":"assets/torw2020/presentation/#nipreps","title":"NiPreps","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#introducing-fmriprep","title":"Introducing fMRIPrep","text":"<p>]</p> <p>???</p> <p>Let's begin with some of the history behind fMRIPrep.</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/torw2020/presentation/#torw2020_1","title":"TORW2020","text":""},{"location":"assets/torw2020/presentation/#talk-12_1","title":"Talk 12","text":""},{"location":"assets/torw2020/presentation/#nipreps_1","title":"NiPreps","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/torw2020/presentation/#fmriprep-produces-analysis-ready-data-from-acquired-fmri-data","title":"fMRIPrep produces analysis-ready data from acquired (fMRI) data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#fmriprep-bundles-many-tools-afni-fsl-freesurfer-nilearn-etc","title":"fMRIPrep bundles many tools (AFNI, FSL, FreeSurfer, Nilearn, etc.)","text":"<ul> <li>(do not reinvent the wheel)</li> </ul> <p>???</p> <p>Finally, fMRIPrep sits on top of giants' shoulders: AFNI, FSL, FreeSurfer, Nilearn, etc. all implement methods very well backed-up and are thoroughly tested on their own.</p>"},{"location":"assets/torw2020/presentation/#we-started-fmriprep-in-february-2016","title":"We started fMRIPrep in February 2016","text":""},{"location":"assets/torw2020/presentation/#objectives","title":"Objectives:","text":"<ul> <li>Develop an fMRI preprocessing tool enforcing BIDS for the inputs</li> <li>Automatically executable within OpenNeuro</li> </ul>"},{"location":"assets/torw2020/presentation/#initially-inspired-by-hcp-pipelines","title":"Initially inspired by HCP Pipelines","text":"<ul> <li>Problem: robustness vs. the wide variability of inputs</li> </ul> <p>???</p> <p>We began working on fMRIPrep back in 2016 with much more humble expectations: - We needed to develop an fMRI preprocessing tool leveraging BIDS - smart enough to adapt the workflow for the input dataset, - and the tool should be executable in OpenNeuro without human intervention.</p> <p>Please note that at the time, the BIDS-Apps specification didn't exist yet.</p> <p>We started out with an eye on HCP Pipelines, and soon identified that datasets in OpenNeuro varied extremely in terms of acquisition protocols and imaging parameters, which is definitely not a problem for HCP Pipelines, which has very specific requirements for the inputs.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-adoption-and-popularization-brought-new-challenges","title":"fMRIPrep adoption and popularization brought new challenges","text":"<p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>With the fast adoption and popularization of fMRIPrep, new challenges surfaced.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#transparency-was-addressed-with","title":"Transparency was addressed with:","text":"<ul> <li>the individual reports;</li> <li>the thorough documentation; and</li> <li>the citation boilerplate. ]</li> </ul> <p>???</p> <p>We realized that transparency is indeed a very hard problem. The first leg of our solution was the creation of a solid report system. fMRIPrep generates one individual report per participant, containing information not just to quality control the results, but also to understand the processing flow.</p> <p>We also strived for a comprehensive, thorough documentation.</p> <p>Finally, the so-called citation boilerplate appended to the individual reports describe the actual workflow that has been run, noting all the software that was applied including their versions and references.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#run-to-run-repeatability-is-an-open-issue","title":"Run-to-run repeatability is an open issue:","text":"<ul> <li>computational precautions (e.g., unpredictable float truncation/rounding)</li> <li>keep track of all random seeds (version +20.1) ]</li> </ul> <p>???</p> <p>Reproducibility in terms of run-to-run repeatability of results become as a more apparent problem, and we are always trying to minimize the vibration caused by computational factors, software versions, etc.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#overwhelming-feedback","title":"Overwhelming feedback:","text":"<ul> <li>massive amounts of bug reports, questioning the robustness</li> <li>organic emergence of fMRIPrep enthusiasts (thanks to E. DuPre, JD. Kent) ]</li> </ul> <p>???</p> <p>We always maintained close attention to all the feedback channels. At some point we were washed over with bug reports that we needed to address. We also started to doubt the robustness against the variability of inputs, and set a thorough stress-test plan using data from OpenNeuro (reported in our Nat Meth paper). Among this feedback flooding, some external friends started to emerge and lent their shoulders in answering questions, fixing bugs, etc.</p> <p>In particular, I want to thank Elizabeth DuPre (McGill) and James Kent (Univ. of Iowa) for being the earliest adopters and contributors.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-stable-today-although-unfinished","title":"fMRIPrep is stable today, although unfinished","text":"<p>(Esteban et al., 2019)</p> <p>???</p> <p>These developments resulted in the following default processing workflow.</p> <p>At the highest level, anatomical preprocessing (left-hand block) and functional preprocessing (right-hand block) can be clearly identified as the largest workflow units.</p> <p>fMRIPrep combines all the anatomical images at the input in one anatomical reference, removes the intensity non-uniformity, delineates brain tissues, reconstructs surfaces, spatially normalizes the anatomical reference to one or more standard spaces.</p> <p>On the functional pathway, a reference is calculated for further processes, then head-motion parameters are estimated (please note head-motion is accounted for in the last resampling step, in combination with other transforms), slice-timing correction is applied if requested.</p> <p>Then, susceptibility distortion is estimated, if sufficient information (in terms of acquisition and metadata) is found in the BIDS structure.</p> <p>Finally, data are mapped to the same individual's anatomical reference and outputs in the several output spaces requested are generated, along with a file gathering time-series of nuisance signals.</p>"},{"location":"assets/torw2020/presentation/#the-individual-report","title":"The individual report","text":"<p>???</p> <p>Let's walk through one example of report. Reports have several sections, starting with a summary indicating the particularities of this dataset and workflow choices made based on the input data.</p> <p>The anatomical section follows with several visualizations to assess the anatomical processing steps mentioned before, spatial normalization to template spaces (the flickering panel helps assess alignment) and finally surface reconstruction.</p> <p>Then, all functional runs are concatenated, and all show the same structure. After an initial summary of this particular run, the alignment to the same subject's anatomical image is presented, with contours of the white and pial surfaces as cues. Next panel shows the brain mask and ROIs utilized by the CompCor denoising. For each run we then find some visualizations to assess the generated confounding signals.</p> <p>After all functional runs are presented, the About section keeps information to aid reproducibility of results, such as the software's version, or the exact command line run.</p> <p>The boilerplate is found next, with a text version shown by default and tabs to convert to Markdown and LaTeX.</p> <p>Reports conclude with a list of encountered errors (if any).</p>"},{"location":"assets/torw2020/presentation/#reports-are-a-crucial-element-to-ensure-transparency","title":"Reports are a crucial element to ensure transparency","text":"<p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p>.distribute[ fMRIPrep generates one participant-wide report after execution.</p> <p>Reports describe the data as found, and the steps applied (providing .blue[visual support to look inside the box]):</p> <ol> <li> <p>show researchers their data;</p> </li> <li> <p>show how fMRIPrep interpreted the data (describing the actual preprocessing steps);</p> </li> <li> <p>quality control of results, facilitating early error detection. ] ]</p> </li> </ol> <p>???</p> <p>Therefore, reports have become a fundamental feature of fMRIPrep because they not only allow assessing the quality of the processing, but also provide an insight about the logic supporting such processing.</p> <p>In other words, reports help respond to the what was done and the why was it done in addition to the how well it did.</p>"},{"location":"assets/torw2020/presentation/#documentation-as-a-second-leg-of-transparency-fmripreporg","title":"Documentation as a second leg of transparency (fmriprep.org)","text":"<ul> <li> <p>Hackathons &amp; docu-sprints</p> </li> <li> <p>the CompCor documentation example</p> </li> </ul> <p> </p> <p>.large[fmriprep.org]</p> <p>???</p> <p>We promptly identified the need for a very comprehensive documentation. The website at fmriprep.org covers a substantial area of how the tool works under the hood and how to best operate it.</p> <p>The documentation turned out to be a great ice breaker for contributors, who have pushed forward fundamental sections of it.</p> <p>Most of the largest increments in documentation are the result of discussions in hackathons, docusprints, neurostars, github, etc. A hallmark example was pull request 1877 by Karolina Finc, who gathered together a massive amount of knowledge from many contributors. Now this is up and open in our documentation website.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-more-of-a-community-driven-project-every-day","title":"fMRIPrep is more of a community-driven project every day","text":"<ul> <li> <p>Bug-fixes: we ensured that open feedback channels were attended (GitHub, NeuroStars, mailing list, etc.);</p> </li> <li> <p>users began also proposing new features (some including code!);</p> </li> <li> <p>with NiPreps we are working towards handling the project over to the community.</p> </li> </ul> <p>???</p> <p>To ensure the future sustainability of the project (what some developers call Bus factor), we are transitioning the tool to NiPreps, transferring the large community nurtured over the past four years with it.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#how-does-fmriprep-compensate-its-contributors","title":"How does fMRIPrep compensate its contributors?","text":"<ul> <li>Contributors are invited to coauthor relevant publications about fMRIPrep.</li> <li>Anyone who helps with documentation, code or relevant discussions is a contributor.</li> </ul> <p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>In return, beyond the rewards of being part of an open source project, fMRIPrep gives some scientific credit back in the form of publications.</p> <ul> <li>All contributors are invited to coauthor these publications.</li> <li>Anything that helps the project is considered a sufficient contribution.</li> </ul>"},{"location":"assets/torw2020/presentation/#lessons-learned","title":"Lessons learned","text":""},{"location":"assets/torw2020/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#wwwniprepsorg_2","title":"www.nipreps.org","text":""},{"location":"assets/torw2020/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/torw2020/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/torw2020/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/torw2020/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/torw2020/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/torw2020/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/torw2020/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/torw2020/presentation/#sdcflows-as-integrated-in-fmriprep","title":"SDCFlows, as integrated in fMRIPrep","text":"<p>.left-column3[</p> <p> </p> <p>]</p> <p>.right-column3[ * Hierarchy of SDC methods:   1. PE-Polar   2. Fieldmap   3. Fieldmap-less</p> <ul> <li>Arguments:</li> <li><code>--use-syn-sdc</code></li> <li><code>--force-syn</code></li> <li> <p><code>--ignore fieldmaps</code></p> </li> <li> <p>REQUIRES (opts. 1 or 2): setting the <code>IntendedFor</code> metadata field of fieldmaps. ]</p> </li> </ul> <p>???</p> <p>With SDCFlows, fMRIPrep implements a rather sophisticated pipeline for the estimation of susceptibility distortions.</p> <p>Depending on whether the input dataset contains EPI images with opposed phase encoding polarities (the so-called PE-Polar correction), fieldmaps (as Gradient Recalled Echo sequences) or the fieldmap-less estimation is requested,</p> <p>then SDCFlows establishes a hierarchy of corrections.</p> <p>After correction, we are interested in assessing that low-frequency distortions have been accounted for and that high-frequency (with extreme regions suffering severe drop-outs) are not excessively present.</p> <p>.pull-left[</p> <p> </p> <p>] .pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>sMRIPrep corresponds to the split of the anatomical preprocessing workflow originally proposed with fMRIPrep.</p> <p>With the support of TemplateFlow, the tool now supports spatial normalization to one or more templates found in the TemplateFlow Archive.</p> <p>It also supports the use of custom templates, whenever they are correctly installed in the templateflow's cache folder.</p> <p></p> <p> </p> <p> </p> <p> </p> <p>???</p> <p>dMRIPrep and fMRIPrep are, of course the tip of the iceberg.</p> <p>dMRIPrep is still in an alpha state, steadily progressing through the path fMRIPrep has delineated for NiPreps.</p> <p>Hopefully, at this point of the talk fMRIPrep doesn't need further description.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#other-components-of-nipreps","title":"Other components of NiPreps","text":"<p>]</p> <p>???</p> <p>Some additional components of NiPreps were never part of fMRIPrep's codebase, or they have been started recently.</p> <p> </p> <p></p> <p> </p> <p></p> <p> </p> <p>???</p> <p>Such is the case of the quality control tools.</p> <p>MRIQC produces visual reports for the efficient screening of acquired (meaning, unprocessed) data - in particular anatomical and functional MRI of the human brain.</p> <p>CrowdMRI is an internet service where anonimized quality control metrics are uploaded automatically as they are computed by MRIQC.</p> <p>The endgoal is to gather enough data to describe the normative distribution of these metrics across image parameters and scanning devices and sites.</p> <p>Finally, MRIQCnets encloses several machine learning projects regarding the quality of acquired images.</p>"},{"location":"assets/torw2020/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/torw2020/presentation/#nibabies","title":"NiBabies","text":"<ul> <li>Recently started, covering infant MRI brain-extraction for now (Mathias Goncalves)</li> </ul>"},{"location":"assets/torw2020/presentation/#nirodents","title":"NiRodents","text":"<ul> <li>Recently started, covering rodent MRI brain-extraction for now (Eilidh MacNicol)</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#future-lines","title":"Future lines","text":"<ul> <li> <p>fMRIPrep-babies</p> </li> <li> <p>fMRIPrep-rodents</p> </li> <li> <p>MolPrep / PETPrep ?</p> </li> </ul> <p>???</p> <p>In a mid-term future, both NiBabies and NiRodents should allow the extension of fMRIPrep to these new two idiosyncratic data families.</p> <p>In additions, plans for a molecular imaging or PET preprocessing NiPrep are being designed.</p>"},{"location":"assets/torw2020/presentation/#conclusion","title":"Conclusion","text":""},{"location":"assets/torw2020/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#open-phd-student-position","title":"Open PhD student position!","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/torw2020/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"community/","title":"Join the NiPreps Community","text":"<p>One of the pillars of fMRIPrep, the seed project for NiPreps, has been nurturing an open-source community. Building Welcoming Communities is crucial for open-source software because of several reasons:</p> <ul> <li> <p>Engaging users and contributors (in a very liberal sense, not just with code)     helps establish a development road-map:</p> <ul> <li>In the case of fMRIPrep, many users have reported bugs via our issue     tracker and Neurostars.org.     Even though testing is one of the primary focuses for fMRIPrep, without these     bug-report contributions the tool would have never reached the dependability level     it requires to serve its purpose.</li> <li>Users identify and propose new features, often illuminating shady areas the     most involved developers did not find time or the right context to explore.</li> </ul> </li> <li> <p>The community exposes the software and also increases the externality of the software.     The neuroimaging discussion supported by Neurostars.org     has been a key factor for the adoption of fMRIPrep.</p> </li> <li> <p>Users always give back, and it is not uncommon to see elaborate responses     to bug-reports and questions about fMRIPrep on Neurostars.org     by users who had similar questions previously.</p> </li> </ul> <p>Because of the scientific purpose of NiPreps, there is one more fundamental reason to grow a (scientific) community around the tools: rigor/scrutiny. As one reviews a few of the most discussed pull-requests to fMRIPrep, very soon they realize that we don't just need to get the code right. We strive for integrating high-quality code, but even more importantly, that code must get the scientific method it implements right. This is particularly difficult because in most of the cases there aren't test oracles (in software engineering terms) or gold-standards (in scientific terms) to efficiently evaluate the validity of new features (even to exercise a minuscule area of the domain of inputs). The redundancy of expert eyes looking at our code has only helped make it better.</p>"},{"location":"community/#current-members-of-the-github-organization","title":"Current members of the GitHub organization","text":"<p>A total of 100 neuroimagers have already joined us. Becoming a member will give you access to additional forums for discussion,  subscribing notifications for events and meetings, etc. You can request you are added to the organization by creating a new issue here.</p> <p> </p>"},{"location":"community/CODE_OF_CONDUCT/","title":"NiPreps Code of Conduct","text":""},{"location":"community/CODE_OF_CONDUCT/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>"},{"location":"community/CODE_OF_CONDUCT/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or   advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic   address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>"},{"location":"community/CODE_OF_CONDUCT/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>"},{"location":"community/CODE_OF_CONDUCT/#scope","title":"Scope","text":"<p>This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>"},{"location":"community/CODE_OF_CONDUCT/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Oscar Esteban at oesteban@stanford.edu or Chris Markiewicz at markiewicz@stanford.edu, two members of the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>"},{"location":"community/CODE_OF_CONDUCT/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>"},{"location":"community/CONTRIBUTING/","title":"Contributing Guidelines","text":"<p>Welcome to the NiPreps project! We're excited you're here and want to contribute.</p> <p>Imposter's syndrome disclaimer</p> <p>Imposter's syndrome disclaimer<sup>1</sup>: We want your help. No, really.</p> <p>There may be a little voice inside your head that is telling you that you're not ready to be an open-source contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer a project like this one?</p> <p>We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open-source. Contributing to open-source projects is a fantastic way to advance one's coding skills. Writing perfect code isn't the measure of a good developer (that would disqualify all of us!); it's trying to create something, making mistakes, and learning from those mistakes. That's how we all improve, and we are happy to help others learn.</p> <p>Being an open-source contributor doesn't just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.</p>"},{"location":"community/CONTRIBUTING/#driving-principles","title":"Driving principles","text":"<p>NiPreps are built around three overarching principles:</p> <ol> <li>Robustness - The pipeline adapts the preprocessing steps depending on    the input dataset and should provide results as good as possible    independently of scanner make, scanning parameters or presence of additional    correction scans (such as fieldmaps).</li> <li>Ease of use - Thanks to dependence on the BIDS standard, manual    parameter input is reduced to a minimum, allowing the pipeline to run in an    automatic fashion.</li> <li>\"Glass box\" philosophy - Automation should not mean that one should not    visually inspect the results or understand the methods.    Thus, NiPreps provides visual reports for each subject, detailing the    accuracy of the most important processing steps.    This, combined with the documentation, can help researchers to understand    the process and decide which subjects should be kept for the group level    analysis.</li> </ol> <p>These principles distill some design and organizational foundations:</p> <ol> <li>NiPreps only and fully support BIDS and BIDS-Derivatives for the input and output data.</li> <li>NiPreps are packaged as a fully-compliant BIDS-Apps, not just in its user interface, but also in the continuous integration, testing, and delivery.</li> <li>The scope of NiPreps is strictly limited to preprocessing tasks.</li> <li>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.</li> <li>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).</li> <li>NiPreps are community-driven, and contributors (in any sense) always get credited with authorship within relevant publications.</li> <li>NiPreps are modular, reliant on widely-used tools such as AFNI, ANTs, FreeSurfer, FSL, NiLearn, or DIPY [7-12] and extensible via plug-ins.</li> </ol>"},{"location":"community/CONTRIBUTING/#practical-guide-to-submitting-your-contribution","title":"Practical guide to submitting your contribution","text":"<p>These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an issue!</p> <p>Before you start, you'll need to set up a free GitHub account and sign in. Here are some instructions.</p> <p>Already know what you're looking for in this guide? Jump to the following sections:</p> <ul> <li>Joining the conversation</li> <li>Contributing through Github</li> <li>Understanding issues</li> <li>Making a change</li> <li>Structuring contributions</li> <li>Licensing</li> <li>Recognizing contributors</li> </ul>"},{"location":"community/CONTRIBUTING/#joining-the-conversation","title":"Joining the conversation","text":"<p>NiPreps is maintained by a growing group of enthusiastic developers\u2014 and we're excited to have you join! Most of our discussions will take place on open issues.</p> <p>We also encourage users to report any difficulties they encounter on NeuroStars, a community platform for discussing neuroimaging.</p> <p>We actively monitor both spaces and look forward to hearing from you in either venue!</p>"},{"location":"community/CONTRIBUTING/#contributing-through-github","title":"Contributing through GitHub","text":"<p>git is a really useful tool for version control. GitHub sits on top of git and supports collaborative and distributed working.</p> <p>If you're not yet familiar with <code>git</code>, there are lots of great resources to help you git started! Some of our favorites include the git Handbook and the Software Carpentry introduction to git.</p> <p>On GitHub, You'll use Markdown to chat in issues and pull requests. You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting. For example, you could write words as bold (<code>**bold**</code>), or in italics (<code>*italics*</code>), or as a link (<code>[link](https://youtu.be/dQw4w9WgXcQ)</code>) to another webpage.</p> <p>GitHub has a really helpful page for getting started with writing and formatting Markdown on GitHub.</p>"},{"location":"community/CONTRIBUTING/#understanding-issues","title":"Understanding issues","text":"<p>Every project on GitHub uses issues slightly differently.</p> <p>The following outlines how the NiPreps developers think about these tools.</p> <ul> <li> <p>Issues are individual pieces of work that need to be completed to move the project forward. A general guideline: if you find yourself tempted to write a great big issue that is difficult to describe as one unit of work, please consider splitting it into two or more issues.</p> <p>Issues are assigned labels which explain how they relate to the overall project's goals and immediate next steps.</p> </li> </ul>"},{"location":"community/CONTRIBUTING/#issue-labels","title":"Issue Labels","text":"<p>The current list of issue labels are here and include:</p> <ul> <li> <p> These issues contain a task that is amenable to new contributors because it doesn't entail a steep learning curve.</p> <p>If you feel that you can contribute to one of these issues, we especially encourage you to do so!</p> </li> <li> <p> These issues point to problems in the project.</p> <p>If you find new a bug, please give as much detail as possible in your issue, including steps to recreate the error. If you experience the same bug as one already listed, please add any additional information that you have as a comment.</p> </li> <li> <p> These issues are asking for new features and improvements to be considered by the project.</p> <p>Please try to make sure that your requested feature is distinct from any others that have already been requested or implemented. If you find one that's similar but there are subtle differences, please reference the other request in your issue.</p> </li> </ul> <p>In order to define priorities and directions in the development roadmap, we have two sets of special labels:</p> Label Description Estimation of the downstream impact the proposed feature/bugfix will have. Estimation of effort required to implement the requested feature or fix the reported bug. <p>One way to understand these labels is to consider how they would apply to an imaginary issue. For example, if -- after a release -- a bug is identified that re-introduces a previously solved issue (i.e., its regresses the code outputs to some undesired behavior), we might assign it the following labels:  . Its development priority would then be \"high\", since it is a low-effort, high-impact change.</p> <p>Long-term goals may be labelled as a combination of:  and   or  since they will have a high-impact on the code-base, but require a medium or high amount of effort. Of note, issues with the labels:   or  are less likely to be addressed because they are less likely to impact the code-base, or because they will require a very high activation energy to do so.</p>"},{"location":"community/CONTRIBUTING/#making-a-change","title":"Making a change","text":"<p>We appreciate all contributions to NiPreps, but those accepted fastest will follow a workflow similar to the following:</p> <ol> <li> <p>Comment on an existing issue or open a new issue referencing your addition.   This allows other members of the NiPreps development team to confirm that you aren't   overlapping with work that's currently underway and that everyone is on the same page   with the goal of the work you're going to carry out. This blog is a nice explanation of why putting this work in up front   is so useful to everyone involved.</p> </li> <li> <p>Fork the particular NiPrep repository (e.g., fMRIPrep)   with your GitHub user.   This is now your own unique copy of that particular NiPreps component.   Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!</p> </li> <li> <p>Clone your forked NiPreps repository to your machine/computer.   While you can edit files directly on github, sometimes the changes   you want to make will be complex and you will want to use a text editor   that you have installed on your local machine/computer.   (One great text editor is vscode).   In order to work on the code locally, you must clone your forked repository.   To keep up with changes in the NiPreps repository,   add the \"upstream\" NiPreps repository as a remote   to your locally cloned repository.     <pre><code>git remote add upstream https://github.com/nipreps/fmriprep.git\n</code></pre>     Make sure to keep your fork up to date with the upstream repository.     For example, to update your master branch on your local cloned repository:       <pre><code>git fetch upstream\ngit checkout master\ngit merge upstream/master\n</code></pre></p> </li> <li> <p>Create a new branch to develop and maintain the proposed code changes.   For example:     <pre><code>git fetch upstream  # Always start with an updated upstream\ngit checkout -b fix/bug-1222 upstream/master\n</code></pre>     Please consider using appropriate branch names as those listed below, and mind that some of them     are special (e.g., <code>doc/</code> and <code>docs/</code>):</p> <ul> <li><code>fix/&lt;some-identifier&gt;</code>: for bugfixes</li> <li><code>enh/&lt;feature-name&gt;</code>: for new features</li> <li><code>doc/&lt;some-identifier&gt;</code>: for documentation improvements.     You should name all your documentation branches with the prefix <code>doc/</code> or <code>docs/</code>     as that will preempt triggering the full battery of continuous integration tests.</li> </ul> </li> <li> <p>Make the changes you've discussed, following the NiPreps coding style guide.   Try to keep the changes focused: it is generally easy to review changes that address one feature or bug at a time.   It can also be helpful to test your changes locally,   using a NiPreps development environment.   Once you are satisfied with your local changes, add/commit/push them   to the branch on your forked repository.</p> </li> <li> <p>Submit a pull request.    A member of the development team will review your changes to confirm    that they can be merged into the main code base.    Pull request titles should begin with a descriptive prefix    (for example, <code>ENH: Support for SB-reference in multi-band datasets</code>):</p> <ul> <li><code>ENH</code>: enhancements or new features (example)</li> <li><code>FIX</code>: bug fixes (example)</li> <li><code>TST</code>: new or updated tests (example)</li> <li><code>DOC</code>: new or updated documentation (example)</li> <li><code>STY</code>: style changes (example)</li> <li><code>REF</code>: refactoring existing code (example)</li> <li><code>CI</code>: updates to continous integration infrastructure (example)</li> <li><code>MAINT</code>: general maintenance (example)</li> <li>For works-in-progress, add the <code>WIP</code> tag in addition to the descriptive prefix.    Pull-requests tagged with <code>WIP:</code> will not be merged until the tag is removed.</li> </ul> </li> <li> <p>Have your PR reviewed by the developers team, and update your changes accordingly in your branch.    The reviewers will take special care in assisting you address their comments, as well as dealing with conflicts    and other tricky situations that could emerge from distributed development.</p> </li> </ol>"},{"location":"community/CONTRIBUTING/#nipreps-coding-style-guide","title":"NiPreps coding style guide","text":"<p>Whenever possible, instances of Nipype <code>Node</code>s and <code>Workflow</code>s should use the same names as the variables they are assigned to. This makes it easier to relate the content of the working directory to the code that generated it when debugging.</p> <p>Workflow variables should end in <code>_wf</code> to indicate that they refer to Workflows and not Nodes. For instance, a workflow whose basename is <code>myworkflow</code> might be defined as follows:</p> <pre><code>from nipype.pipeline import engine as pe\n\nmyworkflow_wf = pe.Workflow(name='myworkflow_wf')\n</code></pre> <p>If a workflow is generated by a function, the name of the function should take the form <code>init_&lt;basename&gt;_wf</code>:</p> <pre><code>def init_myworkflow_wf(name='myworkflow_wf):\n    workflow = pe.Workflow(name=name)\n    ...\n    return workflow\n\nmyworkflow_wf = init_workflow_wf(name='myworkflow_wf')\n</code></pre> <p>If multiple instances of the same workflow might be instantiated in the same namespace, the workflow names and variables should include either a numeric identifier or a one-word description, such as:</p> <pre><code>myworkflow0_wf = init_workflow_wf(name='myworkflow0_wf')\nmyworkflow1_wf = init_workflow_wf(name='myworkflow1_wf')\n\n# or\n\nmyworkflow_lh_wf = init_workflow_wf(name='myworkflow_lh_wf')\nmyworkflow_rh_wf = init_workflow_wf(name='myworkflow_rh_wf')\n</code></pre>"},{"location":"community/CONTRIBUTING/#recognizing-contributions","title":"Recognizing contributions","text":"<p>We welcome and recognize all contributions regardless their size, content or scope: from documentation to testing and code development. You can see a list of current developers and contributors in our zenodo file. Before every release, a new zenodo file will be generated. The update script will also sort creators and contributors by the relative size of their contributions, as provided by the <code>git-line-summary</code> utility distributed with the <code>git-extras</code> package. Last positions in both the creators and contributors list will be reserved to the project leaders. These special positions can be revised to add names by punctual request and revised for removal and update of ordering in an scheduled manner every two years. All the authors enlisted as creators participate in the revision of modifications.</p>"},{"location":"community/CONTRIBUTING/#publications","title":"Publications","text":"<p>Anyone listed as a developer or a contributor can start the submission process of a manuscript as first author (please see Membership, where these concepts are described). To compose the author list, all the creators MUST be included (except for those people who opt to drop-out) and all the contributors MUST be invited to participate. First authorship(s) is (are) reserved for the authors that originated and kept the initiative of submission and wrote the manuscript. To generate the ordering of your paper, please run <code>python .maint/paper_author_list.py</code> from the root of the repository, on the up-to-date <code>upstream/master</code> branch. Then, please modify this list and place your name first. All developers and contributors are pulled together in a unique list, and last authorships assigned. NiPreps and its community adheres to open science principles, such that a pre-print should be posted on an adequate archive service (e.g., ArXiv or BioRxiv) prior publication.</p>"},{"location":"community/CONTRIBUTING/#licensing","title":"Licensing","text":"<p>NiPreps is licensed under the Apache 2.0 license. By contributing to NiPreps, you acknowledge that any contributions will be licensed under the same terms.</p>"},{"location":"community/CONTRIBUTING/#thank-you","title":"Thank you!","text":"<p>You're awesome. </p> <p></p> <p>\u2014 Based on contributing guidelines from the STEMMRoleModels project.</p> <ol> <li> <p>The imposter syndrome disclaimer was originally written by Adrienne Lowe for a PyCon talk, and was adapted based on its use in the README file for the MetPy project.\u00a0\u21a9</p> </li> </ol>"},{"location":"community/features/","title":"New features","text":"<p>The one bit that worries me is that fMRIPrep may become a Swiss army knife. I think instead it should just be a paring knife (small, efficient, and works for many things).</p> <p>-- Satra (source)</p> <p>When projects grow large, many forking paths created by newly implemented features start to open up. To account for this, the NiPreps community was created with the vision of building tools like fMRIPrep and MRIQC covering new imaging modalities, while keeping existing NiPreps tightly within scope. Defining such a scope also aids the implementation of the ease-of-use principle:</p> <p>The same way the scanner does not offer an immense space of knobs to turn in the acquisition, NiPreps should not add many additional knobs to those for them to be considered a viable augmentation or extension of the scanner hw/sw.</p> <p>-- Oscar (source)</p>"},{"location":"community/features/#the-problem-of-feature-creep","title":"The problem of feature creep","text":"<p>To avert feature creep and to serve each individual NiPrep, we developed the following guidelines, with the hopes of keeping these tools in a healthy state.</p> <p>I'm worried fMRIPrep is catching a case of featuritis</p> <p>-- Mathias (source)</p> <p>These guidelines should also serve the community to transparently drive the process of including proposals into the road-map, set the ground for healthy conversation, and establish some patterns when accepting new-feature contributions. Before proposing new features, please be mindful that a road-map may not exist for a particular NiPrep. Even when a development road-map exists, please understand that it is not always possible to rigorously follow them:</p> <p>I think something like this is what we tried to start sketching out with the development roadmap. The concern, as I remember it, was that we couldn't guarantee (or rule out) specific features when working with a small development team.</p> <p>-- Elizabeth (source).</p>"},{"location":"community/features/#proposing-a-new-feature","title":"Proposing a new feature","text":""},{"location":"community/features/#why-the-new-feature-is-requested","title":"Why the new feature is requested?","text":"<p>Before going ahead and proposing a new feature, please take some time to learn whether the topic has been covered in the past and what decisions were made and why. This should be reasonably easy to do with the search tool of GitHub on the particular NiPrep repository.</p> <p>If no previous discussion about the new idea is found, the next step is ensuring the new feature aligns with the vision and the scope of the target tool, as Elizabeth points out. Taking a look into the Development Road-map of the particular project (if it exists), may help finding an answer.</p> <p>If the new feature still seems pertinent after this preliminary work or you are unsure about whether it falls within the scope, then go ahead and post an issue requesting feedback on your proposal. Please make sure to clearly state why the new feature should be considered.</p>"},{"location":"community/features/#some-questions-will-always-be-asked-about-a-new-feature","title":"Some questions will always be asked about a new feature","text":"<p>These questions by James will certainly help build up the discourse in support of the new feature, as the NiPreps maintainers will consider them:</p> <ul> <li> <p>Is the user interface affected?     Because NiPreps generally expose a command-line interface (CLI) for the     interaction with the user, new features involving changes to the CLI must be     considered with caution as they may harm the ease-of-use:</p> <p>It also seems that some new features add more confusion than others. Especially when the CLI is affected, and yet another option is added, that makes the tool more complex to use.</p> <p>-- Alejandro (source).</p> </li> <li> <p>Does the new feature substantially increase the internal complexity?     Maintainers and developers will attempt to consolidate tools and lower the internal     complexity whenever possible.     This effort usually competes with the addition of new features as they typically will     address particular use-cases rather than general improvements.     However, that doesn't need to be the case, as some sections of the code might be     objectively improvable and the integration of a new feature revising those might     also lower complexity.     Lowering the internal complexity will always be considered a great incentive     for a new feature to be accepted.</p> </li> <li> <p>Is there a standard procedure for the proposed feature in the literature?</p> <ul> <li>if so, could we just use that procedure/value?</li> </ul> </li> <li> <p>Is the feature dependent on some attribute of the input data? (e.g., TR, duration, etc.)</p> <ul> <li>if so, can the procedure/value be determined algorithmically?</li> </ul> </li> <li> <p>Does the feature interact with other settings?     For instance, fmriprep#1962     interacts with the a/tCompCor implementation.</p> </li> <li> <p>What is the difficulty of implementing the procedure outside of a NiPrep?     In other words, does the NiPrep provide all the necessary outputs for a     user to perform the non-standard analysis?</p> </li> </ul>"},{"location":"community/features/#how-the-integration-of-the-new-feature-willcan-be-validated","title":"How the integration of the new feature will/can be validated?","text":"<p>Please propose ways to validate the new feature in the context of the workflow. Meaning, the objective here is to validate that the new feature works well within the pipeline, rather than validating a specific algorithm. To ensure the sustainability of NiPreps, the onus of this validation should be on the person/group requesting the feature.</p>"},{"location":"community/licensing/","title":"Licensing and Derived Works","text":"<p>The NiPreps community believes that software is an integral component of scientific practice, and that any scientific claim must be verifiable by following the chain of reasoning from observation to conclusion. To achieve this, software must be free to use, inspect, and critique. We also believe that you should be free to modify our software to improve it or adapt it to new use cases.</p> <p>As software development is a dynamic process, code modifications can quickly become confusing as the original and modified versions depart from each other. For the sake of transparency and verification, when you modify our code, we ask that you document both the version of the software that you started with and the changes you make.</p> <p>We believe these freedoms are best promoted by distributing our software under free/open source software licenses, and the license we feel best promotes these goals is the Apache License, Version 2.0.</p> <p>This page outlines our commitment to transparent development and our expectations for developers who adapt NiPreps code to use in other projects.</p>"},{"location":"community/licensing/#licensing-of-nipreps-projects","title":"Licensing of NiPreps projects","text":"<p>All software packages and tools under the NiPreps umbrella must be licensed under the Apache License 2.0 by default, unless otherwise stated. The authors of new NiPreps packages may not abide by this general rule of thumb if necessary and/or sufficiently justified (e.g., the source code is actually derived from a product licensed under a copyleft license).</p> <p>Containerized Images bundling NiPreps components and their dependencies can be distributed under a free and open-source license without copyleft, such as the MIT License. In such a case, the attribution notice of the MIT license must be present in the header comment of the container image bootstraping file (for instance, the so-called <code>Dockerfile</code>). This different licensing must be also indicated in the <code>NOTICE</code> file of the corresponding NiPreps components bundled within the image.</p> <p>Docker-wrappers such as the <code>fmriprep-docker</code> package may be licensed under any free and open-source license without copyleft, such as the MIT License. This different licensing must be also indicated in the <code>NOTICE</code> file of the corresponding NiPreps components bundled within the image.</p> <p>Data (distributed within the test data of packages or through the <code>nipreps-data</code> GitHub organization) will preferably be distributed under the Creative Commons Zero v1.0 Universal.</p> <p>Under no circumstances any NiPreps software or data will be made publicly available unlicensed. If you find any component of NiPreps that is unlicensed, please make us aware at nipreps@gmail.com at your earliest convenience.</p>"},{"location":"community/licensing/#the-apache-license-20","title":"The Apache License 2.0","text":"<p>(This section is adapted from this blog post by D. Mar\u00edn)</p> <p>The Apache License was created by the Apache Software Foundation (ASF) as the license for its Apache HTTP Server.</p> <p>Just as the MIT License, it\u2019s a very permissive non-copyleft license that allows using the software for any purpose, distributing it, modifying it, and distributing derived works of it without concern for royalties. Its main differences, compared to the MIT License, are:</p> <ul> <li>Using the Apache License, the authors of the software grant patent licenses to any user or distributor of the code.   This patent licenses apply to any patent that, being licenseable by any of the software author, would be infringed by the piece of code they have created.</li> <li>Apache License required that unmodified parts in derived works keep the License.</li> <li>In every licensed file, any original copyright, patent, trademark or attribution notices must be preserved.</li> <li>In every licensed file change, there must be a notification stating that changes have been made in the file.</li> <li>If the Apache-licensed software includes a <code>NOTICE</code> file, this file and its contents must be preserved in all the derived works.</li> <li>If anyone intentionally sends a contribution for an Apache-licensed software to its authors, this contribution can automatically be used under the Apache License.</li> </ul> <p>This license is interesting because of the automatic patent license, and the clause about contribution submission.</p> <p>It\u2019s compatible with the GPL, so you can mix Apache licensed-code into GPL software.</p>"},{"location":"community/licensing/#why-apache-20","title":"Why Apache-2.0?","text":"<p>In the case of scientific software, we believe that clearly stating that a Derived Work introduces changes into the original Work is a fundamental measure of transparency. Other than that, we wanted a permissive, non-copyleft license.</p>"},{"location":"community/licensing/#what-is-our-expectation-for-derived-works","title":"What is our expectation for Derived Works?","text":"<p>At the bare minimum, you must meet the conditions of the license (simplified version) about preserving the license text and copyright/attribution notices as well as corresponding statements of changes.</p> <p>How to state that a file has been changed in a Derived Work. We suggest the following steps, heavily influenced by P. Ombredanne's recommendations at StackExchange:</p> <ol> <li>In each source file, add a note to the header comment stating that the file has been modified, with an approximate date, and a high-level description of the changes.    The date and the description of the changes are not strictly required, but they are positive etiquette from a software engineering standpoint and substantially improve the transparency of the changes from a scientific point of view.</li> <li>If the source file did not have a license notice in the header comment, please add it to avoid ambiguity.</li> <li>Deleted files: please keep the file with just the header comment and state that the file is deleted.    The change statement should follow the suggestion in 1), preferably stating whether the source has been deleted or moved over to other files.    If preserving the filename as-is might become confusing to the user of the Derived Work, the filename can be modified to be marked as hidden with a dot <code>.</code> or underscore <code>_</code> prefix, or modifying the extension.</li> <li>Preferably, also include a link to the original file in our GitHub repository, making sure the link is done to a particular commit state.</li> </ol> <p>What changes would we like to see annotated? The high-level description of the changes will preferably contain:</p> <ul> <li>Correction of bugs</li> <li>Substantial performance improvement decisions</li> <li>Replacement of relevant methods and dependencies by alternatives</li> <li>Changes to the license</li> </ul>"},{"location":"community/licensing/#example-of-our-expectations","title":"Example of our expectations","text":"<p>Let's say a Derived Work modifies the <code>sdcflows.viz.utils</code> code-base. The file may or may not have the attribution notice. At the time of writing, the header comment of this file is:</p> <p>Header comment in the original Work</p> With attribution notice <pre><code># emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-\n# vi: set ft=python sts=4 ts=4 sw=4 et:\n#\n# Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n#     http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> Without attribution notice <pre><code># emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-\n# vi: set ft=python sts=4 ts=4 sw=4 et:\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> <p>Either way (whether the attribution notice is present or not), we suggest to update this header comment to something along the lines of the following:</p> <p>Suggested header comment in the Derived Work</p> Required <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found at:\n# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with yellow color are explicitly required by the Apache-2.0 conditions.</p> Recommended (commit) <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found at:\n# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with green color are recommended by the NiPreps Developers.</p> Recommended (version) <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found within\n# the version 2.0.2 distribution of the software.\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with green color are recommended by the NiPreps Developers.</p> <p>Although it is not mandated by the license letter, the spirit of the Apache-2.0 (and all other licenses stipulating the statement of changes, such as the CC-BY 4.0) suggests that a date of modification and an overview of outstanding changes are pertinent. We also suggest a link to the original code, including the commit-hash (that long string starting with <code>50393a</code> in the URL above) for the location of the exact origin of the file. Alternatively, Derived Works may point to a exact release identifier where the original file is part of the code-base distribution. Please make sure to remove or replace with appropriate contents the comment tags <code>&lt;...&gt;</code> above.</p> <p>What if a Derived Work does not modify this particular file? You should retain the original attribution notice as is (or introduce it if missing), unless you are relicensing the file. In that case, proceed with the suggestions above, and note the license change in the STATEMENT OF CHANGES block of the header comment.</p>"},{"location":"community/licensing/#are-papers-using-apache-20-licensed-software-considered-as-derived-works","title":"Are papers using Apache-2.0 licensed software considered as Derived Works?","text":"<p>No, they don't because they only reuse the software (in other words, they don't redistribute the software). The license stipulates that redistribution must retain the license and attribution notices as they are. In the scientific context, it is likely that a particular tool is modified (for example, to replace a method that you think is not appropriate for your data). Then, redistribution of the source would be desirable from the transparent reporting point of view, and therefore you should honor the License.</p> <p>Generally, works using our NiPreps just need to follow the citation guidelines of the particular project and report the citation boilerplate including all software versions and literature references in the closest letter possible to that generated by the tool.</p>"},{"location":"community/licensing/#licensing-of-docker-and-singularity-images","title":"Licensing of Docker and Singularity images","text":"<p>Container images redistribute copies of NiPreps alongside their third-party dependencies, all of them bundled in the image. If the applicable license is Apache-2.0, then the text of a <code>NOTICE</code> file must be shown to the user. All NiPreps must insert a <code>NOTICE</code> file into their containerized distributions and print its contents out in the command line output, as well as in the visual reports. This <code>NOTICE</code> file for containers will be placed in the <code>/.docker/NOTICE</code> path of the repository, and this file must replace the <code>/NOTICE</code> file (if it exists) at image building time. Alternatively, and if the corresponding NiPreps Developers consider that the Apache-2.0 imposes too onerous requirements for the container image distribution, the source code of such images (e.g., <code>Dockerfile</code>) can be licensed under the MIT license.</p> <p>Example <code>NOTICE</code> file for fMRIPrep</p> Python distribution <code>/NOTICE</code> <pre><code>fMRIPrep\nCopyright 2021 The NiPreps Developers.\n\nThis product includes software developed by\nthe NiPreps Community (https://nipreps.org/).\n\nPortions of this software were developed at the Department of\nPsychology at Stanford University, Stanford, CA, US.\n\nThis software contains code ultimately derived from the epidewarp.fsl\nscript (https://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)\nby Doug Greve, Dave Tuch, Tom Liu, and Bryon Mueller with generous\nhelp from the FSL crew (www.fmrib.ox.ac.uk/fsl) and the Biomedical\nInformatics Research Network (www.nbirn.net).\n</code></pre> Container image distribution <code>/.docker/NOTICE</code> <pre><code>fMRIPrep Container Image distribution\nCopyright 2021 The NiPreps Developers.\n\nThis product includes fMRIPrep and software developed by\nthe NiPreps Community (https://nipreps.org/).\n\nPortions of this software were developed at the Department of\nPsychology at Stanford University, Stanford, CA, US.\n\nThis product bundles AFNI &lt;version-placeholder&gt;, which is available under\nthe Gnu General Public License.\nMajor portions of AFNI were written at the Medical College of Wisconsin,\nwhich owns the copyright to that code. For fuller details, see\nhttp://afni.nimh.nih.gov/pub/dist/src/README.copyright.\n\nThis product bundles ANTs &lt;version-placeholder&gt;, which is available under\nthe BSD 3-clause license terms.\nCopyright 2009-2013 ConsortiumOfANTS.\n\nThis product bundles BIDS-Validator &lt;version-placeholder&gt;, which is available\nunder the MIT License.\nCopyright 2015 The Board of Trustees of the Leland Stanford Junior University.\n\nThis product bundles the Connectome Workbench &lt;version-placeholder&gt;, which\nis available under the GPL-v2\n(https://www.humanconnectome.org/software/connectome-workbench-license).\n\nThis product bundles FSL &lt;version-placeholder&gt;, which is available\nunder a custom license with commercial restrictions\n(https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence).\nCopyright 2018, The University of Oxford.\n\nThis product bundles FreeSurfer &lt;version-placeholder&gt;, which is available\nunder a custom license and requires obtaining a license key\n(https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense).\nCopyright 2011, The General Hospital Corporation, Boston MA, USA.\n\nThis product bundles code derived from ICA-AROMA, both (fork and original work)\nare available under the Apache-2.0 license.\n(https://github.com/oesteban/ICA-AROMA/blob/master/license.md)\nCopyright 2021, Maarten Mennes\n\nThis product bundles Miniconda &lt;version-placeholder&gt;, which is available\nunder a BSD 3-clause license.\n(c) 2017 Continuum Analytics, Inc. (dba Anaconda, Inc.).\nhttps://www.anaconda.com. All Rights Reserved\n\nThis product bundles NeuroDebian, which adheres to the\nDebian Free Software Guidelines (DFSG)\nhttps://www.debian.org/social_contract#guidelines\nand the terms of the Debian Social Contract version 1.1.\n\nThis product bundles tools by the NiPy community, such as NiBabel\n(MIT License, https://github.com/nipy/nibabel/blob/master/COPYING),\nand NiPype (Apache-2.0, https://github.com/nipy/nipype/blob/master/LICENSE).\n\nThis product bundles Pandoc &lt;version-placeholder&gt;, which is available\nunder the GPL version 2 or later.\nCopyright (C) 2006-2021 John MacFarlane &lt;jgm at berkeley dot edu&gt;\n\nThis product bundles SVGO &lt;version-placeholder&gt;, which is available\nunder the MIT License.\nCopyright (c) Kir Belevich\n\nThis product bundles tedana &lt;version-placeholder&gt;, which is available under\nthe GNU Lesser General Public License v2.1.\nCopyright 2018, tedana developers.\n\nTemplateFlow, a component of this bundle, contains neuroimaging template\nand atlas data under several permissive licenses.\nPlease refer to the metadata of the particular template used in your study to\ndetermine the exact terms of the license and how to acknowledge attribution\nof those works.\n\nsMRIPrep, a component of this bundle, contains code ultimately derived from\nANTs &lt;version-placeholder&gt;, which is available under\nthe BSD 3-clause license terms.\nCopyright 2009-2013 ConsortiumOfANTS.\n\nsMRIPrep, a component of this bundle, contains code ultimately derived from\nMindboggle &lt;version-placeholder&gt;, which is available under\nthe Apache License 2.0.\nCopyright 2016, Mindboggle team (http://mindboggle.info)\n\nfMRIPrep contains code ultimately derived from the epidewarp.fsl\nscript (https://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)\nby Doug Greve, Dave Tuch, Tom Liu, and Bryon Mueller with generous\nhelp from the FSL crew (www.fmrib.ox.ac.uk/fsl) and the Biomedical\nInformatics Research Network (www.nbirn.net).\n</code></pre>"},{"location":"community/members/","title":"Membership","text":"<p>In general, NiPreps embrace a liberal contribution model of governance structure. However, because of the scientific domain of NiPreps, the community features some structure from meritocracy models to prescribe the order in the authors list of new papers about these tools.</p>"},{"location":"community/members/#developers","title":"Developers","text":"<p>Developers are members of a wonderful team driving the project. Names and contacts of all developers are included in the <code>.maint/developers.json</code> file of each project. Examples of steering activities that drive the project are: actively participating in the follow-up meetings, leading documentation sprints, helping in the design of the tool and definition of the roadmap, providing resources (in the broad sense, including funding), code-review, etc.</p>"},{"location":"community/members/#contributors","title":"Contributors","text":"<p>Contributors enlisted in the <code>.maint/contributors.json</code> file of each project actively help or have previously helped the project in a broad sense: writing code, writing documentation, benchmarking modules of the tool, proposing new features, helping improve the scientific rigor of implementations, giving out support on the different communication channels (mattermost, NeuroStars, GitHub, etc.). If you are new to the project, don't forget to add your name and affiliation to the list of contributors there! Our Welcome Bot will send an automated message reminding this to first-time contributors. Before every release, unlisted contributors will be invited again to add their names to the file (just in case they missed the automated message from our Welcome Bot).</p> <p>Contributors who have contributed at some point to the project but were required or they wished to disconnect from the project's updates and to drop-out from publications and other dissemination activities, are listed in the <code>.maint/former.json</code> file.</p>"},{"location":"devs/devenv/","title":"Developer Environment","text":"<p>This document explains how to prepare a new development environment and update an existing environment, as necessary, for the development of NiPreps' components. Some components may deviate from these guidelines, in such a case, please follow the guidelines provided in their documentation.</p> <p>If you plan to contribute back to the community, making your code available via pull-request, please make sure to have read and understood the Community Documents and Contributor Guidelines. If you plan to distribute derived code, please follow our licensing guidelines.</p> <p>Development in Docker is encouraged, for the sake of consistency and portability. By default, work should be built off of <code>nipreps/fmriprep:unstable</code>, which tracks the <code>master</code> branch, or <code>nipreps/fmriprep:latest</code>, which tracks the latest release version (see BIDS-Apps execution guide for the basic procedure for running).</p> <p>It will be assumed the developer has a working repository in <code>$HOME/projects/fmriprep</code>, and examples are also given for niworkflows and NiPype.</p>"},{"location":"devs/devenv/#patching-a-working-copy-into-a-docker-container","title":"Patching a working copy into a Docker container","text":"<p>In order to test new code without rebuilding the Docker image, it is possible to mount working repositories as source directories within the container. The Docker wrapper script simplifies this for the most common repositories:</p> <pre><code>    -f PATH, --patch-fmriprep PATH\n                          working fmriprep repository (default: None)\n    -n PATH, --patch-niworkflows PATH\n                          working niworkflows repository (default: None)\n    -p PATH, --patch-nipype PATH\n                          working nipype repository (default: None)\n</code></pre> <p>For instance, if your repositories are contained in <code>$HOME/projects</code>:</p> <pre><code>$ fmriprep-docker -f $HOME/projects/fmriprep/fmriprep \\\n                  -n $HOME/projects/niworkflows/niworkflows \\\n                  -p $HOME/projects/nipype/nipype \\\n                  -i nipreps/fmriprep:latest \\\n                  $HOME/fullds005 $HOME/dockerout participant\n</code></pre> <p>Note the <code>-i</code> flag allows you to specify an image.</p> <p>When invoking <code>docker</code> directly, the mount options must be specified with the <code>-v</code> flag:</p> <pre><code>-v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro\n-v $HOME/projects/niworkflows/niworkflows:/usr/local/miniconda/lib/python3.7/site-packages/niworkflows:ro\n-v $HOME/projects/nipype/nipype:/usr/local/miniconda/lib/python3.7/site-packages/nipype:ro\n</code></pre> <p>For example,</p> <pre><code>$ docker run --rm -v $HOME/ds005:/data:ro -v $HOME/dockerout:/out \\\n    -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro \\\n    nipreps/fmriprep:latest /data /out/out participant \\\n    -w /out/work/\n</code></pre> <p>In order to work directly in the container, pass the <code>--shell</code> flag to <code>fmriprep-docker</code></p> <pre><code>$ fmriprep-docker --shell $HOME/ds005 $HOME/dockerout participant\n</code></pre> <p>This is the equivalent of using <code>--entrypoint=bash</code> and omitting the fMRIPrep arguments in a <code>docker</code> command:</p> <pre><code>$ docker run --rm -v $HOME/ds005:/data:ro -v $HOME/dockerout:/out \\\n    -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro --entrypoint=bash \\\n    nipreps/fmriprep:latest\n</code></pre> <p>Patching containers can be achieved in Singularity analogous to <code>docker</code> using the <code>--bind</code> (<code>-B</code>) option:</p> <pre><code>$ singularity run \\\n    -B $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep \\\n    fmriprep.img \\\n    /scratch/dataset /scratch/out participant -w /out/work/\n</code></pre>"},{"location":"devs/devenv/#adding-dependencies","title":"Adding dependencies","text":"<p>New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies. Python dependencies may be added in three places, depending on whether the package is large or non-release versions are required. The image must be rebuilt after any dependency changes.</p> <p>Python dependencies should generally be included in the appropriate dependency metadata of the <code>setup.cfg</code> file found at the root of each repository. If some the dependency must be a particular version (or set thereof), it is possible to use version filters in this <code>setup.cfg</code> file.</p> <p>For large Python dependencies where there will be a benefit to pre-compiled binaries, conda packages may also be added to the <code>conda install</code> line in the Dockerfile.</p> <p>Non-Python dependencies must also be installed in the Dockerfile, via a <code>RUN</code> command. For example, installing an <code>apt</code> package may be done as follows:</p> <pre><code>RUN apt-get update &amp;&amp; \\\n    apt-get install -y &lt;PACKAGE&gt;\n</code></pre>"},{"location":"devs/devenv/#rebuilding-docker-image","title":"(Re)Building Docker image","text":"<p>If it is necessary to (re)build the Docker image, a local image named <code>fmriprep</code> may be built from within the local repository. Let's assume it is located in <code>~/projects/fmriprep</code>:</p> <pre><code>~/projects/fmriprep$ VERSION=$( python get_version.py )\n~/projects/fmriprep$ docker build -t fmriprep --build-arg VERSION=$VERSION .\n</code></pre> <p>The <code>VERSION</code> build argument is necessary to ensure that help text can be reliably generated. The <code>get_version.py</code> tool constructs the version string from the current repository state.</p> <p>To work in this image, replace <code>nipreps/fmriprep:latest</code> with just <code>fmriprep</code> in any of the above commands. This image may be accessed by the Docker wrapper via the <code>-i</code> flag, e.g.:</p> <pre><code>$ fmriprep-docker -i fmriprep --shell\n</code></pre>"},{"location":"devs/devenv/#code-server-development-environment-experimental","title":"Code-Server Development Environment (Experimental)","text":"<p>To get the best of working with containers and having an interactive development environment, we have an experimental setup with code-server.</p> <p>Important</p> <p>We have a video walking through the process if you want a visual guide.</p> <p>1. Build the Docker image. We will use the <code>Dockerfile_devel</code> file to build our development docker image: <pre><code>$ cd $HOME/projects/fmriprep\n$ docker build -t fmriprep_devel -f Dockerfile_devel .\n</code></pre></p> <p>2. Run the Docker image We can start a docker container using the image we built (<code>fmriprep_devel</code>): <pre><code>$ docker run -it -p 127.0.0.1:8445:8080 -v ${PWD}:/src/fmriprep fmriprep_devel:latest\n</code></pre></p> <p>Windows Users</p> <p>If you are using windows shell, <code>${PWD}</code> may not be defined, instead use the absolute path to your repository.</p> <p>Docker-Toolbox</p> <p>If you are using Docker-Toolbox, you will need to change your virtualbox settings using these steps as a guide. For step 6, instead of <code>Name = rstudio; Host Port = 8787; Guest Port = 8787</code>, have <code>Name = code-server; Host Port = 8443; Guest Port = 8080</code>. Then in the docker command above, change <code>127.0.0.1:8445:8080</code> to <code>192.168.99.100:8445:8080</code>.</p> <p>If the container started correctly, you should see the following on your console:</p> <pre><code>INFO  Server listening on http://localhost:8080\nINFO    - No authentication\nINFO    - Not serving HTTPS\n</code></pre> <p>Now you can switch to your favorite browser and go to: 127.0.0.1:8445 (or 192.168.99.100:8445 for Docker Toolbox).</p> <p>3. Copy <code>fmriprep.egg-info</code> into your <code>fmriprep/</code> project directory <code>fmriprep.egg-info</code> makes the package exacutable inside the docker container. Open a terminal in vscode and type the following:</p> <pre><code>$ cp -R /src/fmriprep.egg-info /src/fmriprep/\n</code></pre>"},{"location":"devs/devenv/#code-server-development-environment-features","title":"Code-Server Development Environment Features","text":"<ul> <li> <p>The editor is vscode</p> </li> <li> <p>There are several preconfigured debugging tests under the debugging icon in the activity bar</p> </li> <li> <p>see vscode debugging python for details.</p> </li> <li> <p>The <code>gitlens</code> and <code>python</code> extensions are preinstalled to improve the development experience in vscode.</p> </li> </ul>"},{"location":"devs/releases/","title":"Releases","text":"<p>As of January 2020, fMRIPrep has adopted a Calendar Versioning scheme, and with it we are attempting to apply more coherent semantic rules to our releases.</p> <p>Note</p> <p>This document is a draft for internal and external comment. Any commitments expressed here are proposals, and should not be relied upon at this time. This conversation started as a Google Doc.</p>"},{"location":"devs/releases/#principles","title":"Principles","text":"<p>The basic release form is <code>YY.MINOR.PATCH</code>, so the first minor release of 2020 is 20.0.0, and the first minor release of 2021 will be 21.0.0, whatever the final minor release of 2020 is. A series of releases share a <code>YY.MINOR.</code> prefix, which we refer to as the <code>YY.MINOR.x</code> series. For example, the 20.0.x series contains version 20.0.0, 20.0.1, and any other releases needed.</p>"},{"location":"devs/releases/#feature-releases","title":"Feature releases","text":"<p>Minor releases are considered feature releases. Because there is no concept of a \"major\" release (just a calendar year rollover), most changes to the code base will result in a new feature release. Changes targeting a new feature release should target the master branch. Feature releases may be released as often as is deemed appropriate.</p>"},{"location":"devs/releases/#bug-fix-releases","title":"Bug-fix releases","text":"<p>Patch releases are considered bug-fix releases. Each minor release triggers the creation of a new <code>maint/&lt;YY&gt;.&lt;MINOR&gt;.x</code> branch, and changes targeting a bug-fix release should target this branch. A \"minor release series\" is the initial feature release and the bug-fix releases that share the minor release prefix. Bug-fix releases may be released on minimal notice to other developers.</p> <p>These releases must satisfy four conditions:</p> <ol> <li>Resolving one or more bugs. These mostly include failures of fMRIPrep to complete or producing invalid derivatives (e.g., a NIfTI file of all zeroes).</li> <li>Derivatives compatibility. If a subject may be successfully run on 20.0.n, then the imaging derivatives should be identical if rerun with 20.0.(n+1), modulo rounding errors and the effects of nondeterministic algorithms. The changes between successful runs of 20.0.n and 20.0.(n+1) should not be larger than the changes between two successful runs of 20.0.n. Cosmetic changes to reports are acceptable, while differing fields of view or data types in a NIfTI file would not be.</li> <li>API compatibility. Workflow-generating functions, workflow input- and outputnode fields must not change. As an end-user application, this may seem overly strict, but the odds of introducing a bug are much higher in these cases.</li> <li>User interface compatibility. Substantial changes to fMRIPrep command line must not happen (e.g., the addition of a new, relevant flag).</li> </ol> <p>Note that not all bugs can be fixed in a way that satisfies all three of these criteria without significant effort. A developer may determine that the bug will be fixed in the next feature release.</p> <p>Additional acceptable changes within a minor release series:</p> <ol> <li>Improved tests. These often come along with bug fixes, but they can be free-standing improvements to the code base.</li> <li>Improved documentation. Unless the documentation is of a feature that will not be present in a bug-fix release, this is always welcome.</li> <li>Updates to the Dockerfile that improve operation for Docker and/or Singularity users, but do not risk behavior change. A good example is including more templates to reduce the need for network requests. An example of an update to the Dockerfile that forces a minor release increment is a change in the pinned version of any of the dependencies or the base container image.</li> <li>Improvements to the lightweight wrappers. As long as a command-line invocation that worked for the previous version continues to work and produce the same Docker command, there's little chance of harm.</li> </ol>"},{"location":"devs/releases/#mechanics","title":"Mechanics","text":""},{"location":"devs/releases/#branch-synchronization","title":"Branch synchronization","text":"<p>A maintenance branch should generally follow directly from the tag of the feature release. <pre><code>git checkout -b maint/20.0.x 20.0.0\ngit push upstream maint/20.0.x\n</code></pre></p> <p>It is expected that <code>maint/20.0.x</code> will diverge from <code>master</code>, as new features will be merged into <code>master</code>, and bug-fixes into <code>maint/20.0.x</code>. At a minimum, each new bug-fix release should be merged into <code>master</code>. After a <code>20.0.1</code> release: <pre><code>git checkout master\ngit fetch upstream\ngit reset --hard upstream/master\ngit merge --no-commit 20.0.1\n\n# Resolve any merge conflicts\ngit add .\n\n# Manually review all changes to ensure compatibility\ngit diff --cached upstream/master\ngit commit\ngit push upstream master\n</code></pre></p> <p>If an unreleased bug-fix seems likely to cause merge conflicts, it may be worth doing the above more frequently.</p>"},{"location":"devs/releases/#dependencies","title":"Dependencies","text":"<p>fMRIPrep has a number of dependencies that we control at this point:</p> <ol> <li>sMRIPrep</li> <li>SDCflows</li> <li>NiWorkflows</li> </ol> <p>These do not follow the same versioning scheme as above, but we need them to follow a compatible scheme. In particular, we need to be able to fix bugs that are situated within these dependencies in a bug-fix release without violating the criteria laid out above. At the time of an fMRIPrep feature release, all of the above tools need to also split out a maintenance branch (if they have not already) for the minor version series that fMRIPrep depends on. As an example, when 20.0.0 was released, fMRIPrep had the following dependencies in <code>setup.cfg</code>:</p> <p><pre><code>    niworkflows ~= 1.1.7\n    sdcflows ~= 1.2.0\n    smriprep ~= 0.5.2\n</code></pre> <code>~=</code> is the compatible release specifier described in PEP 440. <code>~= 1.1.7</code> is equivalent to <code>&gt;= 1.1.7, == 1.1.*</code>. This means that the current version of fMRIPrep is expected to work with niworkflows 1.1.7+ but not 1.2+. Thus, niworkflows needs to have a maint/1.1.x branch, sdcflows a <code>maint/1.2.x</code> and smriprep <code>maint/0.5.x</code>. Any changes to these tools that might violate API or derivative compatibility, must go into master, and must not be released into the current minor series of these tools. Note that fMRIPrep 20.0.0 does not depend on <code>niworkflows ~= 1.1.0</code>. Multiple feature releases of fMRIPrep may depend on the same minor release series of a dependency. There is no requirement to hike the dependency. However, if a dependency has started a new minor release series, a feature release of fMRIPrep is a good opportunity to bump the dependency.</p> <p>We maintain a Versions Matrix to document and keep track of these dependencies.</p>"},{"location":"devs/releases/#support-windows","title":"Support Windows","text":""},{"location":"devs/releases/#minor-release-series","title":"Minor release series","text":"<p>A minor release series will continue to accept qualifying bug fixes at least until the next minor release. A minimum duration may be considered, or a fixed number of minor release series might be simultaneously supported.</p> <p>An unmaintained series is a valid target for bug fixes after the support window, but the expected effort level of the contributor and maintainers will be higher and lower, respectively.</p>"},{"location":"devs/releases/#long-term-support-series","title":"Long-term support series","text":"<p>A long-term support (LTS) series is a minor release series that an LTS manager commits to maintaining for a specific duration, no less than one year. LTS series are under the same constraints as a minor release series in terms of what changes can be accepted.</p> <p>The fMRIPrep developers commit to maintaining one LTS series at all times, at intervals of approximately one year. Community members may volunteer to assume maintainership after the initial period, or to maintain another minor release series as LTS.</p> <p>Support windows of greater than a year have a much higher potential to run into issues with upstream dependencies going outside of their support windows. As much as possible, an fMRIPrep minor release should seek to move to the versions of upstream dependencies that will ensure the longest support before being considered for LTS.</p> <p>Additional tasks required of an LTS manager:</p> <ul> <li> <p>Tracking possible breaking changes and broken URLs in upstream projects outside of the nipreps ecosystem.</p> <ul> <li>Neurodebian dependencies (AFNI, FSL, Convert3D, Connectome WB)</li> <li>FreeSurfer</li> <li>ANTs</li> <li>NodeJS - BIDS-validator, SVGO</li> <li>Pandoc</li> <li>ICA-AROMA</li> <li>Miniconda</li> <li>Python minor series end-of-life</li> <li>numpy, scipy, pandas, nipype, nibabel, matplotlib</li> </ul> </li> <li> <p>Backporting fixes from other maintained series.</p> <ul> <li>If a bug is identified as existing within the LTS series and can be fixed without breaking API or derivative compatibility.</li> </ul> </li> </ul> <p>As many dependencies as possible should be pinned to specific versions relevant to the environment they are installed in. Packages (Debian <code>.deb</code> files, conda packages, Python wheels) should be archived in case of a loss of the external packages.</p>"},{"location":"devs/versions/","title":"Versions Matrix","text":"<p>The versions matrix is intended to allow easy reference for the dependencies within the NiPreps family of projects.</p>"},{"location":"devs/versions/#fmriprep","title":"fMRIPrep","text":"fMRIPrep series sMRIPrep series SDCflows series NiWorkflows series 23.1.x <code>~= 0.12.0</code> <code>~= 2.5.0</code> <code>~= 1.8.0</code> 23.0.x <code>~= 0.11.0</code> <code>~= 2.4.0</code> <code>~= 1.7.6</code> 22.1.x <code>~= 0.10.0</code> <code>~= 2.2.1</code> <code>~= 1.7.0</code> 22.0.x <code>~= 0.9.2</code> <code>~= 2.1.1</code> <code>~= 1.6.3</code> 21.0.x <code>~= 0.8.0</code> <code>~= 2.0.0</code> <code>~= 1.4.0</code> 20.2.x <code>~= 0.7.0</code> <code>~= 1.3.1</code> <code>~= 1.3.0</code> 20.1.x <code>~= 0.6.1</code> <code>~= 1.3.1</code> <code>~= 1.2.3</code> 20.0.x <code>~= 0.5.2</code> <code>~= 1.2.0</code> <code>~= 1.1.7</code> 1.5.3+ <code>~= 0.4.0</code> <code>~= 1.0.1</code> <code>~= 1.0.2</code> <p>(Originally posted at nipreps/fmriprep#2054)</p>"},{"location":"devs/versions/#dmriprep","title":"dMRIPrep","text":"<p>(Work in progress)</p>"},{"location":"devs/versions/#smriprep","title":"sMRIPrep","text":"<p>sMRIPrep requires niworkflows and generally must depend on one minor series of niworkflows for the duration of an sMRIPrep minor series. Each sMRIPrep series may also be depended on for an fMRIPrep series and/or a dMRIPrep series. Noting these dependencies here should make it easier to track when a new minor series needs to be created.</p> sMRIPrep series NiWorkflows series TemplateFlow series 0.12.x <code>~=1.8.0</code> ... 0.10.x <code>~= 1.7.0</code> <code>&gt;= 0.6</code> 0.9.x <code>~= 1.6.0</code> <code>&gt;= 0.6</code> 0.8.x <code>~= 1.4.0</code> <code>&gt;= 0.6</code> 0.7.x <code>~= 1.3.0</code> <code>~= 0.6</code> 0.6.x <code>~= 1.2.0</code> <code>~= 0.6</code> 0.5.x <code>~= 1.1.5</code> <code>~= 0.4.2</code> <p>(Originally posted at nipreps/smriprep#172)</p>"},{"location":"devs/versions/#mriqc","title":"MRIQC","text":"<p>(Work in progress)</p>"},{"location":"intro/nipreps/","title":"Framework","text":""},{"location":"intro/nipreps/#building-on-fmripreps-success-story","title":"Building on fMRIPrep's success story","text":"<p>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 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.</p>"},{"location":"intro/nipreps/#leveraging-bids","title":"Leveraging BIDS","text":"<p>NiPreps leverage the Brain Imaging Data Structure (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.</p>"},{"location":"intro/nipreps/#architecture","title":"Architecture","text":"<p>The NiPreps framework (Figure 1) encompasses a wide array of software projects organized into three layers of scientific software:</p> <ul> <li>Software infrastructure: including quite mature projects such as NiPype and NiBabel; 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).</li> <li>Middleware: these are utilities that generalize their functionalities across the end-user tools.     These utilities cover foundational processing methodologies (e.g., NiWorkflows and SDCflows), the crowdsourcing of metadata (e.g., MRIQC Web-API), and the support for deep learning models (MRIQC-nets).</li> <li>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.</li> </ul> <p> </p>"},{"location":"intro/nipreps/#projects","title":"Projects","text":"<ul> <li>fMRIPrep (GitHub): fMRI Preprocessing</li> <li>dMRIPrep (GitHub): dMRI Preprocessing</li> <li>sMRIPrep (GitHub): Structural MRI Preprocessing</li> <li>MRIQC (GitHub): MRI quality control</li> <li>SDCflows (GitHub): Susceptibility-derived distortion correction (SDC) workflows</li> <li>NiWorkflows (GitHub): General/miscellaneous workflow utilities</li> <li>TemplateFlow: A registry of neuroimaging templates and spatial mappings between them.</li> <li>NiTransforms (GitHub)</li> </ul>"},{"location":"intro/nipreps/#early-stage-projects","title":"Early-stage projects","text":"<ul> <li>NiRodents (GitHub): middleware adaptations for small animals imaging.</li> <li>NiBabies (GitHub): middleware adaptations for infant imaging.</li> </ul>"},{"location":"intro/transparency/","title":"Transparency of workflows","text":"<p>NiPreps adopt fMRIPrep's foundations, and particularly resonate with the transparency principles. As discussed in (Esteban et al., 2019 -- preprint):</p> <p>The rapid increase in the volume and diversity of data, as well as the evolution of available techniques for processing and analysis, presents an opportunity for considerable advancement of research in neuroscience. The drawback resides in the need for progressively more complex analysis workflows that rely on decreasingly interpretable models of the data. Such context encourages \u2018black-box\u2019 solutions that efficiently perform a valuable service but do not provide insights into how the tool has transformed the data into the expected outputs. Black boxes obscure important steps in the inductive process mediating between experimental measurements and reported findings. This way of moving forward risks producing a future generation of cognitive neuroscientists who have become experts in sophisticated computational methods but have little to no working knowledge of how their data were transformed through processing. Transparency is often identified as a remedy for these problems. fMRIPrep ascribes to \u2018glass-box\u2019 principles, which are defined in opposition to the many different facets or levels at which black-box solutions are opaque. The visual reports that fMRIPrep generates are a crucial aspect of the glass-box approach. Their quality control checkpoints represent the logical flow of preprocessing, allowing scientists to critically inspect and better understand the underlying mechanisms of the workflow. A second transparency element is the citation boilerplate that formalizes all details of the workflow and provides the versions of all involved tools along with references to the corresponding scientific literature. A third asset for transparency is thorough documentation that delivers additional details on each of the building blocks represented in the visual reports and described in the boilerplate. Further, fMRIPrep has been open-source since its inception: users have access to all of the incremental additions to the tool through the history of the version-control system. The use of GitHub grants access to the discussions held during development, allowing one to see how and why the main design decisions were made. The modular design of fMRIPrep enhances its flexibility and improves transparency, as the main features of the software are more easily accessible to potential collaborators. In combination with some coding style and contribution guidelines, this modularity has enabled multiple contributions by peers and the creation of a rapidly growing community that would be difficult to nurture behind closed doors.</p>"},{"location":"intro/transparency/#visual-reports-beyond-quality-control","title":"Visual reports beyond quality control","text":"<p>One foundational component of the NiPreps framework is the Visual Report System. End-user applications such as fMRIPrep or dMRIPrep generate individual reports after their preprocessing. Those visual reports have two fundamental purposes:</p> <ul> <li>assessing the quality of the generated outputs, permitting the user to take quality control actions to eliminate biases originated from inadequate processing; and</li> <li>understanding the workflow, by sequentially presenting the main steps of processing, the user can access the why the tool in particular took these steps ando more geneally why standard preprocessing involves that step.</li> </ul>"},{"location":"intro/transparency/#citation-boilerplates","title":"Citation boilerplates","text":"<p>NiPreps leverage the wealth of existing neuroimaging software that is available to researchers. To give back for standing on the shoulders of giants, NiPreps aim at the most thorough reporting possible crediting all the pieces of the prior knowledge they leverage. With the execution of some particular NiPreps, the application runs some introspection code to formalize the computational graph the particular workflow executed and iterates over all the nodes to extract the relevant articles and communications that should be cited, as well as all software tools and their versions involved. Similarly, ancillary materials such as neuroimaging templates and atlases are reported and cited.</p> <p>All these references and citations are finally collated in a natural language description of the workflow. This description is therefore generated automatically, and contains all the details that are necessary to replicate the processing, as well as the abovementioned references. The text is appended to the visual report, and provided in three formats (markdown, latex and html/plain-text) with an index of citations, so that the user is only required to \"copy-and-paste\" into the Methods section of their papers.</p> <p>Note for reviewers and editors</p> <p>The boilerplate text generated by some NiPreps is intended to allow for clear, consistent description of the preprocessing steps used, in order to improve the reproducibility of studies. We fully intend for it to be copied verbatim, and have released it under the CC0 license, dedicating it to the public domain in jurisdictions that recognize the concept, and assert that we will take no action to enforce copyright in jurisdictions where we cannot disclaim it.</p> <p>We firmly believe that requiring authors to modify this passage will serve no legitimate scientific or literary purpose and can, in fact, serve only to reduce the replicability of the analysis being described by making the preprocessing steps less clear.</p> <p>We recognize that there may be automated plagiarism detection software that will flag the boilerplate text. We would be happy to discuss potential solutions for annotating boilerplate sections of documents to indicate automatic generation, and can update our software to make this annotation simpler for authors.</p>"},{"location":"news/","title":"News and Announcements","text":""},{"location":"news/#register-for-the-nipreps-hackathon-with-the-ohbm23-brainhack","title":"Register for the NiPreps hackathon with the OHBM'23 Brainhack!","text":"<p>We are thrilled to announce that the NiPreps Hackathon's second edition will be part of the upcoming OHBM'23 Brainhack (July 19-21, Maison Notman House, Montreal, Canada).</p> <p>Registration To join us for this incredible event and work on NiPreps-related projects, please fill in our registration form.</p> <p>Please remember to also register on the official webpage of the OHBM Brainhack. You will find all the necessary information, event schedule, and location details on Brainhack's website.</p> <p>Approach and projects We will advance (online) some projects as much as possible before the BrainHack. We are putting together a list of potential projects at https://github.com/orgs/nipreps/projects/8. Please feel free to let us know your ideas and voice your questions. Projects can start at any moment (even at the venue in Montreal) to have the flexibility to accommodate all ideas.</p> <p>Those projects with preliminary work will have project leaders who will organize meetings, coordinate a roadmap and help carry out the necessary tasks.</p> <p>See you in Montreal!</p>"},{"location":"news/#nipreps-roundups-feb-22-2023","title":"NiPreps Roundups  Feb 22, 2023","text":"<p>We resumed the bi-monthly NiPreps Roundups with a first meeting on February 22, 2023.</p>"},{"location":"users/educational/","title":"Educational resources","text":""},{"location":"users/educational/#online-books","title":"Online books","text":"<ul> <li>QC-Book, member-initiated tutorial at ISMRM 2022</li> <li>NiPreps Book, developing processing tools for dMRI, ISBI 2021</li> </ul>"},{"location":"users/educational/#qc-protocols-and-standard-operating-procedures","title":"QC protocols and Standard Operating Procedures","text":"<ul> <li>SOPs-cookiecutter, a template repository for version-controlled SOPs. The example template is rendered here</li> </ul>"},{"location":"users/educational/#presentation","title":"Presentation","text":"<ul> <li>Educational Talk at OHBM 2023 - Quality Control in fMRI studies with MRIQC and fMRIPrep</li> </ul>"},{"location":"users/talks/","title":"Talks and presentations","text":"<ul> <li>fMRIPrep Bootcamp Geneva 2024<ul> <li>Day 1: fMRIPrep Primer</li> <li>Day 1: BIDS</li> <li>Day 1: BIDS - Convert a dataset</li> <li>Day 1: Data and HPC</li> <li>Day 1: Containers</li> </ul> </li> <li>NiPreps @ BrainHack Seoul 2024</li> <li>Standardizing neuroimaging workflows (Journal Club @ EPFL 2023)</li> <li>Presentation about MRIQC for INCF 2022 (10 min)</li> <li>NiPreps introduction, Educational Session at OHBM 2022</li> <li>Building community workflows, BrainHack Donostia 2020</li> <li>Building communities around reproducible workflows, Open Reproducible Neuroscience workshop 2020</li> <li>Reproducible workflows, Think Open Rovereto Workshop 2020</li> </ul>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"NeuroImaging PREProcessing toolS (NiPreps)","text":"<p>NiPreps augment the scanner to produce data directly consumable by analyses.</p> <p>We refer to data directly consumable by analyses as analysis-grade data by analogy with the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are products that have been:</p> <ul> <li>minimally preprocessed, but are</li> <li>safe to consume directly.</li> </ul> <p> </p>"},{"location":"#building-on-the-success-story-of-fmriprep","title":"Building on the success story of fMRIPrep","text":"<p>NiPreps were conceived as a generalization of fMRIPrep across new modalities, populations, cohorts, and species. fMRIPrep is widely adopted, as our telemetry with Sentry (and now, in-house with migas) shows:</p> fMRIPrep is executed an average of 9,500 times every week, of which, around 7,000 times it finishes successfully (72.9% success rate). The average number of executions started includes debug and dry runs where researchers do not intend actually process data. Therefore, the effective (that is, discarding test runs) success ratio of fMRIPrep is likely higher."},{"location":"apps/docker/","title":"Executing with Docker","text":"<p>Summary</p> <p>Here, we describe how to run NiPreps with Docker containers. To illustrate the process, we will show the execution of fMRIPrep, but these guidelines extend to any other end-user NiPrep.</p>"},{"location":"apps/docker/#before-you-start-install-docker","title":"Before you start: install Docker","text":"<p>Probably, the most popular framework to execute containers is Docker. If you are to run a NiPrep on your PC/laptop, this is the RECOMMENDED way of execution. Please make sure you follow the Docker installation instructions. You can check your Docker Runtime installation running their <code>hello-world</code> image:</p> <pre><code>$ docker run --rm hello-world\n</code></pre> <p>If you have a functional installation, then you should obtain the following output:</p> <pre><code>Hello from Docker!\nThis message shows that your installation appears to be working correctly.\n\nTo generate this message, Docker took the following steps:\n 1. The Docker client contacted the Docker daemon.\n 2. The Docker daemon pulled the \"hello-world\" image from the Docker Hub.\n    (amd64)\n 3. The Docker daemon created a new container from that image which runs the\n    executable that produces the output you are currently reading.\n 4. The Docker daemon streamed that output to the Docker client, which sent it\n    to your terminal.\n\nTo try something more ambitious, you can run an Ubuntu container with:\n $ docker run -it ubuntu bash\n\nShare images, automate workflows, and more with a free Docker ID:\n https://hub.docker.com/\n\nFor more examples and ideas, visit:\n https://docs.docker.com/get-started/\n</code></pre> <p>After checking your Docker Engine is capable of running Docker images, you are ready to pull your first NiPreps container image.</p>"},{"location":"apps/docker/#docker-images","title":"Docker images","text":"<p>For every new version of the particular NiPrep app that is released, a corresponding Docker image is generated. The Docker image becomes a container when the execution engine loads the image and adds an extra layer that makes it runnable. In order to run NiPreps Docker images, the Docker Runtime must be installed.</p> <p>Taking fMRIPrep to illustrate the usage, first you might want to make sure of the exact version of the tool to be used:</p> <pre><code>$ docker pull nipreps/fmriprep:&lt;latest-version&gt;\n</code></pre> <p>You can run NiPreps interacting directly with the Docker Engine via the <code>docker run</code> interface.</p>"},{"location":"apps/docker/#running-a-niprep-with-a-lightweight-wrapper","title":"Running a NiPrep with a lightweight wrapper","text":"<p>Some NiPreps include a lightweight wrapper script for convenience. That is the case of fMRIPrep and its <code>fmriprep-docker</code> wrapper. Before starting, make sure you have the wrapper installed. When you run <code>fmriprep-docker</code>, it will generate a Docker command line for you, print it out for reporting purposes, and then execute it without further action needed, e.g.:</p> <pre><code>$ fmriprep-docker /path/to/data/dir /path/to/output/dir participant\nRUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \\\n    -v /path/to_output/dir:/out nipreps/fmriprep:20.2.2 \\\n    /data /out participant\n...\n</code></pre> <p><code>fmriprep-docker</code> implements the unified command-line interface of BIDS Apps, and automatically translates directories into Docker mount points for you.</p> <p>We have published a step-by-step tutorial illustrating how to run <code>fmriprep-docker</code>. This tutorial also provides valuable troubleshooting insights and advice on what to do after fMRIPrep has run.</p>"},{"location":"apps/docker/#running-a-niprep-directly-interacting-with-the-docker-engine","title":"Running a NiPrep directly interacting with the Docker Engine","text":"<p>If you need a finer control over the container execution, or you feel comfortable with the Docker Engine, avoiding the extra software layer of the wrapper might be a good decision.</p> <p>Accessing filesystems in the host within the container: Containers are confined in a sandbox, so they can't access the host in any ways unless you explicitly prescribe acceptable accesses to the host. The Docker Engine provides mounting filesystems into the container with the <code>-v</code> argument and the following syntax: <code>-v some/path/in/host:/absolute/path/within/container:ro</code>, where the trailing <code>:ro</code> specifies that the mount is read-only. The mount permissions modifiers can be omitted, which means the mount will have read-write permissions. In general, you'll want to at least provide two mount-points: one set in read-only mode for the input data and one read/write to store the outputs. Potentially, you'll want to provide one or two more mount-points: one for the working directory, in case you need to debug some issue or reuse pre-cached results; and a TemplateFlow folder to preempt the download of your favorite templates in every run.</p> <p>Running containers as a user: By default, Docker will run the container as root. Some share systems my limit this feature and only allow running containers as a user. When the container is run as root, files written out to filesystems mounted from the host will have the user id <code>1000</code> by default. In other words, you'll need to be able to run as root in the host to change permissions or manage these files. Alternatively, running as a user allows preempting these permissions issues. It is possible to run as a user with the <code>-u</code> argument. In general, we will want to use the same user ID as the running user in the host to ensure the ownership of files written during the container execution. Therefore, you will generally run the container with <code>-u $( id -u )</code>.</p> <p>You may also invoke <code>docker</code> directly:</p> <pre><code>$ docker run -ti --rm \\\n    -v path/to/data:/data:ro \\\n    -v path/to/output:/out \\\n    nipreps/fmriprep:&lt;latest-version&gt; \\\n    /data /out/out \\\n    participant\n</code></pre> <p>For example: :</p> <pre><code>$ docker run -ti --rm \\\n    -v $HOME/ds005:/data:ro \\\n    -v $HOME/ds005/derivatives:/out \\\n    -v $HOME/tmp/ds005-workdir:/work \\\n    nipreps/fmriprep:&lt;latest-version&gt; \\\n    /data /out/fmriprep-&lt;latest-version&gt; \\\n    participant \\\n    -w /work\n</code></pre> <p>Once the Docker Engine arguments are written, the remainder of the command line follows the usage. In other words, the first section of the command line is all equivalent to the <code>fmriprep</code> executable in a bare-metal installation: :</p> <pre><code>$ docker run -ti --rm \\                      # These lines\n    -v $HOME/ds005:/data:ro \\                # are equivalent to\n    -v $HOME/ds005/derivatives:/out \\        # a call to the App's\n    -v $HOME/tmp/ds005-workdir:/work \\       # entry-point.\n    nipreps/fmriprep:&lt;latest-version&gt; \\  #\n    \\\n    /data /out/fmriprep-&lt;latest-version&gt; \\   # These lines correspond\n    participant \\                            # to the particular BIDS\n    -w /work                                 # App arguments.\n</code></pre>"},{"location":"apps/framework/","title":"Introduction","text":""},{"location":"apps/framework/#what-is-bids","title":"What is BIDS?","text":"<p>The Brain Imaging Data Structure (BIDS) is a standard for organizing and describing brain datasets, including MRI. The common naming convention and folder structure allow researchers to easily reuse BIDS datasets, re-apply analysis protocols, and run standardized automatic data preprocessing pipelines (and particularly, BIDS Apps). The BIDS starter-kit contains a wide collection of educational resources. Validity of the structure can be assessed with the online BIDS-Validator. The tree of a typical, valid (BIDS-compliant) dataset is shown below:</p> <pre><code>ds000003/\n \u251c\u2500 CHANGES\n \u251c\u2500 dataset_description.json\n \u251c\u2500 participants.tsv\n \u251c\u2500 README\n \u251c\u2500 sub-01/\n \u2502 \u251c\u2500 anat/\n \u2502 \u2502 \u251c\u2500 sub-01_inplaneT2.nii.gz\n \u2502 \u2502 \u2514\u2500 sub-01_T1w.nii.gz\n \u2502 \u2514\u2500 func/\n \u2502 \u251c\u2500 sub-01_task-rhymejudgment_bold.nii.gz\n \u2502 \u2514\u2500 sub-01_task-rhymejudgment_events.tsv\n \u251c\u2500 sub-02/\n \u251c\u2500 sub-03/\n</code></pre>"},{"location":"apps/framework/#what-is-a-bids-app","title":"What is a BIDS App?","text":"<p>(Taken from the BIDS Apps paper)</p> <p>A BIDS App is a container image capturing a neuroimaging pipeline that takes a BIDS-formatted dataset as input. Since the input is a whole dataset, apps are able to combine multiple modalities, sessions, and/or subjects, but at the same time need to implement ways to query input datasets. Each BIDS App has the same core set of command-line arguments, making them easy to run and integrate into automated platforms. BIDS Apps are constructed in a way that does not depend on any software outside of the container image other than the container engine.</p> <p>BIDS Apps rely upon two technologies for container computing:</p> <ol> <li>Docker \u2014 for building, hosting as well as running containers on local hardware (running Windows, Mac OS X or Linux) or in the cloud.</li> <li>Singularity \u2014 for running containers on HPCs (high-performance computing).</li> </ol> <p>BIDS Apps are deposited in the Docker Hub repository, making them openly accessible. Each app is versioned and all of the historical versions are available to download. By reporting the BIDS App name and version in a manuscript, authors can provide others with the ability to exactly replicate their analysis workflow.</p> <p>Docker is used for its excellent documentation, maturity, and the Docker Hub service for storage and distribution of the images. Docker containers are easily run on personal computers and cloud services. However, the Docker Runtime was originally designed to run different components of web services (HTTP servers, databases etc.) using cloud resources. Docker thus requires root or root-like permissions, as well as modern versions of Linux kernel (to perform user mapping and management of network resources); though this is not a problem in context of renting cloud resources (which are not shared with other users), it makes it difficult or impossible to use in a multi-tenant environment such as an HPC system, which is often the most cost-effective computational resource available to researchers.</p> <p>Singularity, on the other hand, is a unique container technology designed from the ground up with the encapsulation of binary dependencies and HPC use in mind. Its main advantage over Docker is that it does not require root access for container execution and thus is safe to use on multi-tenant systems. In addition, it does not require recent Linux kernel functionalities (such as namespaces, cgroups and capabilities), making it easy to install on legacy systems.</p>"},{"location":"apps/framework/#analysis-levels","title":"Analysis levels","text":"<p>BIDS Apps decouple the individual level analysis (processing of independent subjects) from group-level analyses aggregating participants. For the analysis of individual subjects, Apps need to understand the BIDS structure of the input dataset, so that the required inputs for the designated subject are found. Apps are designed to easily process derivatives generated by the participant-level or other Apps. The overall workflow has an entry-point and an end-point responsible of setting-up the map-reduce tasks and the tear-down including organizing the outputs for its archiving, respectively. Each App may implement multiple map and reduce steps.</p> <p></p>"},{"location":"apps/framework/#a-unified-command-line-interface","title":"A unified command-line interface","text":"<p>To improve user experience and ability to integrate BIDS Apps into various computational platforms, each App follows a set of core command-line arguments:</p> <pre><code>$ &lt;entrypoint&gt; &lt;bids_dataset&gt; &lt;output_path&gt; &lt;analysis_level&gt;\n</code></pre> <p>For instance, to run fMRIPrep on a dataset located in <code>/data/bids_root</code> and write the outputs to <code>/data/bids_root/derivatives/</code>:</p> <pre><code>$ fmriprep /data/bids_root /data/bids_root/derivatives/ participant\n</code></pre> <p>In this case, we have selected to run the <code>participant</code> level (to process individual subjects). fMRIPrep does not have a <code>group</code> level, but other BIDS Apps may have. For instance, MRIQC generates group-level reports with the following command-line:</p> <pre><code>$ mriqc /data/bids_root /data/bids_root/derivatives/ group\n</code></pre>"},{"location":"apps/framework/#what-are-bids-derivatives","title":"What are BIDS Derivatives?","text":"<p>NiPreps generate derivatives of the original data, and they fulfill the BIDS specification for the results of Apps that are created for subsequent consumption by other BIDS-Apps. These derivatives must follow the BIDS Derivatives specification (draft). An example of BIDS Derivatives filesystem tree, generated with fMRIPrep 1.5: <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u251c\u2500\u2500 sub-02.html\n\u2502 \u251c\u2500\u2500 sub-02/\n\u2502 \u251c\u2500\u2500 sub-03.html\n\u2502 \u2514\u2500\u2500 sub-03/\n</code></pre></p>"},{"location":"apps/singularity/","title":"Executing with Singularity","text":"<p>Summary</p> <p>Here, we describe how to run NiPreps with Singularity containers. To illustrate the process, we will show the execution of fMRIPrep, but these guidelines extend to any other end-user NiPrep.</p>"},{"location":"apps/singularity/#preparing-a-singularity-image","title":"Preparing a Singularity image","text":"<p>Singularity version &gt;= 2.5: If the version of Singularity installed on your HPC (High-Performance Computing) system is modern enough you can create Singularity image directly on the system. This is as simple as:</p> <pre><code>$ singularity build /my_images/fmriprep-&lt;version&gt;.simg \\\n                    docker://nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>where <code>&lt;version&gt;</code> should be replaced with the desired version of fMRIPrep that you want to download.</p> <p>Singularity version &lt; 2.5: In this case, start with a machine (e.g., your personal computer) with Docker installed. Use docker2singularity to create a singularity image. You will need an active internet connection and some time:</p> <pre><code>$ docker run --privileged -t --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v D:\\host\\path\\where\\to\\output\\singularity\\image:/output \\\n    singularityware/docker2singularity \\\n    nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>Where <code>&lt;version&gt;</code> should be replaced with the desired version of fMRIPrep that you want to download.</p> <p>Beware of the back slashes, expected for Windows systems. For *nix users the command translates as follows: :</p> <pre><code>$ docker run --privileged -t --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v /absolute/path/to/output/folder:/output \\\n    singularityware/docker2singularity \\\n    nipreps/fmriprep:&lt;version&gt;\n</code></pre> <p>Transfer the resulting Singularity image to the HPC, for example, using <code>scp</code> or <code>rsync</code>:</p> <pre><code>$ scp nipreps_fmriprep*.img user@hcpserver.edu:/my_images\n</code></pre>"},{"location":"apps/singularity/#running-a-singularity-image","title":"Running a Singularity Image","text":"<p>If the data to be preprocessed is also on the HPC, you are ready to run the NiPrep:</p> <pre><code>$ singularity run --cleanenv fmriprep.simg \\\n    path/to/data/dir path/to/output/dir \\\n    participant \\\n    --participant-label label\n</code></pre>"},{"location":"apps/singularity/#handling-environment-variables","title":"Handling environment variables","text":"<p>Singularity by default exposes all environment variables from the host inside the container. Because of this, your host libraries (e.g., NiPype or a Python environment) could be accidentally used instead of the ones inside the container. To avoid such a situation, we strongly recommend using the <code>--cleanenv</code> argument in all scenarios. For example:</p> <pre><code>$ singularity run --cleanenv fmriprep.simg \\\n  /work/04168/asdf/lonestar/ $WORK/lonestar/output \\\n  participant \\\n  --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \\\n  --omp-nthreads 16\n</code></pre> <p>Alternatively, conflicts might be preempted and some problems mitigated by unsetting potentially problematic settings, such as the <code>PYTHONPATH</code> variable, before running:</p> <pre><code>$ unset PYTHONPATH; singularity run fmriprep.simg \\\n  /work/04168/asdf/lonestar/ $WORK/lonestar/output \\\n  participant \\\n  --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \\\n  --omp-nthreads 16\n</code></pre> <p>It is possible to define environment variables scoped within the container by using the <code>SINGULARITYENV_*</code> magic, in combination with <code>--cleanenv</code>. For example, we can set the FreeSurfer license variable (see fMRIPrep's documentation on this) as follows: :</p> <pre><code>$ export SINGULARITYENV_FS_LICENSE=$HOME/.freesurfer.txt\n$ singularity exec --cleanenv fmriprep.simg env | grep FS_LICENSE\nFS_LICENSE=/home/users/oesteban/.freesurfer.txt\n</code></pre> <p>As we can see, the export in the first line tells Singularity to set a corresponding environment variable of the same name after dropping the prefix <code>SINGULARITYENV_</code>.</p>"},{"location":"apps/singularity/#accessing-the-hosts-filesystem","title":"Accessing the host's filesystem","text":"<p>Depending on how Singularity is configured on your cluster it might or might not automatically bind (mount or expose) host's folders to the container (e.g., <code>/scratch</code>, or <code>$HOME</code>). This is particularly relevant because, if you can't run Singularity in privileged mode (which is almost certainly true in all the scenarios), Singularity containers are read only. This is to say that you won't be able to write anything unless Singularity can access the host's filesystem in write mode.</p> <p>By default, Singularity automatically binds (mounts) the user's home directory and a scratch directory. In addition, Singularity generally allows binding the necessary folders with the <code>-B &lt;host_folder&gt;:&lt;container_folder&gt;[:&lt;permissions&gt;]</code> Singularity argument. For example:</p> <pre><code>$ singularity run --cleanenv -B /work:/work fmriprep.simg \\\n  /work/my_dataset/ /work/my_dataset/derivatives/fmriprep \\\n  participant \\\n  --participant-label 387 --nthreads 16 \\\n  --omp-nthreads 16\n</code></pre> <p>Warning</p> <p>If your Singularity installation doesn't allow you to bind non-existent bind points, you'll get an error saying <code>WARNING: Skipping user bind, non existent bind point (directory) in container</code>. In this scenario, you can either try to bind things onto some other bind point you know it exists in the image or rebuild your singularity image with <code>docker2singularity</code> as follows:</p> <pre><code>$ docker run --privileged -ti --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n         -v $PWD:/output singularityware/docker2singularity \\\n         -m \"/gpfs /scratch /work /share /lscratch /opt/templateflow\"\n</code></pre> <p>In the example above, the following bind points are created: <code>/gpfs</code>, <code>/scratch</code>, <code>/work</code>, <code>/share</code>, <code>/opt/templateflow</code>.</p> <p>Important</p> <p>One great feature of containers is their confinement or isolation from the host system. Binding mount points breaks this principle, as the container has now access to create changes in the host. Therefore, it is generally recommended to use binding scarcely and granting very limited access to the minimum necessary resources. In other words, it is preferred to bind just one subdirectory of <code>$HOME</code> than the full <code>$HOME</code> directory of the host (see nipreps/fmriprep#1778 (comment)).</p> <p>Relevant aspects of the <code>$HOME</code> directory within the container: By default, Singularity will bind the user's <code>$HOME</code> directory in the host into the <code>/home/$USER</code> (or equivalent) in the container. Most of the times, it will also redefine the <code>$HOME</code> environment variable and update it to point to the corresponding mount point in <code>/home/$USER</code>. However, these defaults can be overwritten in your system. It is recommended to check your settings with your system's administrators. If your Singularity installation allows it, you can workaround the <code>$HOME</code> specification combining the bind mounts argument (<code>-B</code>) with the home overwrite argument (<code>--home</code>) as follows:</p> <pre><code>$ singularity run -B $HOME:/home/fmriprep --home /home/fmriprep \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#templateflow-and-singularity","title":"TemplateFlow and Singularity","text":"<p>TemplateFlow is a helper tool that allows neuroimaging workflows to programmatically access a repository of standard neuroimaging templates. In other words, TemplateFlow allows NiPreps to dynamically change the templates that are used, e.g., in the atlas-based brain extraction step or spatial normalization.</p> <p>Default settings in the Singularity image should get along with the Singularity installation of your system. However, deviations from the default configurations of your installation may break this compatibility. A particularly problematic case arises when the home directory is mounted in the container, but the <code>$HOME</code> environment variable is not correspondingly updated. Typically, you will experience errors like <code>OSError: [Errno 30] Read-only file system</code> or <code>FileNotFoundError: [Errno 2] No such file or directory: '/home/fmriprep/.cache'</code>.</p> <p>If it is not explicitly forbidden in your installation, the first attempt to overcome this issue is manually setting the <code>$HOME</code> directory as follows:</p> <pre><code>$ singularity run --home $HOME --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre> <p>If the user's home directory is not automatically bound, then the second step would include manually binding it as in the section above: :</p> <pre><code>$ singularity run -B $HOME:/home/fmriprep --home /home/fmriprep \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre> <p>Finally, if the <code>--home</code> argument cannot be used, you'll need to provide the container with writable filesystems where TemplateFlow's files can be downloaded. In addition, you will need to indicate fMRIPrep to update the default paths with the new mount points setting the <code>SINGULARITYENV_TEMPLATEFLOW_HOME</code> variable. :</p> <pre><code># Tell the NiPrep where TemplateFlow will place downloads\n$ export SINGULARITYENV_TEMPLATEFLOW_HOME=/opt/templateflow\n$ singularity run -B &lt;writable-path-on-host&gt;:/opt/templateflow \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#restricted-internet-access","title":"Restricted Internet access","text":"<p>We have identified several conditions in which running NiPreps might fail because of spotty or impossible access to Internet.</p> <p>If your compute node cannot have access to Internet, then you'll need to pull down from TemplateFlow all the resources that will be necessary ahead of run-time.</p> <p>If that is not the case (i.e., you should be able to hit HTTP/s endpoints), then you can try the following:</p> <ul> <li> <p><code>VerifiedHTTPSConnection ... Failed to establish a new connection: [Errno 110] Connection timed out</code>.   If you encounter an error like this, probably you'll need to set up an   http proxy exporting <code>SINGULARITYENV_http_proxy</code> (see nipreps/fmriprep#1778 (comment).   For example:</p> <pre><code>$ export SINGULARITYENV_https_proxy=http://&lt;ip or proxy name&gt;:&lt;port&gt;\n</code></pre> </li> <li> <p><code>requests.exceptions.SSLError: HTTPSConnectionPool ...</code>. In this case,   your container seems to be able to reach the Internet, but unable to use   SSL encription. There are two potential solutions to the issue. The   recommended one   is setting <code>REQUESTS_CA_BUNDLE</code> to the appropriate path, and/or binding   the appropriate filesystem:</p> <p><pre><code>$ export SINGULARITYENV_REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt\n$ singularity run -B &lt;path-to-certs-folder&gt;:/etc/ssl/certs \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>   Otherwise, some users have succeeded pre-fetching the necessary   templates onto the TemplateFlow directory to then bind the folder at   execution:</p> <pre><code>$ export TEMPLATEFLOW_HOME=/path/to/keep/templateflow\n$ python -m pip install -U templateflow  # Install the client\n$ python\n&gt;&gt;&gt; import templateflow.api\n&gt;&gt;&gt; templateflow.api.TF_S3_ROOT = 'http://templateflow.s3.amazonaws.com'\n&gt;&gt;&gt; api.get(\u2018MNI152NLin6Asym\u2019)\n</code></pre> </li> </ul> <p>Finally, run the singularity image binding the appropriate folder:</p> <pre><code>$ export SINGULARITYENV_TEMPLATEFLOW_HOME=/templateflow\n$ singularity run -B ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}:/templateflow \\\n      --cleanenv fmriprep.simg &lt;fmriprep arguments&gt;\n</code></pre>"},{"location":"apps/singularity/#troubleshooting","title":"Troubleshooting","text":"<p>Setting up a functional execution framework with Singularity might be tricky in some HPC (high-performance computing) systems. Please make sure you have read the relevant documentation of Singularity, and checked all the defaults and configuration in your system. The next step is checking the environment and access to fMRIPrep resources, using <code>singularity shell</code>.</p> <ol> <li> <p>Check access to input data folder, and BIDS validity:       <pre><code>$ singularity shell -B path/to/data:/data fmriprep.simg\nSingularity fmriprep.simg:~&gt; ls /data\nCHANGES  README  dataset_description.json  participants.tsv  sub-01  sub-02  sub-03  sub-04  sub-05  sub-06  sub-07  sub-08  sub-09  sub-10  sub-11  sub-12  sub-13  sub-14  sub-15  sub-16  task-balloonanalogrisktask_bold.json\nSingularity fmriprep.simg:~&gt; bids-validator /data\n   1: [WARN] You should define 'SliceTiming' for this file. If you don't provide this information slice time correction will not be possible. (code: 13 - SLICE_TIMING_NOT_DEFINED)\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-02_bold.nii.gz\n          ./sub-03/func/sub-03_task-balloonanalogrisktask_run-03_bold.nii.gz\n          ./sub-04/func/sub-04_task-balloonanalogrisktask_run-01_bold.nii.gz\n          ... and 38 more files having this issue (Use --verbose to see them all).\n  Please visit https://neurostars.org/search?q=SLICE_TIMING_NOT_DEFINED for existing conversations about this issue.\n</code></pre></p> </li> <li> <p>Check access to output data folder, and whether you have write    permissions       <pre><code>$ singularity shell -B path/to/data/derivatives/fmriprep-1.5.0:/out fmriprep.simg\nSingularity fmriprep.simg:~&gt; ls /out\nSingularity fmriprep.simg:~&gt; touch /out/test\nSingularity fmriprep.simg:~&gt; rm /out/test\n</code></pre></p> </li> <li> <p>Check access and permissions to <code>$HOME</code>:       <pre><code>$ singularity shell fmriprep.simg\nSingularity fmriprep.simg:~&gt; mkdir -p $HOME/.cache/testfolder\nSingularity fmriprep.simg:~&gt; rmdir $HOME/.cache/testfolder\n</code></pre></p> </li> <li> <p>Check TemplateFlow operation:       <pre><code>$ singularity shell -B path/to/templateflow:/templateflow fmriprep.simg\nSingularity fmriprep.simg:~&gt; echo ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}\n/home/users/oesteban/.cache/templateflow\nSingularity fmriprep.simg:~&gt; python -c \"from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])\"\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th0_dseg.nii.gz\n   304B [00:00, 1.28kB/s]\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th25_dseg.nii.gz\n   261B [00:00, 1.04kB/s]\n   Downloading https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_desc-th50_dseg.nii.gz\n   219B [00:00, 867B/s]\n   ...\n</code></pre></p> </li> </ol>"},{"location":"apps/singularity/#running-singularity-on-a-slurm-system","title":"Running Singularity on a SLURM system","text":"<p>An example of <code>sbatch</code> script to run fMRIPrep on a SLURM system<sup>1</sup> is given below. The submission script will generate one task per subject using a job array. <pre><code>#!/bin/bash\n#\n#SBATCH -J fmriprep\n#SBATCH --time=48:00:00\n#SBATCH -n 1\n#SBATCH --cpus-per-task=16\n#SBATCH --mem-per-cpu=4G\n#SBATCH -p normal,mygroup  # Queue names you can submit to\n# Outputs ----------------------------------\n#SBATCH -o log/%x-%A-%a.out\n#SBATCH -e log/%x-%A-%a.err\n#SBATCH --mail-user=%u@domain.tld\n#SBATCH --mail-type=ALL\n# ------------------------------------------\n\nBIDS_DIR=\"$STUDY/data\"\nDERIVS_DIR=\"derivatives/fmriprep-20.2.2\"\nLOCAL_FREESURFER_DIR=\"$STUDY/data/derivatives/freesurfer-6.0.1\"\n\n# Prepare some writeable bind-mount points.\nTEMPLATEFLOW_HOST_HOME=$HOME/.cache/templateflow\nFMRIPREP_HOST_CACHE=$HOME/.cache/fmriprep\nmkdir -p ${TEMPLATEFLOW_HOST_HOME}\nmkdir -p ${FMRIPREP_HOST_CACHE}\n\n# Prepare derivatives folder\nmkdir -p ${BIDS_DIR}/${DERIVS_DIR}\n\n# Make sure FS_LICENSE is defined in the container.\nexport SINGULARITYENV_FS_LICENSE=$HOME/.freesurfer.txt\n\n# Designate a templateflow bind-mount point\nexport SINGULARITYENV_TEMPLATEFLOW_HOME=\"/templateflow\"\nSINGULARITY_CMD=\"singularity run --cleanenv -B $BIDS_DIR:/data -B ${TEMPLATEFLOW_HOST_HOME}:${SINGULARITYENV_TEMPLATEFLOW_HOME} -B $L_SCRATCH:/work -B ${LOCAL_FREESURFER_DIR}:/fsdir $STUDY/images/fmriprep_20.2.2.simg\"\n\n# Parse the participants.tsv file and extract one subject ID from the line corresponding to this SLURM task.\nsubject=$( sed -n -E \"$((${SLURM_ARRAY_TASK_ID} + 1))s/sub-(\\S*)\\&gt;.*/\\1/gp\" ${BIDS_DIR}/participants.tsv )\n\n# Remove IsRunning files from FreeSurfer\nfind ${LOCAL_FREESURFER_DIR}/sub-$subject/ -name \"*IsRunning*\" -type f -delete\n\n# Compose the command line\ncmd=\"${SINGULARITY_CMD} /data /data/${DERIVS_DIR} participant --participant-label $subject -w /work/ -vv --omp-nthreads 8 --nthreads 12 --mem_mb 30000 --output-spaces MNI152NLin2009cAsym:res-2 anat fsnative fsaverage5 --use-aroma --fs-subjects-dir /fsdir\"\n\n# Setup done, run the command\necho Running task ${SLURM_ARRAY_TASK_ID}\necho Commandline: $cmd\neval $cmd\nexitcode=$?\n\n# Output results to a table\necho \"sub-$subject   ${SLURM_ARRAY_TASK_ID}    $exitcode\" \\\n      &gt;&gt; ${SLURM_JOB_NAME}.${SLURM_ARRAY_JOB_ID}.tsv\necho Finished tasks ${SLURM_ARRAY_TASK_ID} with exit code $exitcode\nexit $exitcode\n</code></pre> Submission is then as easy as:</p> <pre><code>$ export STUDY=/path/to/some/folder\n$ sbatch --array=1-$(( $( wc -l $STUDY/data/participants.tsv | cut -f1 -d' ' ) - 1 )) fmriprep.slurm\n</code></pre> <ol> <li> <p>assuming that job arrays and Singularity are available\u00a0\u21a9</p> </li> </ol>"},{"location":"assets/ORN-Workshop/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#building-communities-around-reproducible-workflows","title":"Building communities around reproducible workflows","text":""},{"location":"assets/ORN-Workshop/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/ORN-Workshop/presentation/#chuv-lausanne-university-hospital","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#building-communities-around-reproducible-workflows_1","title":"Building communities around reproducible workflows","text":""},{"location":"assets/ORN-Workshop/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/ORN-Workshop/presentation/#chuv-lausanne-university-hospital_1","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":"<p>]</p> <p>???</p>"},{"location":"assets/ORN-Workshop/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/ORN-Workshop/presentation/#data-processing","title":"Data Processing","text":""},{"location":"assets/ORN-Workshop/presentation/#day-2-15h-cet","title":"(Day 2, 15h CET)","text":""},{"location":"assets/ORN-Workshop/presentation/#workflows","title":"Workflows","text":"<p>]</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/ORN-Workshop/presentation/#data-processing_1","title":"Data Processing","text":""},{"location":"assets/ORN-Workshop/presentation/#day-2-15h-cet_1","title":"(Day 2, 15h CET)","text":""},{"location":"assets/ORN-Workshop/presentation/#workflows_1","title":"Workflows","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/ORN-Workshop/presentation/#neuroimaging-is-now-mature","title":"Neuroimaging is now mature","text":"<ul> <li>many excellent tools available (from specialized to foundational)</li> <li>large toolboxes (AFNI, ANTs/ITK, FreeSurfer, FSL, Nilearn, SPM, etc.)</li> <li>workflow software (Nipype, Shellscripts, Nextflow, CWL)</li> <li> <p>container technology, CI/CD</p> </li> <li> <p>a wealth of prior knowledge (esp. about humans)</p> </li> <li> <p>LOTS of data acquired everyday</p> </li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#workflows-games-on","title":"Workflows - game's on!","text":"<ul> <li> <p>although many neuroimaging areas are still in search of methodological breakthroughs,</p> </li> <li> <p>challenges have moved on to the workflows:</p> </li> <li>workflows within traditional toolboxes - usually not flexible to adapt to new data</li> <li>BIDS and BIDS-Apps.</li> </ul> <p>???</p> <ul> <li>researchers have a large portfolio of image processing components readily available</li> <li>toolboxes with great support and active maintenance:</li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#new-questions-changing-the-focus","title":"New questions changing the focus:","text":""},{"location":"assets/ORN-Workshop/presentation/#-validity-does-the-workflow-actually-work-out","title":"- validity (does the workflow actually work out?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-transparency-is-it-a-black-box-how-precise-is-reporting","title":"- transparency (is it a black-box? how precise is reporting?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-vibration-how-each-tool-choice-parameters-affect-overall","title":"- vibration (how each tool choice &amp; parameters affect overall?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-throughput-how-much-datatime-can-it-possible-take","title":"- throughput (how much data/time can it possible take?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-robustness-can-i-use-it-on-diverse-studies","title":"- robustness (can I use it on diverse studies?)","text":""},{"location":"assets/ORN-Workshop/presentation/#-evaluation-what-is-it-unique-about-the-workflow-wrt-existing-alternatives","title":"- evaluation (what is it unique about the workflow, w.r.t. existing alternatives?)","text":""},{"location":"assets/ORN-Workshop/presentation/#the-garden-of-forking-paths","title":"The garden of forking paths","text":"<p>(Botvinik-Nezer et al., 2020)</p> <p>Around 50% of teams used fMRIPrep'ed inputs.</p>"},{"location":"assets/ORN-Workshop/presentation/#the-fmriprep-story","title":"The fMRIPrep story","text":""},{"location":"assets/ORN-Workshop/presentation/#fmriprep-produces-analysis-ready-data-from-diverse-data","title":"fMRIPrep produces analysis-ready data from diverse data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> <li>robust against inhomogeneity of data across studies</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p>"},{"location":"assets/ORN-Workshop/presentation/#fmriprep-was-not-originally-envisioned-as-a-community-project","title":"fMRIPrep was not originally envisioned as a community project ...","text":"<p>(we just wanted a robust tool to automatically preprocess incoming data of OpenNeuro.org)</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#but-a-community-built-up-quickly-around-it","title":"... but a community built up quickly around it","text":"<p>--</p> <p>.pull-left[</p>"},{"location":"assets/ORN-Workshop/presentation/#why","title":"Why?","text":"<ul> <li> <p>Preprocessing of fMRI was in need for division of labor.</p> </li> <li> <p>Obsession with transparency made early-adopters confident of the recipes they were applying.</p> </li> <li> <p>Responsiveness to feedback. ]</p> </li> </ul> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Preprocessing is a time-consuming effort, requires expertise converging imaging foundations &amp; CS, typically addressed with legacy in-house pipelines.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p>"},{"location":"assets/ORN-Workshop/presentation/#key-aspect-credit-all-direct-contributors","title":"Key aspect: credit all direct contributors","text":"<p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#and-indirect-citation-boilerplate","title":".. and indirect: citation boilerplate.","text":""},{"location":"assets/ORN-Workshop/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p>"},{"location":"assets/ORN-Workshop/presentation/#the-dmriprep-story","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, some neuroimagers asked \"when a diffussion MRI fMRIPrep?\"</p>"},{"location":"assets/ORN-Workshop/presentation/#neurostarsorg","title":"NeuroStars.org","text":"<p>(please note this down)</p> <p>--</p> <p>Same situation in the field of diffusion MRI:</p>"},{"location":"assets/ORN-Workshop/presentation/#image-processing-possible-guidelines-for-the-standardization-clinical-applications-j-veraart","title":"Image Processing: Possible Guidelines for the Standardization &amp; Clinical Applications (J. Veraart)","text":"<p>(https://www.ismrm.org/19/program_files/MIS15.htm)</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#please-join","title":"Please join!","text":"<p>Joseph, M.; Pisner, D.; Richie-Halford, A.; Lerma-Usabiaga, G.; Keshavan, A.; Kent, JD.; Cieslak, M.; Poldrack, RA.; Rokem, A.; Esteban, O.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#wwwniprepsorg_2","title":"www.nipreps.org","text":""},{"location":"assets/ORN-Workshop/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/ORN-Workshop/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/ORN-Workshop/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/ORN-Workshop/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/ORN-Workshop/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/ORN-Workshop/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/ORN-Workshop/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/ORN-Workshop/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/ORN-Workshop/presentation/#nibabies-fmriprep-babies","title":"NiBabies | fMRIPrep-babies","text":"<ul> <li>Mathias Goncalves</li> </ul>"},{"location":"assets/ORN-Workshop/presentation/#nirodents-fmriprep-rodents","title":"NiRodents | fMRIPrep-rodents","text":"<ul> <li>Eilidh MacNicol</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p>"},{"location":"assets/ORN-Workshop/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p>"},{"location":"assets/ORN-Workshop/presentation/#the-nmind-story","title":"The NMiND story","text":"<p>NMiND = NeverMIND, this Neuroimaging Method Is Not Duplicated</p>"},{"location":"assets/ORN-Workshop/presentation/#pis-worried-about-methodological-duplicity","title":"PIs worried about methodological duplicity","text":"<p>M. Milham, D. Fair, T. Satterthwaite, S. Ghosh, R. Poldrack, etc.</p> <p>--</p>"},{"location":"assets/ORN-Workshop/presentation/#nminds-workgroups","title":"NMiND's workgroups","text":"<p>nosology group, coding standards &amp; patterns, sharing standards, testing standards, crediting contributors, funding strategy, benchmarking datasets.</p>"},{"location":"assets/ORN-Workshop/presentation/#nminds-nosology-goals","title":"NMiND's nosology goals","text":"<ul> <li>Consensus glossary of terms</li> <li>Landscape the portfolio of methodological solutions along several experimental and computational dimensions</li> <li>Organize and document a taxonomy along those dimensions</li> <li>Index existing software (from unit methods to workflows) in the taxonomy</li> </ul> <p>Please Join!</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/ORN-Workshop/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/ORN-Workshop/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"assets/bhd2020/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"NiPreps | NeuroImaging PREProcessing toolS","text":""},{"location":"assets/bhd2020/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/bhd2020/presentation/#chuv-lausanne-university-hospital","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorgassetsbhd2020","title":"www.nipreps.org/assets/bhd2020","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools_1","title":"NiPreps | NeuroImaging PREProcessing toolS","text":""},{"location":"assets/bhd2020/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/bhd2020/presentation/#chuv-lausanne-university-hospital_1","title":"CHUV | Lausanne University Hospital","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorgassetsbhd2020_1","title":"www.nipreps.org/assets/bhd2020","text":"<p>]</p> <p>???</p>"},{"location":"assets/bhd2020/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/bhd2020/presentation/#bhd2020","title":"BHD2020","text":""},{"location":"assets/bhd2020/presentation/#day-2-14h-cet","title":"(Day 2, 14h CET)","text":""},{"location":"assets/bhd2020/presentation/#nipreps","title":"NiPreps","text":"<p>]</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/bhd2020/presentation/#bhd2020_1","title":"BHD2020","text":""},{"location":"assets/bhd2020/presentation/#day-2-14h-cet_1","title":"(Day 2, 14h CET)","text":""},{"location":"assets/bhd2020/presentation/#nipreps_1","title":"NiPreps","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/bhd2020/presentation/#outlook","title":"Outlook","text":""},{"location":"assets/bhd2020/presentation/#1-understand-what-preprocessing-is-from-fmri","title":"1. Understand what preprocessing is - from fMRI","text":""},{"location":"assets/bhd2020/presentation/#2-the-fmriprep-experience","title":"2. The fMRIPrep experience","text":""},{"location":"assets/bhd2020/presentation/#3-the-dmriprep-experience","title":"3. The dMRIPrep experience","text":""},{"location":"assets/bhd2020/presentation/#4-importance-of-the-visual-reports","title":"4. Importance of the visual reports","text":""},{"location":"assets/bhd2020/presentation/#5-introducing-nipreps","title":"5. Introducing NiPreps","text":""},{"location":"assets/bhd2020/presentation/#6-open-forum-first-steps-and-contributing","title":"6. Open forum: first steps and contributing","text":""},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-nowadays","title":"The research workflow of functional MRI (nowadays)","text":"<p>(source: next slide)</p>"},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-2006","title":"The research workflow of functional MRI (2006)","text":"<p>(Strother, 2006; 10.1109/MEMB.2006.1607667)</p>"},{"location":"assets/bhd2020/presentation/#the-research-workflow-of-functional-mri-ab","title":"The research workflow of functional MRI (a.B.<sup>*</sup>)","text":"<p>Adapted (Strother, 2006)</p> <p><sup>*</sup>a.B. = after BIDS (Brain Imaging Data Structure; Gorgolewski et al. (2016))</p>"},{"location":"assets/bhd2020/presentation/#neuroimaging-is-now-mature","title":"Neuroimaging is now mature","text":"<ul> <li>many excellent tools available (from specialized to foundational)</li> <li>large toolboxes (AFNI, ANTs/ITK, FreeSurfer, FSL, Nilearn, SPM, etc.)</li> <li>workflow software (Nipype, Shellscripts, Nextflow, CWL)</li> <li> <p>container technology, CI/CD</p> </li> <li> <p>a wealth of prior knowledge (esp. about humans)</p> </li> <li> <p>LOTS of data acquired everyday</p> </li> </ul>"},{"location":"assets/bhd2020/presentation/#bids-a-thrust-of-technology-driven-development","title":"BIDS - A thrust of technology-driven development","text":"<ul> <li> <p>A uniform and complete interface to data:</p> </li> <li> <p>Uniform: enables the workflow adapt to the data</p> </li> <li> <p>Complete: enables validation and minimizes human-intervention</p> </li> <li> <p>Extensible reproducibility:</p> </li> <li> <p>BIDS-Derivatives</p> </li> <li>BIDS-Apps (Gorgolewski et al., 2017)</li> </ul> <p>???</p> <ul> <li>researchers have a large portfolio of image processing components readily available</li> <li>toolboxes with great support and active maintenance:</li> </ul>"},{"location":"assets/bhd2020/presentation/#new-questions-changing-the-focus","title":"New questions changing the focus:","text":""},{"location":"assets/bhd2020/presentation/#-validity-does-the-workflow-actually-work-out","title":"- validity (does the workflow actually work out?)","text":""},{"location":"assets/bhd2020/presentation/#-transparency-is-it-a-black-box-how-precise-is-reporting","title":"- transparency (is it a black-box? how precise is reporting?)","text":""},{"location":"assets/bhd2020/presentation/#-vibration-how-each-tool-choice-parameters-affect-overall","title":"- vibration (how each tool choice &amp; parameters affect overall?)","text":""},{"location":"assets/bhd2020/presentation/#-throughput-how-much-datatime-can-it-possible-take","title":"- throughput (how much data/time can it possible take?)","text":""},{"location":"assets/bhd2020/presentation/#-robustness-can-i-use-it-on-diverse-studies","title":"- robustness (can I use it on diverse studies?)","text":""},{"location":"assets/bhd2020/presentation/#-evaluation-what-is-it-unique-about-the-workflow-wrt-existing-alternatives","title":"- evaluation (what is it unique about the workflow, w.r.t. existing alternatives?)","text":""},{"location":"assets/bhd2020/presentation/#the-garden-of-forking-paths","title":"The garden of forking paths","text":"<p>(Botvinik-Nezer et al., 2020)</p> <p>Around 50% of teams used fMRIPrep'ed inputs.</p>"},{"location":"assets/bhd2020/presentation/#the-fmriprep-story","title":"The fMRIPrep story","text":""},{"location":"assets/bhd2020/presentation/#fmriprep-produces-analysis-ready-data-from-diverse-data","title":"fMRIPrep produces analysis-ready data from diverse data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> <li>robust against inhomogeneity of data across studies</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p>"},{"location":"assets/bhd2020/presentation/#fmriprep-was-not-originally-envisioned-as-a-community-project","title":"fMRIPrep was not originally envisioned as a community project ...","text":"<p>(we just wanted a robust tool to automatically preprocess incoming data of OpenNeuro.org)</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#but-a-community-built-up-quickly-around-it","title":"... but a community built up quickly around it","text":"<p>--</p> <p>.pull-left[</p>"},{"location":"assets/bhd2020/presentation/#why","title":"Why?","text":"<ul> <li> <p>Preprocessing of fMRI was in need for division of labor.</p> </li> <li> <p>Obsession with transparency made early-adopters confident of the recipes they were applying.</p> </li> <li> <p>Responsiveness to feedback. ]</p> </li> </ul> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Preprocessing is a time-consuming effort, requires expertise converging imaging foundations &amp; CS, typically addressed with legacy in-house pipelines.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p>"},{"location":"assets/bhd2020/presentation/#key-aspect-credit-all-direct-contributors","title":"Key aspect: credit all direct contributors","text":"<p>--</p>"},{"location":"assets/bhd2020/presentation/#and-indirect-citation-boilerplate","title":".. and indirect: citation boilerplate.","text":""},{"location":"assets/bhd2020/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p> <p> </p> <p> (Esteban et al., 2019) </p>"},{"location":"assets/bhd2020/presentation/#the-dmriprep-story","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, Dr. A. Keshavan asked \"when a dMRIPrep?\"</p>"},{"location":"assets/bhd2020/presentation/#neurostarsorg","title":"NeuroStars.org","text":"<p>(please note this down)</p>"},{"location":"assets/bhd2020/presentation/#the-dmriprep-story_1","title":"The dMRIPrep story","text":"<p>After the success of fMRIPrep, Dr. A. Keshavan asked \"when a dMRIPrep?\"</p> <p> </p> <p>Image Processing: Possible Guidelines for the Standardization &amp; Clinical Applications</p> <p>(Veraart, 2019)</p>"},{"location":"assets/bhd2020/presentation/#please-join","title":"Please join!","text":"<p>Joseph, M.; Pisner, D.; Richie-Halford, A.; Lerma-Usabiaga, G.; Keshavan, A.; Kent, JD.; Veraart, J.; Cieslak, M.; Poldrack, RA.; Rokem, A.; Esteban, O.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#understanding-what-preprocessing-is-with-visual-reports","title":"Understanding what preprocessing is with visual reports","text":"<p>]</p>"},{"location":"assets/bhd2020/presentation/#the-individual-report","title":"The individual report","text":"<p>???</p> <p>Let's walk through one example of report. Reports have several sections, starting with a summary indicating the particularities of this dataset and workflow choices made based on the input data.</p> <p>The anatomical section follows with several visualizations to assess the anatomical processing steps mentioned before, spatial normalization to template spaces (the flickering panel helps assess alignment) and finally surface reconstruction.</p> <p>Then, all functional runs are concatenated, and all show the same structure. After an initial summary of this particular run, the alignment to the same subject's anatomical image is presented, with contours of the white and pial surfaces as cues. Next panel shows the brain mask and ROIs utilized by the CompCor denoising. For each run we then find some visualizations to assess the generated confounding signals.</p> <p>After all functional runs are presented, the About section keeps information to aid reproducibility of results, such as the software's version, or the exact command line run.</p> <p>The boilerplate is found next, with a text version shown by default and tabs to convert to Markdown and LaTeX.</p> <p>Reports conclude with a list of encountered errors (if any).</p>"},{"location":"assets/bhd2020/presentation/#reports-are-a-crucial-element-to-ensure-transparency","title":"Reports are a crucial element to ensure transparency","text":"<p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p>.distribute[ fMRIPrep generates one participant-wide report after execution.</p> <p>Reports describe the data as found, and the steps applied (providing .blue[visual support to look inside the box]):</p> <ol> <li> <p>show researchers their data;</p> </li> <li> <p>show how fMRIPrep interpreted the data (describing the actual preprocessing steps);</p> </li> <li> <p>quality control of results, facilitating early error detection. ] ]</p> </li> </ol> <p>???</p> <p>Therefore, reports have become a fundamental feature of fMRIPrep because they not only allow assessing the quality of the processing, but also provide an insight about the logic supporting such processing.</p> <p>In other words, reports help respond to the what was done and the why was it done in addition to the how well it did.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":""},{"location":"assets/bhd2020/presentation/#nipreps-neuroimaging-preprocessing-tools_2","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/bhd2020/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/bhd2020/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/bhd2020/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/bhd2020/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/bhd2020/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/bhd2020/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/bhd2020/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/bhd2020/presentation/#nibabies-fmriprep-babies","title":"NiBabies | fMRIPrep-babies","text":"<ul> <li>Mathias Goncalves</li> </ul>"},{"location":"assets/bhd2020/presentation/#nirodents-fmriprep-rodents","title":"NiRodents | fMRIPrep-rodents","text":"<ul> <li>Eilidh MacNicol</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p>"},{"location":"assets/bhd2020/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/bhd2020/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#where-to-start","title":"Where to start?","text":""},{"location":"assets/bhd2020/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":""},{"location":"assets/bhd2020/presentation/#githubcomnipreps","title":"github.com/nipreps","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/bhd2020/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/bhd2020/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"assets/torw2020/presentation/","title":"Presentation","text":"<p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#building-next-generation-preprocessing-pipelines","title":"Building next-generation preprocessing pipelines:","text":""},{"location":"assets/torw2020/presentation/#the-fmriprep-experience","title":"the fMRIPrep experience","text":""},{"location":"assets/torw2020/presentation/#o-esteban","title":"O. Esteban","text":""},{"location":"assets/torw2020/presentation/#center-for-reproducible-neuroscience","title":"Center for Reproducible Neuroscience","text":""},{"location":"assets/torw2020/presentation/#stanford-university","title":"Stanford University","text":""},{"location":"assets/torw2020/presentation/#wwwniprepsorg","title":"www.nipreps.org","text":"<p>]</p> <p>layout: false count: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#building-next-generation-preprocessing-pipelines_1","title":"Building next-generation preprocessing pipelines:","text":""},{"location":"assets/torw2020/presentation/#the-fmriprep-experience_1","title":"the fMRIPrep experience","text":""},{"location":"assets/torw2020/presentation/#o-esteban_1","title":"O. Esteban","text":""},{"location":"assets/torw2020/presentation/#center-for-reproducible-neuroscience_1","title":"Center for Reproducible Neuroscience","text":""},{"location":"assets/torw2020/presentation/#stanford-university_1","title":"Stanford University","text":""},{"location":"assets/torw2020/presentation/#wwwniprepsorg_1","title":"www.nipreps.org","text":"<p>]</p> <p>???</p>"},{"location":"assets/torw2020/presentation/#im-going-to-talk-about-how-we-are-building-a-framework-of-preprocessing-pipelines-for-neuroimaging-called-nipreps-based-on-the-fmriprep-experience","title":"I'm going to talk about how we are building a framework of preprocessing pipelines for neuroimaging called NiPreps, based on the fMRIPrep experience.","text":"<p>name: newsection layout: true class: section-separator</p> <p>.perma-sidebar[</p>"},{"location":"assets/torw2020/presentation/#torw2020","title":"TORW2020","text":""},{"location":"assets/torw2020/presentation/#talk-12","title":"Talk 12","text":""},{"location":"assets/torw2020/presentation/#nipreps","title":"NiPreps","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#introducing-fmriprep","title":"Introducing fMRIPrep","text":"<p>]</p> <p>???</p> <p>Let's begin with some of the history behind fMRIPrep.</p> <p>name: sidebar layout: true</p> <p>.perma-sidebar[</p>"},{"location":"assets/torw2020/presentation/#torw2020_1","title":"TORW2020","text":""},{"location":"assets/torw2020/presentation/#talk-12_1","title":"Talk 12","text":""},{"location":"assets/torw2020/presentation/#nipreps_1","title":"NiPreps","text":"<p>]</p> <p>template: sidebar</p>"},{"location":"assets/torw2020/presentation/#fmriprep-produces-analysis-ready-data-from-acquired-fmri-data","title":"fMRIPrep produces analysis-ready data from acquired (fMRI) data","text":"<ul> <li>minimal requirements (BIDS-compliant);</li> <li>agnostic to downstream steps of the workflow</li> <li>produces BIDS-Derivatives;</li> </ul> <p>???</p> <p>fMRIPrep takes in a task-based or resting-state functional MRI dataset in BIDS-format and returns preprocessed data ready for analysis.</p> <p>Preprocessed data can be used for a broad range of analysis, and they are formatted following BIDS-Derivatives to maximize compatibility with:   * major software packages (AFNI, FSL, SPM*, etc.)   * further temporal filtering and denoising: fMRIDenoise   * any BIDS-Derivatives compliant tool (e.g., FitLins).</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-a-bids-app-gorgolewski-et-al-2017","title":"fMRIPrep is a BIDS-App (Gorgolewski, et al. 2017)","text":"<ul> <li>adhered to modern software-engineering standards (CI/CD, containers)</li> <li>compatible interface with other BIDS-Apps</li> <li>optimized for automatic execution</li> </ul> <p>???</p> <p>fMRIPrep adopts the BIDS-App specifications. That means the software is tested with every change to the codebase, it also means that packaging, containerization, and deployment are also automated and require tests to be passing. BIDS-Apps are inter-operable (via BIDS-Derivatives), and optimized for execution in HPC, Cloud, etc.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#minimizes-human-intervention","title":"Minimizes human intervention","text":"<ul> <li>avoid error-prone parameters settings (read them from BIDS)</li> <li>adapts the workflow to the actual data available</li> <li>while remaining flexible to some design choices (e.g., whether or not reconstructing surfaces or customizing target normalized standard spaces)</li> </ul> <p>???</p> <p>fMRIPrep minimizes human intervention because the user does not need to fiddle with any parameters - they are obtained from the BIDS structure. However, fMRIPrep does allow some flexibility to ensure the preprocessing meets the requirements of the intended analyses.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#fmriprep-bundles-many-tools-afni-fsl-freesurfer-nilearn-etc","title":"fMRIPrep bundles many tools (AFNI, FSL, FreeSurfer, Nilearn, etc.)","text":"<ul> <li>(do not reinvent the wheel)</li> </ul> <p>???</p> <p>Finally, fMRIPrep sits on top of giants' shoulders: AFNI, FSL, FreeSurfer, Nilearn, etc. all implement methods very well backed-up and are thoroughly tested on their own.</p>"},{"location":"assets/torw2020/presentation/#we-started-fmriprep-in-february-2016","title":"We started fMRIPrep in February 2016","text":""},{"location":"assets/torw2020/presentation/#objectives","title":"Objectives:","text":"<ul> <li>Develop an fMRI preprocessing tool enforcing BIDS for the inputs</li> <li>Automatically executable within OpenNeuro</li> </ul>"},{"location":"assets/torw2020/presentation/#initially-inspired-by-hcp-pipelines","title":"Initially inspired by HCP Pipelines","text":"<ul> <li>Problem: robustness vs. the wide variability of inputs</li> </ul> <p>???</p> <p>We began working on fMRIPrep back in 2016 with much more humble expectations: - We needed to develop an fMRI preprocessing tool leveraging BIDS - smart enough to adapt the workflow for the input dataset, - and the tool should be executable in OpenNeuro without human intervention.</p> <p>Please note that at the time, the BIDS-Apps specification didn't exist yet.</p> <p>We started out with an eye on HCP Pipelines, and soon identified that datasets in OpenNeuro varied extremely in terms of acquisition protocols and imaging parameters, which is definitely not a problem for HCP Pipelines, which has very specific requirements for the inputs.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-adoption-and-popularization-brought-new-challenges","title":"fMRIPrep adoption and popularization brought new challenges","text":"<p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>With the fast adoption and popularization of fMRIPrep, new challenges surfaced.</p> <p>On the right-hand side, you'll find the chart of unique visitors to fmriprep.org, which is the documentation website.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#transparency-was-addressed-with","title":"Transparency was addressed with:","text":"<ul> <li>the individual reports;</li> <li>the thorough documentation; and</li> <li>the citation boilerplate. ]</li> </ul> <p>???</p> <p>We realized that transparency is indeed a very hard problem. The first leg of our solution was the creation of a solid report system. fMRIPrep generates one individual report per participant, containing information not just to quality control the results, but also to understand the processing flow.</p> <p>We also strived for a comprehensive, thorough documentation.</p> <p>Finally, the so-called citation boilerplate appended to the individual reports describe the actual workflow that has been run, noting all the software that was applied including their versions and references.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#run-to-run-repeatability-is-an-open-issue","title":"Run-to-run repeatability is an open issue:","text":"<ul> <li>computational precautions (e.g., unpredictable float truncation/rounding)</li> <li>keep track of all random seeds (version +20.1) ]</li> </ul> <p>???</p> <p>Reproducibility in terms of run-to-run repeatability of results become as a more apparent problem, and we are always trying to minimize the vibration caused by computational factors, software versions, etc.</p> <p>--</p> <p>.pull-left[</p>"},{"location":"assets/torw2020/presentation/#overwhelming-feedback","title":"Overwhelming feedback:","text":"<ul> <li>massive amounts of bug reports, questioning the robustness</li> <li>organic emergence of fMRIPrep enthusiasts (thanks to E. DuPre, JD. Kent) ]</li> </ul> <p>???</p> <p>We always maintained close attention to all the feedback channels. At some point we were washed over with bug reports that we needed to address. We also started to doubt the robustness against the variability of inputs, and set a thorough stress-test plan using data from OpenNeuro (reported in our Nat Meth paper). Among this feedback flooding, some external friends started to emerge and lent their shoulders in answering questions, fixing bugs, etc.</p> <p>In particular, I want to thank Elizabeth DuPre (McGill) and James Kent (Univ. of Iowa) for being the earliest adopters and contributors.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-stable-today-although-unfinished","title":"fMRIPrep is stable today, although unfinished","text":"<p>(Esteban et al., 2019)</p> <p>???</p> <p>These developments resulted in the following default processing workflow.</p> <p>At the highest level, anatomical preprocessing (left-hand block) and functional preprocessing (right-hand block) can be clearly identified as the largest workflow units.</p> <p>fMRIPrep combines all the anatomical images at the input in one anatomical reference, removes the intensity non-uniformity, delineates brain tissues, reconstructs surfaces, spatially normalizes the anatomical reference to one or more standard spaces.</p> <p>On the functional pathway, a reference is calculated for further processes, then head-motion parameters are estimated (please note head-motion is accounted for in the last resampling step, in combination with other transforms), slice-timing correction is applied if requested.</p> <p>Then, susceptibility distortion is estimated, if sufficient information (in terms of acquisition and metadata) is found in the BIDS structure.</p> <p>Finally, data are mapped to the same individual's anatomical reference and outputs in the several output spaces requested are generated, along with a file gathering time-series of nuisance signals.</p>"},{"location":"assets/torw2020/presentation/#the-individual-report","title":"The individual report","text":"<p>???</p> <p>Let's walk through one example of report. Reports have several sections, starting with a summary indicating the particularities of this dataset and workflow choices made based on the input data.</p> <p>The anatomical section follows with several visualizations to assess the anatomical processing steps mentioned before, spatial normalization to template spaces (the flickering panel helps assess alignment) and finally surface reconstruction.</p> <p>Then, all functional runs are concatenated, and all show the same structure. After an initial summary of this particular run, the alignment to the same subject's anatomical image is presented, with contours of the white and pial surfaces as cues. Next panel shows the brain mask and ROIs utilized by the CompCor denoising. For each run we then find some visualizations to assess the generated confounding signals.</p> <p>After all functional runs are presented, the About section keeps information to aid reproducibility of results, such as the software's version, or the exact command line run.</p> <p>The boilerplate is found next, with a text version shown by default and tabs to convert to Markdown and LaTeX.</p> <p>Reports conclude with a list of encountered errors (if any).</p>"},{"location":"assets/torw2020/presentation/#reports-are-a-crucial-element-to-ensure-transparency","title":"Reports are a crucial element to ensure transparency","text":"<p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p>.distribute[ fMRIPrep generates one participant-wide report after execution.</p> <p>Reports describe the data as found, and the steps applied (providing .blue[visual support to look inside the box]):</p> <ol> <li> <p>show researchers their data;</p> </li> <li> <p>show how fMRIPrep interpreted the data (describing the actual preprocessing steps);</p> </li> <li> <p>quality control of results, facilitating early error detection. ] ]</p> </li> </ol> <p>???</p> <p>Therefore, reports have become a fundamental feature of fMRIPrep because they not only allow assessing the quality of the processing, but also provide an insight about the logic supporting such processing.</p> <p>In other words, reports help respond to the what was done and the why was it done in addition to the how well it did.</p>"},{"location":"assets/torw2020/presentation/#documentation-as-a-second-leg-of-transparency-fmripreporg","title":"Documentation as a second leg of transparency (fmriprep.org)","text":"<ul> <li> <p>Hackathons &amp; docu-sprints</p> </li> <li> <p>the CompCor documentation example</p> </li> </ul> <p> </p> <p>.large[fmriprep.org]</p> <p>???</p> <p>We promptly identified the need for a very comprehensive documentation. The website at fmriprep.org covers a substantial area of how the tool works under the hood and how to best operate it.</p> <p>The documentation turned out to be a great ice breaker for contributors, who have pushed forward fundamental sections of it.</p> <p>Most of the largest increments in documentation are the result of discussions in hackathons, docusprints, neurostars, github, etc. A hallmark example was pull request 1877 by Karolina Finc, who gathered together a massive amount of knowledge from many contributors. Now this is up and open in our documentation website.</p>"},{"location":"assets/torw2020/presentation/#fmriprep-is-more-of-a-community-driven-project-every-day","title":"fMRIPrep is more of a community-driven project every day","text":"<ul> <li> <p>Bug-fixes: we ensured that open feedback channels were attended (GitHub, NeuroStars, mailing list, etc.);</p> </li> <li> <p>users began also proposing new features (some including code!);</p> </li> <li> <p>with NiPreps we are working towards handling the project over to the community.</p> </li> </ul> <p>???</p> <p>To ensure the future sustainability of the project (what some developers call Bus factor), we are transitioning the tool to NiPreps, transferring the large community nurtured over the past four years with it.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#how-does-fmriprep-compensate-its-contributors","title":"How does fMRIPrep compensate its contributors?","text":"<ul> <li>Contributors are invited to coauthor relevant publications about fMRIPrep.</li> <li>Anyone who helps with documentation, code or relevant discussions is a contributor.</li> </ul> <p>.pull-left[</p> <p> </p> <p>]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>In return, beyond the rewards of being part of an open source project, fMRIPrep gives some scientific credit back in the form of publications.</p> <ul> <li>All contributors are invited to coauthor these publications.</li> <li>Anything that helps the project is considered a sufficient contribution.</li> </ul>"},{"location":"assets/torw2020/presentation/#lessons-learned","title":"Lessons learned","text":""},{"location":"assets/torw2020/presentation/#researchers-want-to-spend-more-time-on-those-areas-most-relevant-to-them","title":"Researchers want to spend more time on those areas most relevant to them","text":"<p>(probably not preprocessing...)</p> <p>???</p> <p>With the development of fMRIPrep we understood that researchers don't want to waste their time on preprocessing (except for researchers developing new preprocessing techniques).</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#writing-fmriprep-required-a-team-of-several-experts-in-processing-methods-for-neuroimaging-with-a-solid-base-on-computer-science","title":"Writing fMRIPrep required a team of several experts in processing methods for neuroimaging, with a solid base on Computer Science.","text":"<p>(research programs just can't cover the neuroscience and the engineering of the whole workflow - we need to divide the labor)</p> <p>???</p> <p>The current neuroimaging workflow requires extensive knowledge in sometimes orthogonal fields such as neuroscience and computer science. Dividing the labor in labs, communities or individuals with the necessary expertise is the fundamental for the advance of the whole field.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#transparency-helps-against-the-risk-of-super-easy-tools","title":"Transparency helps against the risk of super-easy tools","text":"<p>(easy-to-use tools are risky because they might get a researcher very far with no idea whatsoever of what they've done)</p> <p>???</p> <p>There is an implicit risk in making things too easy to operate:</p> <p>For instance, imagine someone who runs fMRIPrep on diffusion data by tricking the BIDS naming into an apparently functional MRI dataset. If fMRIPrep reached the end at all, the garbage at the output could be fed into further tools, in a sort of a snowballing problem.</p> <p>When researchers have access to the guts of the software and are given an opportunity to understand what's going on, the risk of misuse dips.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#established-toolboxes-do-not-have-incentives-for-compatibility","title":"Established toolboxes do not have incentives for compatibility","text":"<p>(and to some extent this is not necessarily bad, as long as they are kept well-tested and they embrace/help-develop some minimal standards)</p> <p>???</p> <p>AFNI, ANTs, FSL, FreeSurfer, SPM, etc. have comprehensive software validation tests, methodological validation tests, stress tests, etc. - which pushed up their quality and made them fundamental for the field.</p> <p>Therefore, it is better to keep things that way (although some minimal efforts towards convergence in compatibility are of course welcome)</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#wwwniprepsorg_2","title":"www.nipreps.org","text":""},{"location":"assets/torw2020/presentation/#nipreps-neuroimaging-preprocessing-tools","title":"(NiPreps == NeuroImaging PREProcessing toolS)","text":"<p>]</p> <p>???</p> <p>The enormous success of fMRIPrep led us to propose its generalization to other MRI and non-MRI modalities, as well as nonhuman species (for instance, rodents), and particular populations currently unsupported by fMRIPrep such as infants.</p>"},{"location":"assets/torw2020/presentation/#augmenting-scanners-to-produce-analysis-grade-data","title":"Augmenting scanners to produce \"analysis-grade\" data","text":""},{"location":"assets/torw2020/presentation/#data-directly-consumable-by-analyses","title":"(data directly consumable by analyses)","text":"<p>.pull-left[</p> <p>Analysis-grade data is an analogy to the concept of \"sushi-grade (or sashimi-grade) fish\" in that both are:</p> <p></p> <p>.large[minimally preprocessed,]</p> <p>and</p> <p>.large[safe to consume directly.] ]</p> <p>.pull-right[  ]</p> <p>???</p> <p>The goal, therefore, of NiPreps is to extend the scanner so that, in a way, they produce data ready for analysis.</p> <p>We liken these analysis-grade data to sushi-grade fish, because in both cases the product is minimally preprocessed and at the same time safe to consume as is.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#deconstructing-fmriprep","title":"Deconstructing fMRIPrep","text":"<p> ]</p> <p>???</p> <p>For the last two years we've been decomposing the architecture of fMRIPrep, spinning off its constituent parts that are valuable in other applications.</p> <p>This process of decoupling (to use a proper CS term) has been greatly facilitated by the modular nature of the code since its inception.</p> <p>???</p> <p>The processing elements extracted from fMRIPrep can be mapped to three regimes of responsibility:</p> <ul> <li>Software infrastructure composed by tools ensuring the collaboration and the most basic tooling.</li> <li>Middleware utilities, which build more advanced tooling based on the foundational infrastructure</li> <li>And at the top of the stack end-user applications - namely fMRIPrep, dMRIPrep, sMRIPrep and MRIQC.</li> </ul> <p>As we can see, the boundaries of these three architectural layers are soft and tools such as TemplateFlow may stand in between.</p> <p>Only projects enclosed in the brain shape pertain to the NiPreps community. NiPype, NiBabel and BIDS are so deeply embedded as dependencies that NiPreps can't be understood without them.</p> <p></p> <ul> <li> <p>BIDS provides a standard, guaranteeing I/O agreements:</p> </li> <li> <p>Allows workflows to self-adapt to the inputs</p> </li> <li> <p>Ensures the shareability of the results</p> </li> <li> <p>PyBIDS: a Python tool to query BIDS datasets (Yarkoni et al., 2019):</p> </li> </ul> <pre><code>&gt;&gt;&gt; from bids import BIDSLayout\n\n# Point PyBIDS to the dataset's path\n&gt;&gt;&gt; layout = BIDSLayout(\"/data/coolproject\")\n\n# List the participant IDs of present subjects\n&gt;&gt;&gt; layout.get_subjects()\n['01', '02', '03', '04', '05']\n\n# List session identifiers, if present\n&gt;&gt;&gt; layout.get_sessions()\n['01', '02']\n\n# List functional MRI tasks\n&gt;&gt;&gt; layout.get_tasks()\n['rest', 'nback']\n</code></pre> <p>???</p> <p>BIDS is one of the keys to success for fMRIPrep and consequently, a strategic element of NiPreps.</p> <p>Because the tools so far are written in Python, PyBIDS is a powerful tool to index and query inputs and outputs.</p> <p>The code snippet illustrates the ease to find out the subject identifiers available in the dataset, sessions, and tasks.</p>"},{"location":"assets/torw2020/presentation/#bids-derivatives","title":"BIDS Derivatives","text":"<p>.cut-right[ <pre><code>derivatives/\n\u251c\u2500\u2500 fmriprep/\n\u2502 \u251c\u2500\u2500 dataset_description.json\n\u2502 \u251c\u2500\u2500 logs\n\u2502 \u251c\u2500\u2500 sub-01.html\n\u2502 \u251c\u2500\u2500 sub-01/\n\u2502 \u2502 \u251c\u2500\u2500 anat/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-brain_mask.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_dseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-GM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-WM_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_label-CSF_probseg.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_space-MNI152_desc-preproc_T1w.nii.gz\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-MNI152_to-T1w_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 sub-01_from-T1w_to-MNI152_mode-image_xfm.h5\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 sub-01_from-orig_to-T1w_mode-image_xfm.txt\n\u2502 \u2502 \u251c\u2500\u2500 figures/\n\u2502 \u2502 \u2514\u2500\u2500 func/\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_boldref.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-preproc_bold.nii.gz\n\u2502 \u2502   \u251c\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-confounds_regressors.nii.gz\n\u2502 \u2502   \u2514\u2500\u2500 sub-01_task-rhymejudgment_space-MNI152_desc-brain_mask.nii.gz\n</code></pre> ]</p> <p>???</p> <p>All NiPreps must write out BIDS-Derivatives. As illustrated in the example, the outputs of fMRIPrep are very similar to the BIDS standard for acquired data.</p>"},{"location":"assets/torw2020/presentation/#bids-apps","title":"BIDS-Apps","text":"<ul> <li>BIDS-Apps proposes a workflow structure model:</li> </ul> <ul> <li> <p>Use of containers &amp; CI/CD</p> </li> <li> <p>Uniform interface:   .cut-right[   <pre><code>fmriprep /data /data/derivatives/fmriprep-20.1.1 participant [+OPTIONS]\n</code></pre>   ]</p> </li> </ul> <p>???</p> <p>All end-user applications in NiPreps must conform to the BIDS-Apps specifications.</p> <p>The BIDS-Apps paper identified a common pattern in neuroimaging studies, where individual participants (and runs) are processed first individually, and then based on the outcomes, further levels of data aggregation are executed.</p> <p>For this reason, BIDS-Apps define two major levels of execution: participant and group level.</p> <p>Finally, the paper also stresses the importance of containerizing applications to ensure long-term preservation of run-to-run repeatability and proposes a common command line interface as described at the bottom:</p> <ul> <li>first the name of the BIDS-Apps (fmriprep, in this case)</li> <li>followed by input and output directories (respectively),</li> <li>to finally indicate the analysis level (always participant, for the case of fmriprep)</li> </ul> <p>.pull-left[</p> <p> </p> <p></p> <pre><code>from nipype.interfaces.fsl import BET\nbrain_extract = BET(\n  in_file=\"/data/coolproject/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii\",\n  out_file=\"/out/sub-01/ses-01/anat/sub-01_ses-01_desc-brain_T1w.nii\"\n)\nbrain_extract.run()\n</code></pre> <p>Nipype is the gateway to mix-and-match from AFNI, ANTs, Dipy, FreeSurfer, FSL, MRTrix, SPM, etc. ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>Nipype is the glue stitching together all the underlying neuroimaging toolboxes and provides the execution framework.</p> <p>The snippet shows how the widely known BET tool from FSL can be executed using NiPype. This is a particular example instance of interfaces - which provide uniform access to the tooling with Python.</p> <p>Finally, combining these interfaces we generate processing workflows to fulfill higher level processing tasks.</p> <p></p> <p> </p> <p>???</p> <p>For instance, we may have a look into fMRIPrep's functional processing block.</p> <p>Nipype helps understand (and opens windows in the black box) generating these graph representation of the workflow.</p> <p></p> <pre><code>\"\"\"Fix the affine of a rodent dataset, imposing 0.2x0.2x0.2 [mm].\"\"\"\nimport numpy as np\nimport nibabel as nb\n\n# Open the file\nimg = nb.load(\"sub-25_MGE_MouseBrain_3D_MGE_150.nii.gz\")\n\n# New (correct) affine\naff = np.diag((-0.2, -0.2, 0.2, 1.0))\n\n# Use nibabel to reorient to canonical\ncard = nb.as_closest_canonical(nb.Nifti1Image(\n    img.dataobj,\n    np.diag((-0.2, -0.2, 0.2, 1.0)),\n    None\n))\n\n# Save to disk\ncard.to_filename(\"sub-25_T2star.nii.gz\")\n</code></pre> <p>???</p> <p>NiBabel allows Python to easily access neuroimaging data formats such as NIfTI, GIFTI and CIFTI2.</p> <p>Although this might be a trivial task, the proliferation of neuroimaging software has led to some sort of Wild West of formats, and sometimes interoperation is not ensured.</p>"},{"location":"assets/torw2020/presentation/#in-the-snippet-we-can-see-how-we-can-manipulate-the-orientation-headers-of-a-nifti-volume-in-particular-a-rodent-image-with-incorrect-affine-information","title":"In the snippet, we can see how we can manipulate the orientation headers of a NIfTI volume, in particular a rodent image with incorrect affine information.","text":"<p>.pull-left[</p> <p> </p> <p> </p> <p>Transforms typically are the outcome of image registration methodologies</p> <p></p> <p>The proliferation of software implementations of image registration methodologies has resulted in a spread of data structures and file formats used to preserve and communicate transforms.</p> <p>(Esteban et al., 2020) ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>NiTransforms is a super-interesting toy project where we are exercising our finest coding skills. It completes NiBabel in the effort of making spatial transforms calculated by neuroimaging software tools interoperable.</p> <p>When it goes beyond the alpha state, it is expected to be merged into NiBabel.</p> <p>At the moment, NiTransforms is already integrated in fMRIPrep +20.1 to concatenate LTA (linear affine transforms) transforms obtained with FreeSurfer, ITK transforms obtained with ANTs, and motion parameters estimated with FSL.</p> <p>Compatibility across formats is hard due to the many arbitrary decisions in establishing the mathematical framework of the transform and the intrinsic confusion of applying a transform.</p> <p>While intuitively we understand applying a transform as \"transforming the moving image so that I can represent it overlaid or fused with the reference image and both should look aligned\", in reality, we only transform coordinates from the reference image into the moving image's space (step 1 on the right).</p> <p>Once we know where the center of every voxel of the reference image falls in the moving image coordinate system, we read in the information (in other words, a value) from the moving image. Because the location will probably be off-grid, we interpolate such a value from the neighboring voxels (step 2).</p> <p>Finally (step 3) we generate a new image object with the structure of the reference image and the data interpolated from the moving information. This new image object is the moving image \"moved\" on to the reference image space and thus, both look aligned.</p> <p>.pull-left[</p> <p> </p> <ul> <li>The Archive (right) is a repository of templates and atlases</li> <li>The Python Client (bottom) provides easy access (with lazy-loading) to the Archive</li> </ul> <pre><code>&gt;&gt;&gt; from templateflow import api as tflow\n&gt;&gt;&gt; tflow.get(\n...     'MNI152NLin6Asym',\n...     desc=None,\n...     resolution=1,\n...     suffix='T1w',\n...     extension='nii.gz'\n... )\nPosixPath('/templateflow_home/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz')\n</code></pre> <p>.large[www.templateflow.org] ]</p> <p>.pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>One of the most ancient feature requests received from fMRIPrep early adopters was improving the flexibility of spatial normalization to standard templates other than fMRIPrep's default.</p> <p>For instance, infant templates.</p> <p>TemplateFlow offers an Archive of templates where they are stored, maintained and re-distributed;</p> <p>and a Python client that helps accessing them.</p> <p>On the right hand side, an screenshot of the TemplateFlow browser shows some of the templates currently available in the repository. The browser can be reached at www.templateflow.org.</p> <p>The tool is based on PyBIDS, and the snippet will surely remind you of it. In this case the example shows how to obtain the T1w template corresponding to FSL's MNI space, at the highest resolution.</p> <p>If the files requested are not in TemplateFlow's cache, they will be pulled down and kept for further utilization.</p>"},{"location":"assets/torw2020/presentation/#templateflow-archive","title":"TemplateFlow - Archive","text":"<p>.small[(Ciric et al. 2020, in prep)]</p> <p>???</p> <p>The Archive allows a rich range of data and metadata to be stored with the template.</p> <p>Datatypes in the repository cover:</p> <ul> <li>images containing population-average templates,</li> <li>masks (for instance brain masks),</li> <li>atlases (including parcellations and segmentations)</li> <li>transform files between templates</li> </ul> <p>Metadata can be stored with the usual BIDS options.</p> <p>Finally, templates allow having multiple cohorts, in a similar encoding to that of multi-session BIDS datasets.</p> <p>Multiple cohorts are useful, for instance, in infant templates with averages at several gestational ages.</p> <p></p> <p> </p> <p>NiWorkflows is a miscellaneous mixture of tooling used by downstream NiPreps:</p> <p>???</p> <p>NiWorkflows is, historically, the first component detached from fMRIPrep.</p> <p>For that reason, its scope and vision has very fuzzy boundaries as compared to the other tools.</p> <p>The most relevant utilities incorporated within NiWorkflows are:</p> <p>--</p> <ul> <li>The reportlet aggregation and individual report generation system</li> </ul> <p>???</p> <p>First, the individual report system which aggregates the visual elements or the reports (which we call \"reportlets\") and generates the final HTML document.</p> <p>Also, most of the engineering behind the generation of these reportlets and their integration within NiPype are part of NiWorkflows</p> <p>--</p> <ul> <li>Custom extensions to NiPype interfaces</li> </ul> <p>???</p> <p>Beyond the extension of NiPype to generate a reportlet from any given interface, NiWorkflows is the test bed for many utilities that are then upstreamed to nipype.</p> <p>Also, special interfaces with a limited scope that should not be included in nipype are maintained here.</p> <p>--</p> <ul> <li>Workflows useful across applications</li> </ul> <p>???</p> <p>Finally, NiWorkflows indeed offers workflows that can be used by end-user NiPreps. For instance atlas-based brain extraction of anatomical images, based on ANTs.</p> <p></p> <p>???</p> <p>Echo-planar imaging (EPI) are typically affected by distortions along the phase encoding axis, caused by the perturbation of the magnetic field at tissue interfaces.</p> <p>Looking at the reportlet, we can see how in the \"before\" panel, the image is warped.</p> <p>The distortion is most obvious in the coronal view (middle row) because this image has posterior-anterior phase encoding.</p> <p>Focusing on the changes between \"before\" and \"after\" correction in this coronal view, we can see how the blue contours delineating the corpus callosum fit better the dark shade in the data after correction.</p>"},{"location":"assets/torw2020/presentation/#sdcflows-as-integrated-in-fmriprep","title":"SDCFlows, as integrated in fMRIPrep","text":"<p>.left-column3[</p> <p> </p> <p>]</p> <p>.right-column3[ * Hierarchy of SDC methods:   1. PE-Polar   2. Fieldmap   3. Fieldmap-less</p> <ul> <li>Arguments:</li> <li><code>--use-syn-sdc</code></li> <li><code>--force-syn</code></li> <li> <p><code>--ignore fieldmaps</code></p> </li> <li> <p>REQUIRES (opts. 1 or 2): setting the <code>IntendedFor</code> metadata field of fieldmaps. ]</p> </li> </ul> <p>???</p> <p>With SDCFlows, fMRIPrep implements a rather sophisticated pipeline for the estimation of susceptibility distortions.</p> <p>Depending on whether the input dataset contains EPI images with opposed phase encoding polarities (the so-called PE-Polar correction), fieldmaps (as Gradient Recalled Echo sequences) or the fieldmap-less estimation is requested,</p> <p>then SDCFlows establishes a hierarchy of corrections.</p> <p>After correction, we are interested in assessing that low-frequency distortions have been accounted for and that high-frequency (with extreme regions suffering severe drop-outs) are not excessively present.</p> <p>.pull-left[</p> <p> </p> <p>] .pull-right[</p> <p> </p> <p>]</p> <p>???</p> <p>sMRIPrep corresponds to the split of the anatomical preprocessing workflow originally proposed with fMRIPrep.</p> <p>With the support of TemplateFlow, the tool now supports spatial normalization to one or more templates found in the TemplateFlow Archive.</p> <p>It also supports the use of custom templates, whenever they are correctly installed in the templateflow's cache folder.</p> <p></p> <p> </p> <p> </p> <p> </p> <p>???</p> <p>dMRIPrep and fMRIPrep are, of course the tip of the iceberg.</p> <p>dMRIPrep is still in an alpha state, steadily progressing through the path fMRIPrep has delineated for NiPreps.</p> <p>Hopefully, at this point of the talk fMRIPrep doesn't need further description.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#other-components-of-nipreps","title":"Other components of NiPreps","text":"<p>]</p> <p>???</p> <p>Some additional components of NiPreps were never part of fMRIPrep's codebase, or they have been started recently.</p> <p> </p> <p></p> <p> </p> <p></p> <p> </p> <p>???</p> <p>Such is the case of the quality control tools.</p> <p>MRIQC produces visual reports for the efficient screening of acquired (meaning, unprocessed) data - in particular anatomical and functional MRI of the human brain.</p> <p>CrowdMRI is an internet service where anonimized quality control metrics are uploaded automatically as they are computed by MRIQC.</p> <p>The endgoal is to gather enough data to describe the normative distribution of these metrics across image parameters and scanning devices and sites.</p> <p>Finally, MRIQCnets encloses several machine learning projects regarding the quality of acquired images.</p>"},{"location":"assets/torw2020/presentation/#upcoming-new-utilities","title":"Upcoming new utilities","text":""},{"location":"assets/torw2020/presentation/#nibabies","title":"NiBabies","text":"<ul> <li>Recently started, covering infant MRI brain-extraction for now (Mathias Goncalves)</li> </ul>"},{"location":"assets/torw2020/presentation/#nirodents","title":"NiRodents","text":"<ul> <li>Recently started, covering rodent MRI brain-extraction for now (Eilidh MacNicol)</li> </ul> <p>???</p> <p>So, what's coming up next?</p> <p>NiBabies is some sort of NiWorkflows equivalent for the preprocessing of infant imaging. At the moment, only atlas-based brain extraction using ANTs (and adapted from NiWorkflows) is in active developments.</p> <p>Next steps include brain tissue segmentation.</p> <p>Similarly, NiRodents is the NiWorkflows parallel for the prepocessing of rodent preclinical imaging. Again, only atlas-based brain extraction adapted from NiWorkflows is being developed.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#future-lines","title":"Future lines","text":"<ul> <li> <p>fMRIPrep-babies</p> </li> <li> <p>fMRIPrep-rodents</p> </li> <li> <p>MolPrep / PETPrep ?</p> </li> </ul> <p>???</p> <p>In a mid-term future, both NiBabies and NiRodents should allow the extension of fMRIPrep to these new two idiosyncratic data families.</p> <p>In additions, plans for a molecular imaging or PET preprocessing NiPrep are being designed.</p>"},{"location":"assets/torw2020/presentation/#conclusion","title":"Conclusion","text":""},{"location":"assets/torw2020/presentation/#nipreps-is-a-framework-for-the-development-of-preprocessing-workflows","title":"NiPreps is a framework for the development of preprocessing workflows","text":"<ul> <li>Principled design, with BIDS as an strategic component</li> <li>Leveraging existing, widely used software</li> <li>Using NiPype as a foundation</li> </ul> <p>???</p> <p>To wrap-up, I've presented NiPreps, a framework for developing preprocessing workflows inspired by fMRIPrep.</p> <p>The framework is heavily principle and tags along BIDS as a foundational component</p> <p>NiPreps should not reinvent any wheel, trying to reuse as much as possible of the widely used and tested existing software.</p> <p>Nipype serves as a glue components to orchestrate workflows.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#why-preprocessing","title":"Why preprocessing?","text":"<ul> <li>We propose to consider preprocessing as part of the image acquisition and reconstruction</li> <li>When setting the boundaries that way, it seems sensible to pursue some standardization in the preprocessing:</li> <li>Less experimental degrees of freedom for the researcher</li> <li>Researchers can focus on the analysis</li> <li>More homogeneous data at the output (e.g., for machine learning)</li> <li>How:</li> <li>Transparency is key to success: individual reports and documentation (open source is implicit).</li> <li>Best engineering practices (e.g., containers and CI/CD)</li> </ul> <p>???</p> <p>But why just preprocessing, with a very strict scope?</p> <p>We propose to think about preprocessing as part of the image acquisition and reconstruction process (in other words, scanning), rather than part of the analysis workflow.</p> <p>This decoupling from analysis comes with several upshots:</p> <p>First, there are less moving parts to play with for researchers in the attempt to fit their methods to the data (instead of fitting data with their methods).</p> <p>Second, such division of labor allows the researcher to use their time in the analysis.</p> <p>Finally, two preprocessed datasets from two different studies and scanning sites should be more homogeneous when processed with the same instruments, in comparison to processing them with idiosyncratic, lab-managed, preprocessing workflows.</p> <p>However, for NiPreps to work we need to make sure the tools are transparent.</p> <p>Not just with the individual reports and thorough documentation, also because of the community driven development. For instance, the peer-review process that goes around large incremental changes is fundamental to ensure the quality of the tool.</p> <p>In addition, best engineering practices suggested in the BIDS-Apps paper, along with those we have been including with fMRIPrep, are necessary to ensure the quality of the final product.</p> <p>--</p>"},{"location":"assets/torw2020/presentation/#challenges","title":"Challenges","text":"<ul> <li>Testing / Validation!</li> </ul> <p>???</p> <p>As an open problem, validating the results of the tool remains extremely challenging for the lack in gold standard datasets that can tell us the best possible outcome.</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#open-phd-student-position","title":"Open PhD student position!","text":"<p>]</p> <p>template: newsection layout: false</p> <p>.middle.center[</p>"},{"location":"assets/torw2020/presentation/#thanks","title":"Thanks!","text":""},{"location":"assets/torw2020/presentation/#questions","title":"Questions?","text":"<p>]</p>"},{"location":"community/","title":"Join the NiPreps Community","text":"<p>One of the pillars of fMRIPrep, the seed project for NiPreps, has been nurturing an open-source community. Building Welcoming Communities is crucial for open-source software because of several reasons:</p> <ul> <li> <p>Engaging users and contributors (in a very liberal sense, not just with code)     helps establish a development road-map:</p> <ul> <li>In the case of fMRIPrep, many users have reported bugs via our issue     tracker and Neurostars.org.     Even though testing is one of the primary focuses for fMRIPrep, without these     bug-report contributions the tool would have never reached the dependability level     it requires to serve its purpose.</li> <li>Users identify and propose new features, often illuminating shady areas the     most involved developers did not find time or the right context to explore.</li> </ul> </li> <li> <p>The community exposes the software and also increases the externality of the software.     The neuroimaging discussion supported by Neurostars.org     has been a key factor for the adoption of fMRIPrep.</p> </li> <li> <p>Users always give back, and it is not uncommon to see elaborate responses     to bug-reports and questions about fMRIPrep on Neurostars.org     by users who had similar questions previously.</p> </li> </ul> <p>Because of the scientific purpose of NiPreps, there is one more fundamental reason to grow a (scientific) community around the tools: rigor/scrutiny. As one reviews a few of the most discussed pull-requests to fMRIPrep, very soon they realize that we don't just need to get the code right. We strive for integrating high-quality code, but even more importantly, that code must get the scientific method it implements right. This is particularly difficult because in most of the cases there aren't test oracles (in software engineering terms) or gold-standards (in scientific terms) to efficiently evaluate the validity of new features (even to exercise a minuscule area of the domain of inputs). The redundancy of expert eyes looking at our code has only helped make it better.</p>"},{"location":"community/#current-members-of-the-github-organization","title":"Current members of the GitHub organization","text":"<p>A total of 100 neuroimagers have already joined us. Becoming a member will give you access to additional forums for discussion,  subscribing notifications for events and meetings, etc. You can request you are added to the organization by creating a new issue here.</p> <p> </p>"},{"location":"community/CODE_OF_CONDUCT/","title":"NiPreps Code of Conduct","text":""},{"location":"community/CODE_OF_CONDUCT/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>"},{"location":"community/CODE_OF_CONDUCT/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or   advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic   address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>"},{"location":"community/CODE_OF_CONDUCT/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>"},{"location":"community/CODE_OF_CONDUCT/#scope","title":"Scope","text":"<p>This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>"},{"location":"community/CODE_OF_CONDUCT/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Oscar Esteban at oesteban@stanford.edu or Chris Markiewicz at markiewicz@stanford.edu, two members of the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>"},{"location":"community/CODE_OF_CONDUCT/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>"},{"location":"community/CONTRIBUTING/","title":"Contributing Guidelines","text":"<p>Welcome to the NiPreps project! We're excited you're here and want to contribute.</p> <p>Imposter's syndrome disclaimer</p> <p>Imposter's syndrome disclaimer<sup>1</sup>: We want your help. No, really.</p> <p>There may be a little voice inside your head that is telling you that you're not ready to be an open-source contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer a project like this one?</p> <p>We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open-source. Contributing to open-source projects is a fantastic way to advance one's coding skills. Writing perfect code isn't the measure of a good developer (that would disqualify all of us!); it's trying to create something, making mistakes, and learning from those mistakes. That's how we all improve, and we are happy to help others learn.</p> <p>Being an open-source contributor doesn't just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.</p>"},{"location":"community/CONTRIBUTING/#driving-principles","title":"Driving principles","text":"<p>NiPreps are built around three overarching principles:</p> <ol> <li>Robustness - The pipeline adapts the preprocessing steps depending on    the input dataset and should provide results as good as possible    independently of scanner make, scanning parameters or presence of additional    correction scans (such as fieldmaps).</li> <li>Ease of use - Thanks to dependence on the BIDS standard, manual    parameter input is reduced to a minimum, allowing the pipeline to run in an    automatic fashion.</li> <li>\"Glass box\" philosophy - Automation should not mean that one should not    visually inspect the results or understand the methods.    Thus, NiPreps provides visual reports for each subject, detailing the    accuracy of the most important processing steps.    This, combined with the documentation, can help researchers to understand    the process and decide which subjects should be kept for the group level    analysis.</li> </ol> <p>These principles distill some design and organizational foundations:</p> <ol> <li>NiPreps only and fully support BIDS and BIDS-Derivatives for the input and output data.</li> <li>NiPreps are packaged as a fully-compliant BIDS-Apps, not just in its user interface, but also in the continuous integration, testing, and delivery.</li> <li>The scope of NiPreps is strictly limited to preprocessing tasks.</li> <li>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.</li> <li>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).</li> <li>NiPreps are community-driven, and contributors (in any sense) always get credited with authorship within relevant publications.</li> <li>NiPreps are modular, reliant on widely-used tools such as AFNI, ANTs, FreeSurfer, FSL, NiLearn, or DIPY [7-12] and extensible via plug-ins.</li> </ol>"},{"location":"community/CONTRIBUTING/#practical-guide-to-submitting-your-contribution","title":"Practical guide to submitting your contribution","text":"<p>These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an issue!</p> <p>Before you start, you'll need to set up a free GitHub account and sign in. Here are some instructions.</p> <p>Already know what you're looking for in this guide? Jump to the following sections:</p> <ul> <li>Joining the conversation</li> <li>Contributing through Github</li> <li>Understanding issues</li> <li>Making a change</li> <li>Structuring contributions</li> <li>Licensing</li> <li>Recognizing contributors</li> </ul>"},{"location":"community/CONTRIBUTING/#joining-the-conversation","title":"Joining the conversation","text":"<p>NiPreps is maintained by a growing group of enthusiastic developers\u2014 and we're excited to have you join! Most of our discussions will take place on open issues.</p> <p>We also encourage users to report any difficulties they encounter on NeuroStars, a community platform for discussing neuroimaging.</p> <p>We actively monitor both spaces and look forward to hearing from you in either venue!</p>"},{"location":"community/CONTRIBUTING/#contributing-through-github","title":"Contributing through GitHub","text":"<p>git is a really useful tool for version control. GitHub sits on top of git and supports collaborative and distributed working.</p> <p>If you're not yet familiar with <code>git</code>, there are lots of great resources to help you git started! Some of our favorites include the git Handbook and the Software Carpentry introduction to git.</p> <p>On GitHub, You'll use Markdown to chat in issues and pull requests. You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting. For example, you could write words as bold (<code>**bold**</code>), or in italics (<code>*italics*</code>), or as a link (<code>[link](https://youtu.be/dQw4w9WgXcQ)</code>) to another webpage.</p> <p>GitHub has a really helpful page for getting started with writing and formatting Markdown on GitHub.</p>"},{"location":"community/CONTRIBUTING/#understanding-issues","title":"Understanding issues","text":"<p>Every project on GitHub uses issues slightly differently.</p> <p>The following outlines how the NiPreps developers think about these tools.</p> <ul> <li> <p>Issues are individual pieces of work that need to be completed to move the project forward. A general guideline: if you find yourself tempted to write a great big issue that is difficult to describe as one unit of work, please consider splitting it into two or more issues.</p> <p>Issues are assigned labels which explain how they relate to the overall project's goals and immediate next steps.</p> </li> </ul>"},{"location":"community/CONTRIBUTING/#issue-labels","title":"Issue Labels","text":"<p>The current list of issue labels are here and include:</p> <ul> <li> <p> These issues contain a task that is amenable to new contributors because it doesn't entail a steep learning curve.</p> <p>If you feel that you can contribute to one of these issues, we especially encourage you to do so!</p> </li> <li> <p> These issues point to problems in the project.</p> <p>If you find new a bug, please give as much detail as possible in your issue, including steps to recreate the error. If you experience the same bug as one already listed, please add any additional information that you have as a comment.</p> </li> <li> <p> These issues are asking for new features and improvements to be considered by the project.</p> <p>Please try to make sure that your requested feature is distinct from any others that have already been requested or implemented. If you find one that's similar but there are subtle differences, please reference the other request in your issue.</p> </li> </ul> <p>In order to define priorities and directions in the development roadmap, we have two sets of special labels:</p> Label Description Estimation of the downstream impact the proposed feature/bugfix will have. Estimation of effort required to implement the requested feature or fix the reported bug. <p>One way to understand these labels is to consider how they would apply to an imaginary issue. For example, if -- after a release -- a bug is identified that re-introduces a previously solved issue (i.e., its regresses the code outputs to some undesired behavior), we might assign it the following labels:  . Its development priority would then be \"high\", since it is a low-effort, high-impact change.</p> <p>Long-term goals may be labelled as a combination of:  and   or  since they will have a high-impact on the code-base, but require a medium or high amount of effort. Of note, issues with the labels:   or  are less likely to be addressed because they are less likely to impact the code-base, or because they will require a very high activation energy to do so.</p>"},{"location":"community/CONTRIBUTING/#making-a-change","title":"Making a change","text":"<p>We appreciate all contributions to NiPreps, but those accepted fastest will follow a workflow similar to the following:</p> <ol> <li> <p>Comment on an existing issue or open a new issue referencing your addition.   This allows other members of the NiPreps development team to confirm that you aren't   overlapping with work that's currently underway and that everyone is on the same page   with the goal of the work you're going to carry out. This blog is a nice explanation of why putting this work in up front   is so useful to everyone involved.</p> </li> <li> <p>Fork the particular NiPrep repository (e.g., fMRIPrep)   with your GitHub user.   This is now your own unique copy of that particular NiPreps component.   Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!</p> </li> <li> <p>Clone your forked NiPreps repository to your machine/computer.   While you can edit files directly on github, sometimes the changes   you want to make will be complex and you will want to use a text editor   that you have installed on your local machine/computer.   (One great text editor is vscode).   In order to work on the code locally, you must clone your forked repository.   To keep up with changes in the NiPreps repository,   add the \"upstream\" NiPreps repository as a remote   to your locally cloned repository.     <pre><code>git remote add upstream https://github.com/nipreps/fmriprep.git\n</code></pre>     Make sure to keep your fork up to date with the upstream repository.     For example, to update your master branch on your local cloned repository:       <pre><code>git fetch upstream\ngit checkout master\ngit merge upstream/master\n</code></pre></p> </li> <li> <p>Create a new branch to develop and maintain the proposed code changes.   For example:     <pre><code>git fetch upstream  # Always start with an updated upstream\ngit checkout -b fix/bug-1222 upstream/master\n</code></pre>     Please consider using appropriate branch names as those listed below, and mind that some of them     are special (e.g., <code>doc/</code> and <code>docs/</code>):</p> <ul> <li><code>fix/&lt;some-identifier&gt;</code>: for bugfixes</li> <li><code>enh/&lt;feature-name&gt;</code>: for new features</li> <li><code>doc/&lt;some-identifier&gt;</code>: for documentation improvements.     You should name all your documentation branches with the prefix <code>doc/</code> or <code>docs/</code>     as that will preempt triggering the full battery of continuous integration tests.</li> </ul> </li> <li> <p>Make the changes you've discussed, following the NiPreps coding style guide.   Try to keep the changes focused: it is generally easy to review changes that address one feature or bug at a time.   It can also be helpful to test your changes locally,   using a NiPreps development environment.   Once you are satisfied with your local changes, add/commit/push them   to the branch on your forked repository.</p> </li> <li> <p>Submit a pull request.    A member of the development team will review your changes to confirm    that they can be merged into the main code base.    Pull request titles should begin with a descriptive prefix    (for example, <code>ENH: Support for SB-reference in multi-band datasets</code>):</p> <ul> <li><code>ENH</code>: enhancements or new features (example)</li> <li><code>FIX</code>: bug fixes (example)</li> <li><code>TST</code>: new or updated tests (example)</li> <li><code>DOC</code>: new or updated documentation (example)</li> <li><code>STY</code>: style changes (example)</li> <li><code>REF</code>: refactoring existing code (example)</li> <li><code>CI</code>: updates to continous integration infrastructure (example)</li> <li><code>MAINT</code>: general maintenance (example)</li> <li>For works-in-progress, add the <code>WIP</code> tag in addition to the descriptive prefix.    Pull-requests tagged with <code>WIP:</code> will not be merged until the tag is removed.</li> </ul> </li> <li> <p>Have your PR reviewed by the developers team, and update your changes accordingly in your branch.    The reviewers will take special care in assisting you address their comments, as well as dealing with conflicts    and other tricky situations that could emerge from distributed development.</p> </li> </ol>"},{"location":"community/CONTRIBUTING/#nipreps-coding-style-guide","title":"NiPreps coding style guide","text":"<p>Whenever possible, instances of Nipype <code>Node</code>s and <code>Workflow</code>s should use the same names as the variables they are assigned to. This makes it easier to relate the content of the working directory to the code that generated it when debugging.</p> <p>Workflow variables should end in <code>_wf</code> to indicate that they refer to Workflows and not Nodes. For instance, a workflow whose basename is <code>myworkflow</code> might be defined as follows:</p> <pre><code>from nipype.pipeline import engine as pe\n\nmyworkflow_wf = pe.Workflow(name='myworkflow_wf')\n</code></pre> <p>If a workflow is generated by a function, the name of the function should take the form <code>init_&lt;basename&gt;_wf</code>:</p> <pre><code>def init_myworkflow_wf(name='myworkflow_wf):\n    workflow = pe.Workflow(name=name)\n    ...\n    return workflow\n\nmyworkflow_wf = init_workflow_wf(name='myworkflow_wf')\n</code></pre> <p>If multiple instances of the same workflow might be instantiated in the same namespace, the workflow names and variables should include either a numeric identifier or a one-word description, such as:</p> <pre><code>myworkflow0_wf = init_workflow_wf(name='myworkflow0_wf')\nmyworkflow1_wf = init_workflow_wf(name='myworkflow1_wf')\n\n# or\n\nmyworkflow_lh_wf = init_workflow_wf(name='myworkflow_lh_wf')\nmyworkflow_rh_wf = init_workflow_wf(name='myworkflow_rh_wf')\n</code></pre>"},{"location":"community/CONTRIBUTING/#recognizing-contributions","title":"Recognizing contributions","text":"<p>We welcome and recognize all contributions regardless their size, content or scope: from documentation to testing and code development. You can see a list of current developers and contributors in our zenodo file. Before every release, a new zenodo file will be generated. The update script will also sort creators and contributors by the relative size of their contributions, as provided by the <code>git-line-summary</code> utility distributed with the <code>git-extras</code> package. Last positions in both the creators and contributors list will be reserved to the project leaders. These special positions can be revised to add names by punctual request and revised for removal and update of ordering in an scheduled manner every two years. All the authors enlisted as creators participate in the revision of modifications.</p>"},{"location":"community/CONTRIBUTING/#publications","title":"Publications","text":"<p>Anyone listed as a developer or a contributor can start the submission process of a manuscript as first author (please see Membership, where these concepts are described). To compose the author list, all the creators MUST be included (except for those people who opt to drop-out) and all the contributors MUST be invited to participate. First authorship(s) is (are) reserved for the authors that originated and kept the initiative of submission and wrote the manuscript. To generate the ordering of your paper, please run <code>python .maint/paper_author_list.py</code> from the root of the repository, on the up-to-date <code>upstream/master</code> branch. Then, please modify this list and place your name first. All developers and contributors are pulled together in a unique list, and last authorships assigned. NiPreps and its community adheres to open science principles, such that a pre-print should be posted on an adequate archive service (e.g., ArXiv or BioRxiv) prior publication.</p>"},{"location":"community/CONTRIBUTING/#licensing","title":"Licensing","text":"<p>NiPreps is licensed under the Apache 2.0 license. By contributing to NiPreps, you acknowledge that any contributions will be licensed under the same terms.</p>"},{"location":"community/CONTRIBUTING/#thank-you","title":"Thank you!","text":"<p>You're awesome. </p> <p></p> <p>\u2014 Based on contributing guidelines from the STEMMRoleModels project.</p> <ol> <li> <p>The imposter syndrome disclaimer was originally written by Adrienne Lowe for a PyCon talk, and was adapted based on its use in the README file for the MetPy project.\u00a0\u21a9</p> </li> </ol>"},{"location":"community/features/","title":"New features","text":"<p>The one bit that worries me is that fMRIPrep may become a Swiss army knife. I think instead it should just be a paring knife (small, efficient, and works for many things).</p> <p>-- Satra (source)</p> <p>When projects grow large, many forking paths created by newly implemented features start to open up. To account for this, the NiPreps community was created with the vision of building tools like fMRIPrep and MRIQC covering new imaging modalities, while keeping existing NiPreps tightly within scope. Defining such a scope also aids the implementation of the ease-of-use principle:</p> <p>The same way the scanner does not offer an immense space of knobs to turn in the acquisition, NiPreps should not add many additional knobs to those for them to be considered a viable augmentation or extension of the scanner hw/sw.</p> <p>-- Oscar (source)</p>"},{"location":"community/features/#the-problem-of-feature-creep","title":"The problem of feature creep","text":"<p>To avert feature creep and to serve each individual NiPrep, we developed the following guidelines, with the hopes of keeping these tools in a healthy state.</p> <p>I'm worried fMRIPrep is catching a case of featuritis</p> <p>-- Mathias (source)</p> <p>These guidelines should also serve the community to transparently drive the process of including proposals into the road-map, set the ground for healthy conversation, and establish some patterns when accepting new-feature contributions. Before proposing new features, please be mindful that a road-map may not exist for a particular NiPrep. Even when a development road-map exists, please understand that it is not always possible to rigorously follow them:</p> <p>I think something like this is what we tried to start sketching out with the development roadmap. The concern, as I remember it, was that we couldn't guarantee (or rule out) specific features when working with a small development team.</p> <p>-- Elizabeth (source).</p>"},{"location":"community/features/#proposing-a-new-feature","title":"Proposing a new feature","text":""},{"location":"community/features/#why-the-new-feature-is-requested","title":"Why the new feature is requested?","text":"<p>Before going ahead and proposing a new feature, please take some time to learn whether the topic has been covered in the past and what decisions were made and why. This should be reasonably easy to do with the search tool of GitHub on the particular NiPrep repository.</p> <p>If no previous discussion about the new idea is found, the next step is ensuring the new feature aligns with the vision and the scope of the target tool, as Elizabeth points out. Taking a look into the Development Road-map of the particular project (if it exists), may help finding an answer.</p> <p>If the new feature still seems pertinent after this preliminary work or you are unsure about whether it falls within the scope, then go ahead and post an issue requesting feedback on your proposal. Please make sure to clearly state why the new feature should be considered.</p>"},{"location":"community/features/#some-questions-will-always-be-asked-about-a-new-feature","title":"Some questions will always be asked about a new feature","text":"<p>These questions by James will certainly help build up the discourse in support of the new feature, as the NiPreps maintainers will consider them:</p> <ul> <li> <p>Is the user interface affected?     Because NiPreps generally expose a command-line interface (CLI) for the     interaction with the user, new features involving changes to the CLI must be     considered with caution as they may harm the ease-of-use:</p> <p>It also seems that some new features add more confusion than others. Especially when the CLI is affected, and yet another option is added, that makes the tool more complex to use.</p> <p>-- Alejandro (source).</p> </li> <li> <p>Does the new feature substantially increase the internal complexity?     Maintainers and developers will attempt to consolidate tools and lower the internal     complexity whenever possible.     This effort usually competes with the addition of new features as they typically will     address particular use-cases rather than general improvements.     However, that doesn't need to be the case, as some sections of the code might be     objectively improvable and the integration of a new feature revising those might     also lower complexity.     Lowering the internal complexity will always be considered a great incentive     for a new feature to be accepted.</p> </li> <li> <p>Is there a standard procedure for the proposed feature in the literature?</p> <ul> <li>if so, could we just use that procedure/value?</li> </ul> </li> <li> <p>Is the feature dependent on some attribute of the input data? (e.g., TR, duration, etc.)</p> <ul> <li>if so, can the procedure/value be determined algorithmically?</li> </ul> </li> <li> <p>Does the feature interact with other settings?     For instance, fmriprep#1962     interacts with the a/tCompCor implementation.</p> </li> <li> <p>What is the difficulty of implementing the procedure outside of a NiPrep?     In other words, does the NiPrep provide all the necessary outputs for a     user to perform the non-standard analysis?</p> </li> </ul>"},{"location":"community/features/#how-the-integration-of-the-new-feature-willcan-be-validated","title":"How the integration of the new feature will/can be validated?","text":"<p>Please propose ways to validate the new feature in the context of the workflow. Meaning, the objective here is to validate that the new feature works well within the pipeline, rather than validating a specific algorithm. To ensure the sustainability of NiPreps, the onus of this validation should be on the person/group requesting the feature.</p>"},{"location":"community/licensing/","title":"Licensing and Derived Works","text":"<p>The NiPreps community believes that software is an integral component of scientific practice, and that any scientific claim must be verifiable by following the chain of reasoning from observation to conclusion. To achieve this, software must be free to use, inspect, and critique. We also believe that you should be free to modify our software to improve it or adapt it to new use cases.</p> <p>As software development is a dynamic process, code modifications can quickly become confusing as the original and modified versions depart from each other. For the sake of transparency and verification, when you modify our code, we ask that you document both the version of the software that you started with and the changes you make.</p> <p>We believe these freedoms are best promoted by distributing our software under free/open source software licenses, and the license we feel best promotes these goals is the Apache License, Version 2.0.</p> <p>This page outlines our commitment to transparent development and our expectations for developers who adapt NiPreps code to use in other projects.</p>"},{"location":"community/licensing/#licensing-of-nipreps-projects","title":"Licensing of NiPreps projects","text":"<p>All software packages and tools under the NiPreps umbrella must be licensed under the Apache License 2.0 by default, unless otherwise stated. The authors of new NiPreps packages may not abide by this general rule of thumb if necessary and/or sufficiently justified (e.g., the source code is actually derived from a product licensed under a copyleft license).</p> <p>Containerized Images bundling NiPreps components and their dependencies can be distributed under a free and open-source license without copyleft, such as the MIT License. In such a case, the attribution notice of the MIT license must be present in the header comment of the container image bootstraping file (for instance, the so-called <code>Dockerfile</code>). This different licensing must be also indicated in the <code>NOTICE</code> file of the corresponding NiPreps components bundled within the image.</p> <p>Docker-wrappers such as the <code>fmriprep-docker</code> package may be licensed under any free and open-source license without copyleft, such as the MIT License. This different licensing must be also indicated in the <code>NOTICE</code> file of the corresponding NiPreps components bundled within the image.</p> <p>Data (distributed within the test data of packages or through the <code>nipreps-data</code> GitHub organization) will preferably be distributed under the Creative Commons Zero v1.0 Universal.</p> <p>Under no circumstances any NiPreps software or data will be made publicly available unlicensed. If you find any component of NiPreps that is unlicensed, please make us aware at nipreps@gmail.com at your earliest convenience.</p>"},{"location":"community/licensing/#the-apache-license-20","title":"The Apache License 2.0","text":"<p>(This section is adapted from this blog post by D. Mar\u00edn)</p> <p>The Apache License was created by the Apache Software Foundation (ASF) as the license for its Apache HTTP Server.</p> <p>Just as the MIT License, it\u2019s a very permissive non-copyleft license that allows using the software for any purpose, distributing it, modifying it, and distributing derived works of it without concern for royalties. Its main differences, compared to the MIT License, are:</p> <ul> <li>Using the Apache License, the authors of the software grant patent licenses to any user or distributor of the code.   This patent licenses apply to any patent that, being licenseable by any of the software author, would be infringed by the piece of code they have created.</li> <li>Apache License required that unmodified parts in derived works keep the License.</li> <li>In every licensed file, any original copyright, patent, trademark or attribution notices must be preserved.</li> <li>In every licensed file change, there must be a notification stating that changes have been made in the file.</li> <li>If the Apache-licensed software includes a <code>NOTICE</code> file, this file and its contents must be preserved in all the derived works.</li> <li>If anyone intentionally sends a contribution for an Apache-licensed software to its authors, this contribution can automatically be used under the Apache License.</li> </ul> <p>This license is interesting because of the automatic patent license, and the clause about contribution submission.</p> <p>It\u2019s compatible with the GPL, so you can mix Apache licensed-code into GPL software.</p>"},{"location":"community/licensing/#why-apache-20","title":"Why Apache-2.0?","text":"<p>In the case of scientific software, we believe that clearly stating that a Derived Work introduces changes into the original Work is a fundamental measure of transparency. Other than that, we wanted a permissive, non-copyleft license.</p>"},{"location":"community/licensing/#what-is-our-expectation-for-derived-works","title":"What is our expectation for Derived Works?","text":"<p>At the bare minimum, you must meet the conditions of the license (simplified version) about preserving the license text and copyright/attribution notices as well as corresponding statements of changes.</p> <p>How to state that a file has been changed in a Derived Work. We suggest the following steps, heavily influenced by P. Ombredanne's recommendations at StackExchange:</p> <ol> <li>In each source file, add a note to the header comment stating that the file has been modified, with an approximate date, and a high-level description of the changes.    The date and the description of the changes are not strictly required, but they are positive etiquette from a software engineering standpoint and substantially improve the transparency of the changes from a scientific point of view.</li> <li>If the source file did not have a license notice in the header comment, please add it to avoid ambiguity.</li> <li>Deleted files: please keep the file with just the header comment and state that the file is deleted.    The change statement should follow the suggestion in 1), preferably stating whether the source has been deleted or moved over to other files.    If preserving the filename as-is might become confusing to the user of the Derived Work, the filename can be modified to be marked as hidden with a dot <code>.</code> or underscore <code>_</code> prefix, or modifying the extension.</li> <li>Preferably, also include a link to the original file in our GitHub repository, making sure the link is done to a particular commit state.</li> </ol> <p>What changes would we like to see annotated? The high-level description of the changes will preferably contain:</p> <ul> <li>Correction of bugs</li> <li>Substantial performance improvement decisions</li> <li>Replacement of relevant methods and dependencies by alternatives</li> <li>Changes to the license</li> </ul>"},{"location":"community/licensing/#example-of-our-expectations","title":"Example of our expectations","text":"<p>Let's say a Derived Work modifies the <code>sdcflows.viz.utils</code> code-base. The file may or may not have the attribution notice. At the time of writing, the header comment of this file is:</p> <p>Header comment in the original Work</p> With attribution notice <pre><code># emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-\n# vi: set ft=python sts=4 ts=4 sw=4 et:\n#\n# Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n#     http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> Without attribution notice <pre><code># emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-\n# vi: set ft=python sts=4 ts=4 sw=4 et:\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> <p>Either way (whether the attribution notice is present or not), we suggest to update this header comment to something along the lines of the following:</p> <p>Suggested header comment in the Derived Work</p> Required <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found at:\n# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with yellow color are explicitly required by the Apache-2.0 conditions.</p> Recommended (commit) <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found at:\n# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with green color are recommended by the NiPreps Developers.</p> Recommended (version) <p><pre><code># &lt;shebang and editor settings can be preserved or removed freely&gt;\n#\n# &lt;your attribution notice, either maintaining the Apache-2.0 license or changing the license&gt;\n#\n# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,\n# and this file has been changed.\n# The original file this work derives from is found within\n# the version 2.0.2 distribution of the software.\n#\n# [April 2021] CHANGES:\n#    * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.\n#    * ENH: Changed plotting dependency to the new `netplotbrain` package.\n#    * DOC: Added docstrings to some functions that lacked them.\n#\n# ORIGINAL WORK'S ATTRIBUTION NOTICE:\n#\n#     Copyright 2021 The NiPreps Developers &lt;nipreps@gmail.com&gt;\n#\n#     Licensed under the Apache License, Version 2.0 (the \"License\");\n#     you may not use this file except in compliance with the License.\n#     You may obtain a copy of the License at\n#\n#         http://www.apache.org/licenses/LICENSE-2.0\n#\n#     Unless required by applicable law or agreed to in writing, software\n#     distributed under the License is distributed on an \"AS IS\" BASIS,\n#     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#     See the License for the specific language governing permissions and\n#     limitations under the License.\n\"\"\"Visualization tooling.\"\"\"\n</code></pre> The lines highlighted with green color are recommended by the NiPreps Developers.</p> <p>Although it is not mandated by the license letter, the spirit of the Apache-2.0 (and all other licenses stipulating the statement of changes, such as the CC-BY 4.0) suggests that a date of modification and an overview of outstanding changes are pertinent. We also suggest a link to the original code, including the commit-hash (that long string starting with <code>50393a</code> in the URL above) for the location of the exact origin of the file. Alternatively, Derived Works may point to a exact release identifier where the original file is part of the code-base distribution. Please make sure to remove or replace with appropriate contents the comment tags <code>&lt;...&gt;</code> above.</p> <p>What if a Derived Work does not modify this particular file? You should retain the original attribution notice as is (or introduce it if missing), unless you are relicensing the file. In that case, proceed with the suggestions above, and note the license change in the STATEMENT OF CHANGES block of the header comment.</p>"},{"location":"community/licensing/#are-papers-using-apache-20-licensed-software-considered-as-derived-works","title":"Are papers using Apache-2.0 licensed software considered as Derived Works?","text":"<p>No, they don't because they only reuse the software (in other words, they don't redistribute the software). The license stipulates that redistribution must retain the license and attribution notices as they are. In the scientific context, it is likely that a particular tool is modified (for example, to replace a method that you think is not appropriate for your data). Then, redistribution of the source would be desirable from the transparent reporting point of view, and therefore you should honor the License.</p> <p>Generally, works using our NiPreps just need to follow the citation guidelines of the particular project and report the citation boilerplate including all software versions and literature references in the closest letter possible to that generated by the tool.</p>"},{"location":"community/licensing/#licensing-of-docker-and-singularity-images","title":"Licensing of Docker and Singularity images","text":"<p>Container images redistribute copies of NiPreps alongside their third-party dependencies, all of them bundled in the image. If the applicable license is Apache-2.0, then the text of a <code>NOTICE</code> file must be shown to the user. All NiPreps must insert a <code>NOTICE</code> file into their containerized distributions and print its contents out in the command line output, as well as in the visual reports. This <code>NOTICE</code> file for containers will be placed in the <code>/.docker/NOTICE</code> path of the repository, and this file must replace the <code>/NOTICE</code> file (if it exists) at image building time. Alternatively, and if the corresponding NiPreps Developers consider that the Apache-2.0 imposes too onerous requirements for the container image distribution, the source code of such images (e.g., <code>Dockerfile</code>) can be licensed under the MIT license.</p> <p>Example <code>NOTICE</code> file for fMRIPrep</p> Python distribution <code>/NOTICE</code> <pre><code>fMRIPrep\nCopyright 2021 The NiPreps Developers.\n\nThis product includes software developed by\nthe NiPreps Community (https://nipreps.org/).\n\nPortions of this software were developed at the Department of\nPsychology at Stanford University, Stanford, CA, US.\n\nThis software contains code ultimately derived from the epidewarp.fsl\nscript (https://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)\nby Doug Greve, Dave Tuch, Tom Liu, and Bryon Mueller with generous\nhelp from the FSL crew (www.fmrib.ox.ac.uk/fsl) and the Biomedical\nInformatics Research Network (www.nbirn.net).\n</code></pre> Container image distribution <code>/.docker/NOTICE</code> <pre><code>fMRIPrep Container Image distribution\nCopyright 2021 The NiPreps Developers.\n\nThis product includes fMRIPrep and software developed by\nthe NiPreps Community (https://nipreps.org/).\n\nPortions of this software were developed at the Department of\nPsychology at Stanford University, Stanford, CA, US.\n\nThis product bundles AFNI &lt;version-placeholder&gt;, which is available under\nthe Gnu General Public License.\nMajor portions of AFNI were written at the Medical College of Wisconsin,\nwhich owns the copyright to that code. For fuller details, see\nhttp://afni.nimh.nih.gov/pub/dist/src/README.copyright.\n\nThis product bundles ANTs &lt;version-placeholder&gt;, which is available under\nthe BSD 3-clause license terms.\nCopyright 2009-2013 ConsortiumOfANTS.\n\nThis product bundles BIDS-Validator &lt;version-placeholder&gt;, which is available\nunder the MIT License.\nCopyright 2015 The Board of Trustees of the Leland Stanford Junior University.\n\nThis product bundles the Connectome Workbench &lt;version-placeholder&gt;, which\nis available under the GPL-v2\n(https://www.humanconnectome.org/software/connectome-workbench-license).\n\nThis product bundles FSL &lt;version-placeholder&gt;, which is available\nunder a custom license with commercial restrictions\n(https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence).\nCopyright 2018, The University of Oxford.\n\nThis product bundles FreeSurfer &lt;version-placeholder&gt;, which is available\nunder a custom license and requires obtaining a license key\n(https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense).\nCopyright 2011, The General Hospital Corporation, Boston MA, USA.\n\nThis product bundles code derived from ICA-AROMA, both (fork and original work)\nare available under the Apache-2.0 license.\n(https://github.com/oesteban/ICA-AROMA/blob/master/license.md)\nCopyright 2021, Maarten Mennes\n\nThis product bundles Miniconda &lt;version-placeholder&gt;, which is available\nunder a BSD 3-clause license.\n(c) 2017 Continuum Analytics, Inc. (dba Anaconda, Inc.).\nhttps://www.anaconda.com. All Rights Reserved\n\nThis product bundles NeuroDebian, which adheres to the\nDebian Free Software Guidelines (DFSG)\nhttps://www.debian.org/social_contract#guidelines\nand the terms of the Debian Social Contract version 1.1.\n\nThis product bundles tools by the NiPy community, such as NiBabel\n(MIT License, https://github.com/nipy/nibabel/blob/master/COPYING),\nand NiPype (Apache-2.0, https://github.com/nipy/nipype/blob/master/LICENSE).\n\nThis product bundles Pandoc &lt;version-placeholder&gt;, which is available\nunder the GPL version 2 or later.\nCopyright (C) 2006-2021 John MacFarlane &lt;jgm at berkeley dot edu&gt;\n\nThis product bundles SVGO &lt;version-placeholder&gt;, which is available\nunder the MIT License.\nCopyright (c) Kir Belevich\n\nThis product bundles tedana &lt;version-placeholder&gt;, which is available under\nthe GNU Lesser General Public License v2.1.\nCopyright 2018, tedana developers.\n\nTemplateFlow, a component of this bundle, contains neuroimaging template\nand atlas data under several permissive licenses.\nPlease refer to the metadata of the particular template used in your study to\ndetermine the exact terms of the license and how to acknowledge attribution\nof those works.\n\nsMRIPrep, a component of this bundle, contains code ultimately derived from\nANTs &lt;version-placeholder&gt;, which is available under\nthe BSD 3-clause license terms.\nCopyright 2009-2013 ConsortiumOfANTS.\n\nsMRIPrep, a component of this bundle, contains code ultimately derived from\nMindboggle &lt;version-placeholder&gt;, which is available under\nthe Apache License 2.0.\nCopyright 2016, Mindboggle team (http://mindboggle.info)\n\nfMRIPrep contains code ultimately derived from the epidewarp.fsl\nscript (https://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)\nby Doug Greve, Dave Tuch, Tom Liu, and Bryon Mueller with generous\nhelp from the FSL crew (www.fmrib.ox.ac.uk/fsl) and the Biomedical\nInformatics Research Network (www.nbirn.net).\n</code></pre>"},{"location":"community/members/","title":"Membership","text":"<p>In general, NiPreps embrace a liberal contribution model of governance structure. However, because of the scientific domain of NiPreps, the community features some structure from meritocracy models to prescribe the order in the authors list of new papers about these tools.</p>"},{"location":"community/members/#developers","title":"Developers","text":"<p>Developers are members of a wonderful team driving the project. Names and contacts of all developers are included in the <code>.maint/developers.json</code> file of each project. Examples of steering activities that drive the project are: actively participating in the follow-up meetings, leading documentation sprints, helping in the design of the tool and definition of the roadmap, providing resources (in the broad sense, including funding), code-review, etc.</p>"},{"location":"community/members/#contributors","title":"Contributors","text":"<p>Contributors enlisted in the <code>.maint/contributors.json</code> file of each project actively help or have previously helped the project in a broad sense: writing code, writing documentation, benchmarking modules of the tool, proposing new features, helping improve the scientific rigor of implementations, giving out support on the different communication channels (mattermost, NeuroStars, GitHub, etc.). If you are new to the project, don't forget to add your name and affiliation to the list of contributors there! Our Welcome Bot will send an automated message reminding this to first-time contributors. Before every release, unlisted contributors will be invited again to add their names to the file (just in case they missed the automated message from our Welcome Bot).</p> <p>Contributors who have contributed at some point to the project but were required or they wished to disconnect from the project's updates and to drop-out from publications and other dissemination activities, are listed in the <code>.maint/former.json</code> file.</p>"},{"location":"devs/devenv/","title":"Developer Environment","text":"<p>This document explains how to prepare a new development environment and update an existing environment, as necessary, for the development of NiPreps' components. Some components may deviate from these guidelines, in such a case, please follow the guidelines provided in their documentation.</p> <p>If you plan to contribute back to the community, making your code available via pull-request, please make sure to have read and understood the Community Documents and Contributor Guidelines. If you plan to distribute derived code, please follow our licensing guidelines.</p> <p>Development in Docker is encouraged, for the sake of consistency and portability. By default, work should be built off of <code>nipreps/fmriprep:unstable</code>, which tracks the <code>master</code> branch, or <code>nipreps/fmriprep:latest</code>, which tracks the latest release version (see BIDS-Apps execution guide for the basic procedure for running).</p> <p>It will be assumed the developer has a working repository in <code>$HOME/projects/fmriprep</code>, and examples are also given for niworkflows and NiPype.</p>"},{"location":"devs/devenv/#patching-a-working-copy-into-a-docker-container","title":"Patching a working copy into a Docker container","text":"<p>In order to test new code without rebuilding the Docker image, it is possible to mount working repositories as source directories within the container. The Docker wrapper script simplifies this for the most common repositories:</p> <pre><code>    -f PATH, --patch-fmriprep PATH\n                          working fmriprep repository (default: None)\n    -n PATH, --patch-niworkflows PATH\n                          working niworkflows repository (default: None)\n    -p PATH, --patch-nipype PATH\n                          working nipype repository (default: None)\n</code></pre> <p>For instance, if your repositories are contained in <code>$HOME/projects</code>:</p> <pre><code>$ fmriprep-docker -f $HOME/projects/fmriprep/fmriprep \\\n                  -n $HOME/projects/niworkflows/niworkflows \\\n                  -p $HOME/projects/nipype/nipype \\\n                  -i nipreps/fmriprep:latest \\\n                  $HOME/fullds005 $HOME/dockerout participant\n</code></pre> <p>Note the <code>-i</code> flag allows you to specify an image.</p> <p>When invoking <code>docker</code> directly, the mount options must be specified with the <code>-v</code> flag:</p> <pre><code>-v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro\n-v $HOME/projects/niworkflows/niworkflows:/usr/local/miniconda/lib/python3.7/site-packages/niworkflows:ro\n-v $HOME/projects/nipype/nipype:/usr/local/miniconda/lib/python3.7/site-packages/nipype:ro\n</code></pre> <p>For example,</p> <pre><code>$ docker run --rm -v $HOME/ds005:/data:ro -v $HOME/dockerout:/out \\\n    -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro \\\n    nipreps/fmriprep:latest /data /out/out participant \\\n    -w /out/work/\n</code></pre> <p>In order to work directly in the container, pass the <code>--shell</code> flag to <code>fmriprep-docker</code></p> <pre><code>$ fmriprep-docker --shell $HOME/ds005 $HOME/dockerout participant\n</code></pre> <p>This is the equivalent of using <code>--entrypoint=bash</code> and omitting the fMRIPrep arguments in a <code>docker</code> command:</p> <pre><code>$ docker run --rm -v $HOME/ds005:/data:ro -v $HOME/dockerout:/out \\\n    -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro --entrypoint=bash \\\n    nipreps/fmriprep:latest\n</code></pre> <p>Patching containers can be achieved in Singularity analogous to <code>docker</code> using the <code>--bind</code> (<code>-B</code>) option:</p> <pre><code>$ singularity run \\\n    -B $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep \\\n    fmriprep.img \\\n    /scratch/dataset /scratch/out participant -w /out/work/\n</code></pre>"},{"location":"devs/devenv/#adding-dependencies","title":"Adding dependencies","text":"<p>New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies. Python dependencies may be added in three places, depending on whether the package is large or non-release versions are required. The image must be rebuilt after any dependency changes.</p> <p>Python dependencies should generally be included in the appropriate dependency metadata of the <code>setup.cfg</code> file found at the root of each repository. If some the dependency must be a particular version (or set thereof), it is possible to use version filters in this <code>setup.cfg</code> file.</p> <p>For large Python dependencies where there will be a benefit to pre-compiled binaries, conda packages may also be added to the <code>conda install</code> line in the Dockerfile.</p> <p>Non-Python dependencies must also be installed in the Dockerfile, via a <code>RUN</code> command. For example, installing an <code>apt</code> package may be done as follows:</p> <pre><code>RUN apt-get update &amp;&amp; \\\n    apt-get install -y &lt;PACKAGE&gt;\n</code></pre>"},{"location":"devs/devenv/#rebuilding-docker-image","title":"(Re)Building Docker image","text":"<p>If it is necessary to (re)build the Docker image, a local image named <code>fmriprep</code> may be built from within the local repository. Let's assume it is located in <code>~/projects/fmriprep</code>:</p> <pre><code>~/projects/fmriprep$ VERSION=$( python get_version.py )\n~/projects/fmriprep$ docker build -t fmriprep --build-arg VERSION=$VERSION .\n</code></pre> <p>The <code>VERSION</code> build argument is necessary to ensure that help text can be reliably generated. The <code>get_version.py</code> tool constructs the version string from the current repository state.</p> <p>To work in this image, replace <code>nipreps/fmriprep:latest</code> with just <code>fmriprep</code> in any of the above commands. This image may be accessed by the Docker wrapper via the <code>-i</code> flag, e.g.:</p> <pre><code>$ fmriprep-docker -i fmriprep --shell\n</code></pre>"},{"location":"devs/devenv/#code-server-development-environment-experimental","title":"Code-Server Development Environment (Experimental)","text":"<p>To get the best of working with containers and having an interactive development environment, we have an experimental setup with code-server.</p> <p>Important</p> <p>We have a video walking through the process if you want a visual guide.</p> <p>1. Build the Docker image. We will use the <code>Dockerfile_devel</code> file to build our development docker image: <pre><code>$ cd $HOME/projects/fmriprep\n$ docker build -t fmriprep_devel -f Dockerfile_devel .\n</code></pre></p> <p>2. Run the Docker image We can start a docker container using the image we built (<code>fmriprep_devel</code>): <pre><code>$ docker run -it -p 127.0.0.1:8445:8080 -v ${PWD}:/src/fmriprep fmriprep_devel:latest\n</code></pre></p> <p>Windows Users</p> <p>If you are using windows shell, <code>${PWD}</code> may not be defined, instead use the absolute path to your repository.</p> <p>Docker-Toolbox</p> <p>If you are using Docker-Toolbox, you will need to change your virtualbox settings using these steps as a guide. For step 6, instead of <code>Name = rstudio; Host Port = 8787; Guest Port = 8787</code>, have <code>Name = code-server; Host Port = 8443; Guest Port = 8080</code>. Then in the docker command above, change <code>127.0.0.1:8445:8080</code> to <code>192.168.99.100:8445:8080</code>.</p> <p>If the container started correctly, you should see the following on your console:</p> <pre><code>INFO  Server listening on http://localhost:8080\nINFO    - No authentication\nINFO    - Not serving HTTPS\n</code></pre> <p>Now you can switch to your favorite browser and go to: 127.0.0.1:8445 (or 192.168.99.100:8445 for Docker Toolbox).</p> <p>3. Copy <code>fmriprep.egg-info</code> into your <code>fmriprep/</code> project directory <code>fmriprep.egg-info</code> makes the package exacutable inside the docker container. Open a terminal in vscode and type the following:</p> <pre><code>$ cp -R /src/fmriprep.egg-info /src/fmriprep/\n</code></pre>"},{"location":"devs/devenv/#code-server-development-environment-features","title":"Code-Server Development Environment Features","text":"<ul> <li> <p>The editor is vscode</p> </li> <li> <p>There are several preconfigured debugging tests under the debugging icon in the activity bar</p> </li> <li> <p>see vscode debugging python for details.</p> </li> <li> <p>The <code>gitlens</code> and <code>python</code> extensions are preinstalled to improve the development experience in vscode.</p> </li> </ul>"},{"location":"devs/releases/","title":"Releases","text":"<p>As of January 2020, fMRIPrep has adopted a Calendar Versioning scheme, and with it we are attempting to apply more coherent semantic rules to our releases.</p> <p>Note</p> <p>This document is a draft for internal and external comment. Any commitments expressed here are proposals, and should not be relied upon at this time. This conversation started as a Google Doc.</p>"},{"location":"devs/releases/#principles","title":"Principles","text":"<p>The basic release form is <code>YY.MINOR.PATCH</code>, so the first minor release of 2020 is 20.0.0, and the first minor release of 2021 will be 21.0.0, whatever the final minor release of 2020 is. A series of releases share a <code>YY.MINOR.</code> prefix, which we refer to as the <code>YY.MINOR.x</code> series. For example, the 20.0.x series contains version 20.0.0, 20.0.1, and any other releases needed.</p>"},{"location":"devs/releases/#feature-releases","title":"Feature releases","text":"<p>Minor releases are considered feature releases. Because there is no concept of a \"major\" release (just a calendar year rollover), most changes to the code base will result in a new feature release. Changes targeting a new feature release should target the master branch. Feature releases may be released as often as is deemed appropriate.</p>"},{"location":"devs/releases/#bug-fix-releases","title":"Bug-fix releases","text":"<p>Patch releases are considered bug-fix releases. Each minor release triggers the creation of a new <code>maint/&lt;YY&gt;.&lt;MINOR&gt;.x</code> branch, and changes targeting a bug-fix release should target this branch. A \"minor release series\" is the initial feature release and the bug-fix releases that share the minor release prefix. Bug-fix releases may be released on minimal notice to other developers.</p> <p>These releases must satisfy four conditions:</p> <ol> <li>Resolving one or more bugs. These mostly include failures of fMRIPrep to complete or producing invalid derivatives (e.g., a NIfTI file of all zeroes).</li> <li>Derivatives compatibility. If a subject may be successfully run on 20.0.n, then the imaging derivatives should be identical if rerun with 20.0.(n+1), modulo rounding errors and the effects of nondeterministic algorithms. The changes between successful runs of 20.0.n and 20.0.(n+1) should not be larger than the changes between two successful runs of 20.0.n. Cosmetic changes to reports are acceptable, while differing fields of view or data types in a NIfTI file would not be.</li> <li>API compatibility. Workflow-generating functions, workflow input- and outputnode fields must not change. As an end-user application, this may seem overly strict, but the odds of introducing a bug are much higher in these cases.</li> <li>User interface compatibility. Substantial changes to fMRIPrep command line must not happen (e.g., the addition of a new, relevant flag).</li> </ol> <p>Note that not all bugs can be fixed in a way that satisfies all three of these criteria without significant effort. A developer may determine that the bug will be fixed in the next feature release.</p> <p>Additional acceptable changes within a minor release series:</p> <ol> <li>Improved tests. These often come along with bug fixes, but they can be free-standing improvements to the code base.</li> <li>Improved documentation. Unless the documentation is of a feature that will not be present in a bug-fix release, this is always welcome.</li> <li>Updates to the Dockerfile that improve operation for Docker and/or Singularity users, but do not risk behavior change. A good example is including more templates to reduce the need for network requests. An example of an update to the Dockerfile that forces a minor release increment is a change in the pinned version of any of the dependencies or the base container image.</li> <li>Improvements to the lightweight wrappers. As long as a command-line invocation that worked for the previous version continues to work and produce the same Docker command, there's little chance of harm.</li> </ol>"},{"location":"devs/releases/#mechanics","title":"Mechanics","text":""},{"location":"devs/releases/#branch-synchronization","title":"Branch synchronization","text":"<p>A maintenance branch should generally follow directly from the tag of the feature release. <pre><code>git checkout -b maint/20.0.x 20.0.0\ngit push upstream maint/20.0.x\n</code></pre></p> <p>It is expected that <code>maint/20.0.x</code> will diverge from <code>master</code>, as new features will be merged into <code>master</code>, and bug-fixes into <code>maint/20.0.x</code>. At a minimum, each new bug-fix release should be merged into <code>master</code>. After a <code>20.0.1</code> release: <pre><code>git checkout master\ngit fetch upstream\ngit reset --hard upstream/master\ngit merge --no-commit 20.0.1\n\n# Resolve any merge conflicts\ngit add .\n\n# Manually review all changes to ensure compatibility\ngit diff --cached upstream/master\ngit commit\ngit push upstream master\n</code></pre></p> <p>If an unreleased bug-fix seems likely to cause merge conflicts, it may be worth doing the above more frequently.</p>"},{"location":"devs/releases/#dependencies","title":"Dependencies","text":"<p>fMRIPrep has a number of dependencies that we control at this point:</p> <ol> <li>sMRIPrep</li> <li>SDCflows</li> <li>NiWorkflows</li> </ol> <p>These do not follow the same versioning scheme as above, but we need them to follow a compatible scheme. In particular, we need to be able to fix bugs that are situated within these dependencies in a bug-fix release without violating the criteria laid out above. At the time of an fMRIPrep feature release, all of the above tools need to also split out a maintenance branch (if they have not already) for the minor version series that fMRIPrep depends on. As an example, when 20.0.0 was released, fMRIPrep had the following dependencies in <code>setup.cfg</code>:</p> <p><pre><code>    niworkflows ~= 1.1.7\n    sdcflows ~= 1.2.0\n    smriprep ~= 0.5.2\n</code></pre> <code>~=</code> is the compatible release specifier described in PEP 440. <code>~= 1.1.7</code> is equivalent to <code>&gt;= 1.1.7, == 1.1.*</code>. This means that the current version of fMRIPrep is expected to work with niworkflows 1.1.7+ but not 1.2+. Thus, niworkflows needs to have a maint/1.1.x branch, sdcflows a <code>maint/1.2.x</code> and smriprep <code>maint/0.5.x</code>. Any changes to these tools that might violate API or derivative compatibility, must go into master, and must not be released into the current minor series of these tools. Note that fMRIPrep 20.0.0 does not depend on <code>niworkflows ~= 1.1.0</code>. Multiple feature releases of fMRIPrep may depend on the same minor release series of a dependency. There is no requirement to hike the dependency. However, if a dependency has started a new minor release series, a feature release of fMRIPrep is a good opportunity to bump the dependency.</p> <p>We maintain a Versions Matrix to document and keep track of these dependencies.</p>"},{"location":"devs/releases/#support-windows","title":"Support Windows","text":""},{"location":"devs/releases/#minor-release-series","title":"Minor release series","text":"<p>A minor release series will continue to accept qualifying bug fixes at least until the next minor release. A minimum duration may be considered, or a fixed number of minor release series might be simultaneously supported.</p> <p>An unmaintained series is a valid target for bug fixes after the support window, but the expected effort level of the contributor and maintainers will be higher and lower, respectively.</p>"},{"location":"devs/releases/#long-term-support-series","title":"Long-term support series","text":"<p>A long-term support (LTS) series is a minor release series that an LTS manager commits to maintaining for a specific duration, no less than one year. LTS series are under the same constraints as a minor release series in terms of what changes can be accepted.</p> <p>The fMRIPrep developers commit to maintaining one LTS series at all times, at intervals of approximately one year. Community members may volunteer to assume maintainership after the initial period, or to maintain another minor release series as LTS.</p> <p>Support windows of greater than a year have a much higher potential to run into issues with upstream dependencies going outside of their support windows. As much as possible, an fMRIPrep minor release should seek to move to the versions of upstream dependencies that will ensure the longest support before being considered for LTS.</p> <p>Additional tasks required of an LTS manager:</p> <ul> <li> <p>Tracking possible breaking changes and broken URLs in upstream projects outside of the nipreps ecosystem.</p> <ul> <li>Neurodebian dependencies (AFNI, FSL, Convert3D, Connectome WB)</li> <li>FreeSurfer</li> <li>ANTs</li> <li>NodeJS - BIDS-validator, SVGO</li> <li>Pandoc</li> <li>ICA-AROMA</li> <li>Miniconda</li> <li>Python minor series end-of-life</li> <li>numpy, scipy, pandas, nipype, nibabel, matplotlib</li> </ul> </li> <li> <p>Backporting fixes from other maintained series.</p> <ul> <li>If a bug is identified as existing within the LTS series and can be fixed without breaking API or derivative compatibility.</li> </ul> </li> </ul> <p>As many dependencies as possible should be pinned to specific versions relevant to the environment they are installed in. Packages (Debian <code>.deb</code> files, conda packages, Python wheels) should be archived in case of a loss of the external packages.</p>"},{"location":"devs/versions/","title":"Versions Matrix","text":"<p>The versions matrix is intended to allow easy reference for the dependencies within the NiPreps family of projects.</p>"},{"location":"devs/versions/#fmriprep","title":"fMRIPrep","text":"fMRIPrep series sMRIPrep series SDCflows series NiWorkflows series 23.1.x <code>~= 0.12.0</code> <code>~= 2.5.0</code> <code>~= 1.8.0</code> 23.0.x <code>~= 0.11.0</code> <code>~= 2.4.0</code> <code>~= 1.7.6</code> 22.1.x <code>~= 0.10.0</code> <code>~= 2.2.1</code> <code>~= 1.7.0</code> 22.0.x <code>~= 0.9.2</code> <code>~= 2.1.1</code> <code>~= 1.6.3</code> 21.0.x <code>~= 0.8.0</code> <code>~= 2.0.0</code> <code>~= 1.4.0</code> 20.2.x <code>~= 0.7.0</code> <code>~= 1.3.1</code> <code>~= 1.3.0</code> 20.1.x <code>~= 0.6.1</code> <code>~= 1.3.1</code> <code>~= 1.2.3</code> 20.0.x <code>~= 0.5.2</code> <code>~= 1.2.0</code> <code>~= 1.1.7</code> 1.5.3+ <code>~= 0.4.0</code> <code>~= 1.0.1</code> <code>~= 1.0.2</code> <p>(Originally posted at nipreps/fmriprep#2054)</p>"},{"location":"devs/versions/#dmriprep","title":"dMRIPrep","text":"<p>(Work in progress)</p>"},{"location":"devs/versions/#smriprep","title":"sMRIPrep","text":"<p>sMRIPrep requires niworkflows and generally must depend on one minor series of niworkflows for the duration of an sMRIPrep minor series. Each sMRIPrep series may also be depended on for an fMRIPrep series and/or a dMRIPrep series. Noting these dependencies here should make it easier to track when a new minor series needs to be created.</p> sMRIPrep series NiWorkflows series TemplateFlow series 0.12.x <code>~=1.8.0</code> ... 0.10.x <code>~= 1.7.0</code> <code>&gt;= 0.6</code> 0.9.x <code>~= 1.6.0</code> <code>&gt;= 0.6</code> 0.8.x <code>~= 1.4.0</code> <code>&gt;= 0.6</code> 0.7.x <code>~= 1.3.0</code> <code>~= 0.6</code> 0.6.x <code>~= 1.2.0</code> <code>~= 0.6</code> 0.5.x <code>~= 1.1.5</code> <code>~= 0.4.2</code> <p>(Originally posted at nipreps/smriprep#172)</p>"},{"location":"devs/versions/#mriqc","title":"MRIQC","text":"<p>(Work in progress)</p>"},{"location":"intro/nipreps/","title":"Framework","text":""},{"location":"intro/nipreps/#building-on-fmripreps-success-story","title":"Building on fMRIPrep's success story","text":"<p>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 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.</p>"},{"location":"intro/nipreps/#leveraging-bids","title":"Leveraging BIDS","text":"<p>NiPreps leverage the Brain Imaging Data Structure (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.</p>"},{"location":"intro/nipreps/#architecture","title":"Architecture","text":"<p>The NiPreps framework (Figure 1) encompasses a wide array of software projects organized into three layers of scientific software:</p> <ul> <li>Software infrastructure: including quite mature projects such as NiPype and NiBabel; 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).</li> <li>Middleware: these are utilities that generalize their functionalities across the end-user tools.     These utilities cover foundational processing methodologies (e.g., NiWorkflows and SDCflows), the crowdsourcing of metadata (e.g., MRIQC Web-API), and the support for deep learning models (MRIQC-nets).</li> <li>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.</li> </ul> <p> </p>"},{"location":"intro/nipreps/#projects","title":"Projects","text":"<ul> <li>fMRIPrep (GitHub): fMRI Preprocessing</li> <li>dMRIPrep (GitHub): dMRI Preprocessing</li> <li>sMRIPrep (GitHub): Structural MRI Preprocessing</li> <li>MRIQC (GitHub): MRI quality control</li> <li>SDCflows (GitHub): Susceptibility-derived distortion correction (SDC) workflows</li> <li>NiWorkflows (GitHub): General/miscellaneous workflow utilities</li> <li>TemplateFlow: A registry of neuroimaging templates and spatial mappings between them.</li> <li>NiTransforms (GitHub)</li> </ul>"},{"location":"intro/nipreps/#early-stage-projects","title":"Early-stage projects","text":"<ul> <li>NiRodents (GitHub): middleware adaptations for small animals imaging.</li> <li>NiBabies (GitHub): middleware adaptations for infant imaging.</li> </ul>"},{"location":"intro/transparency/","title":"Transparency of workflows","text":"<p>NiPreps adopt fMRIPrep's foundations, and particularly resonate with the transparency principles. As discussed in (Esteban et al., 2019 -- preprint):</p> <p>The rapid increase in the volume and diversity of data, as well as the evolution of available techniques for processing and analysis, presents an opportunity for considerable advancement of research in neuroscience. The drawback resides in the need for progressively more complex analysis workflows that rely on decreasingly interpretable models of the data. Such context encourages \u2018black-box\u2019 solutions that efficiently perform a valuable service but do not provide insights into how the tool has transformed the data into the expected outputs. Black boxes obscure important steps in the inductive process mediating between experimental measurements and reported findings. This way of moving forward risks producing a future generation of cognitive neuroscientists who have become experts in sophisticated computational methods but have little to no working knowledge of how their data were transformed through processing. Transparency is often identified as a remedy for these problems. fMRIPrep ascribes to \u2018glass-box\u2019 principles, which are defined in opposition to the many different facets or levels at which black-box solutions are opaque. The visual reports that fMRIPrep generates are a crucial aspect of the glass-box approach. Their quality control checkpoints represent the logical flow of preprocessing, allowing scientists to critically inspect and better understand the underlying mechanisms of the workflow. A second transparency element is the citation boilerplate that formalizes all details of the workflow and provides the versions of all involved tools along with references to the corresponding scientific literature. A third asset for transparency is thorough documentation that delivers additional details on each of the building blocks represented in the visual reports and described in the boilerplate. Further, fMRIPrep has been open-source since its inception: users have access to all of the incremental additions to the tool through the history of the version-control system. The use of GitHub grants access to the discussions held during development, allowing one to see how and why the main design decisions were made. The modular design of fMRIPrep enhances its flexibility and improves transparency, as the main features of the software are more easily accessible to potential collaborators. In combination with some coding style and contribution guidelines, this modularity has enabled multiple contributions by peers and the creation of a rapidly growing community that would be difficult to nurture behind closed doors.</p>"},{"location":"intro/transparency/#visual-reports-beyond-quality-control","title":"Visual reports beyond quality control","text":"<p>One foundational component of the NiPreps framework is the Visual Report System. End-user applications such as fMRIPrep or dMRIPrep generate individual reports after their preprocessing. Those visual reports have two fundamental purposes:</p> <ul> <li>assessing the quality of the generated outputs, permitting the user to take quality control actions to eliminate biases originated from inadequate processing; and</li> <li>understanding the workflow, by sequentially presenting the main steps of processing, the user can access the why the tool in particular took these steps ando more geneally why standard preprocessing involves that step.</li> </ul>"},{"location":"intro/transparency/#citation-boilerplates","title":"Citation boilerplates","text":"<p>NiPreps leverage the wealth of existing neuroimaging software that is available to researchers. To give back for standing on the shoulders of giants, NiPreps aim at the most thorough reporting possible crediting all the pieces of the prior knowledge they leverage. With the execution of some particular NiPreps, the application runs some introspection code to formalize the computational graph the particular workflow executed and iterates over all the nodes to extract the relevant articles and communications that should be cited, as well as all software tools and their versions involved. Similarly, ancillary materials such as neuroimaging templates and atlases are reported and cited.</p> <p>All these references and citations are finally collated in a natural language description of the workflow. This description is therefore generated automatically, and contains all the details that are necessary to replicate the processing, as well as the abovementioned references. The text is appended to the visual report, and provided in three formats (markdown, latex and html/plain-text) with an index of citations, so that the user is only required to \"copy-and-paste\" into the Methods section of their papers.</p> <p>Note for reviewers and editors</p> <p>The boilerplate text generated by some NiPreps is intended to allow for clear, consistent description of the preprocessing steps used, in order to improve the reproducibility of studies. We fully intend for it to be copied verbatim, and have released it under the CC0 license, dedicating it to the public domain in jurisdictions that recognize the concept, and assert that we will take no action to enforce copyright in jurisdictions where we cannot disclaim it.</p> <p>We firmly believe that requiring authors to modify this passage will serve no legitimate scientific or literary purpose and can, in fact, serve only to reduce the replicability of the analysis being described by making the preprocessing steps less clear.</p> <p>We recognize that there may be automated plagiarism detection software that will flag the boilerplate text. We would be happy to discuss potential solutions for annotating boilerplate sections of documents to indicate automatic generation, and can update our software to make this annotation simpler for authors.</p>"},{"location":"news/","title":"News and Announcements","text":""},{"location":"news/#register-for-the-nipreps-hackathon-with-the-ohbm23-brainhack","title":"Register for the NiPreps hackathon with the OHBM'23 Brainhack!","text":"<p>We are thrilled to announce that the NiPreps Hackathon's second edition will be part of the upcoming OHBM'23 Brainhack (July 19-21, Maison Notman House, Montreal, Canada).</p> <p>Registration To join us for this incredible event and work on NiPreps-related projects, please fill in our registration form.</p> <p>Please remember to also register on the official webpage of the OHBM Brainhack. You will find all the necessary information, event schedule, and location details on Brainhack's website.</p> <p>Approach and projects We will advance (online) some projects as much as possible before the BrainHack. We are putting together a list of potential projects at https://github.com/orgs/nipreps/projects/8. Please feel free to let us know your ideas and voice your questions. Projects can start at any moment (even at the venue in Montreal) to have the flexibility to accommodate all ideas.</p> <p>Those projects with preliminary work will have project leaders who will organize meetings, coordinate a roadmap and help carry out the necessary tasks.</p> <p>See you in Montreal!</p>"},{"location":"news/#nipreps-roundups-feb-22-2023","title":"NiPreps Roundups  Feb 22, 2023","text":"<p>We resumed the bi-monthly NiPreps Roundups with a first meeting on February 22, 2023.</p>"},{"location":"users/educational/","title":"Educational resources","text":""},{"location":"users/educational/#fmriprep-bootcamp-geneva-2024","title":"fMRIPrep Bootcamp Geneva 2024","text":"<ul> <li>Overview of the fMRI neuroimaging pipeline &amp; fMRIPrep</li> <li>The Brain Imaging Data Structure (BIDS)</li> <li>Day 1: BIDS - Convert a dataset</li> <li>Day 1: Data and HPC</li> <li>Day 1: Containers</li> </ul>"},{"location":"users/educational/#online-books","title":"Online books","text":"<ul> <li>QC-Book, member-initiated tutorial at ISMRM 2022</li> <li>NiPreps Book, developing processing tools for dMRI, ISBI 2021</li> </ul>"},{"location":"users/educational/#qc-protocols-and-standard-operating-procedures","title":"QC protocols and Standard Operating Procedures","text":"<ul> <li>SOPs-cookiecutter, a template repository for version-controlled SOPs. The example template is rendered here</li> </ul>"},{"location":"users/educational/#presentation","title":"Presentation","text":"<ul> <li>Educational Talk at OHBM 2023 - Quality Control in fMRI studies with MRIQC and fMRIPrep</li> </ul>"},{"location":"users/talks/","title":"Talks and presentations","text":"<ul> <li>NiPreps @ BrainHack Seoul 2024</li> <li>Standardizing neuroimaging workflows (Journal Club @ EPFL 2023)</li> <li>Presentation about MRIQC for INCF 2022 (10 min)</li> <li>NiPreps introduction, Educational Session at OHBM 2022</li> <li>Building community workflows, BrainHack Donostia 2020</li> <li>Building communities around reproducible workflows, Open Reproducible Neuroscience workshop 2020</li> <li>Reproducible workflows, Think Open Rovereto Workshop 2020</li> </ul>"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index a129bf9..ec3a16a 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,86 +2,86 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://www.nipreps.org/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/apps/docker/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/apps/framework/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/apps/singularity/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/assets/ORN-Workshop/presentation/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/assets/bhd2020/presentation/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/assets/torw2020/presentation/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/CODE_OF_CONDUCT/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/CONTRIBUTING/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/features/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/licensing/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/community/members/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/devs/devenv/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/devs/releases/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/devs/versions/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/intro/nipreps/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/intro/transparency/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/news/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/users/educational/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
     <url>
          <loc>https://www.nipreps.org/users/talks/</loc>
-         <lastmod>2024-09-04</lastmod>
+         <lastmod>2024-09-05</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 5813c13..2a9d28d 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/users/educational/index.html b/users/educational/index.html
index cfdbaf7..78dfc68 100644
--- a/users/educational/index.html
+++ b/users/educational/index.html
@@ -700,6 +700,15 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#fmriprep-bootcamp-geneva-2024" class="md-nav__link">
+    <span class="md-ellipsis">
+      fMRIPrep Bootcamp Geneva 2024
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#online-books" class="md-nav__link">
     <span class="md-ellipsis">
@@ -874,6 +883,15 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#fmriprep-bootcamp-geneva-2024" class="md-nav__link">
+    <span class="md-ellipsis">
+      fMRIPrep Bootcamp Geneva 2024
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#online-books" class="md-nav__link">
     <span class="md-ellipsis">
@@ -917,6 +935,14 @@
 
 
 <h1 id="educational-resources">Educational resources<a class="headerlink" href="#educational-resources" title="Permanent link">&para;</a></h1>
+<h2 id="fmriprep-bootcamp-geneva-2024">fMRIPrep Bootcamp Geneva 2024<a class="headerlink" href="#fmriprep-bootcamp-geneva-2024" title="Permanent link">&para;</a></h2>
+<ul>
+<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer">Overview of the fMRI neuroimaging pipeline &amp; <em>fMRIPrep</em></a></li>
+<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-02-bids">The Brain Imaging Data Structure (BIDS)</a></li>
+<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-03-bids-convert-a-dataset">Day 1: BIDS - Convert a dataset</a></li>
+<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-04-data-and-hpc">Day 1: Data and HPC</a></li>
+<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-05-containers">Day 1: Containers</a></li>
+</ul>
 <h2 id="online-books">Online books<a class="headerlink" href="#online-books" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="../../qc-book">QC-Book, member-initiated tutorial at ISMRM 2022</a></li>
diff --git a/users/talks/index.html b/users/talks/index.html
index 87a152e..dba9015 100644
--- a/users/talks/index.html
+++ b/users/talks/index.html
@@ -826,14 +826,6 @@
 
 <h1 id="talks-and-presentations">Talks and presentations<a class="headerlink" href="#talks-and-presentations" title="Permanent link">&para;</a></h1>
 <ul>
-<li>fMRIPrep Bootcamp Geneva 2024<ul>
-<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-01-fmriprep-primer">Day 1: fMRIPrep Primer</a></li>
-<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-02-bids">Day 1: BIDS</a></li>
-<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-03-bids-convert-a-dataset">Day 1: BIDS - Convert a dataset</a></li>
-<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-04-data-and-hpc">Day 1: Data and HPC</a></li>
-<li><a href="../../assets/fmriprep-bootcamp-geneva2024/day1-05-containers">Day 1: Containers</a></li>
-</ul>
-</li>
 <li><a href="../../assets/BrainHack2024">NiPreps @ BrainHack Seoul 2024</a></li>
 <li><a href="../../assets/EPFL2023">Standardizing neuroimaging workflows (Journal Club @ EPFL 2023)</a></li>
 <li><a href="../../assets/INCF22-MRIQC/">Presentation about MRIQC for INCF 2022 (10 min)</a></li>
