First pass Reproin

docs/reproin.rst

@@ -2,47 +2,55 @@
 Reproin 
 ================
 
-This tutorial is based on https://neuroimaging-core-docs.readthedocs.io/en/latest/pages/heudiconv.html#lesson-3-reproin-py
-
-If you don't want to modify a Python file as you did for *heuristic.py*, an alternative is to name your image sequences at the scanner using the *reproin* naming convention. Take some time getting the scanner protocol right, because it is the critical job for running *reproin*. Then a single Docker command converts your DICOMS to the BIDS data structure. There are more details about *reproin* in the 
-.. TODO new link ref:`Links <heudiconv_links>` section above.
-
-* You should already have Docker installed and have downloaded HeuDiConv as described in Lesson 1.
-* Download and unzip the phantom dataset: `reproin_dicom.zip <https://osf.io/4jwk5/>`_ generated here at the University of Arizona on our Siemens Skyra 3T with Syngo MR VE11c software on 2018_02_08.
-* You should see a new directory *REPROIN*. This is a simple reproin-compliant dataset without sessions. Derived dwi images (ADC, FA etc.) that the scanner produced were removed.
-* Change directory to *REPROIN*. The directory structure should look like this::
-
-    REPROIN
-    ├── data
-    └── dicom
-        └── 001
-            └── Patterson_Coben\ -\ 1
-                ├── Localizers_4
-                ├── anatT1w_acqMPRAGE_6
-                ├── dwi_dirAP_9
-                ├── fmap_acq4mm_7
-                ├── fmap_acq4mm_8
-                ├── fmap_dirPA_15
-                └── func_taskrest_16
-
-* From the *REPROIN* directory, run this Docker command::
-
-    docker run --rm -it -v ${PWD}:/base nipy/heudiconv:latest -f reproin --bids  -o /base/data --files /base/dicom/001 --minmeta
-* ``--rm`` means Docker should cleanup after itself
-* ``-it`` means Docker should run interactively
-* ``-v ${PWD}:/base`` binds your current directory to ``/base`` inside the container.  Alternatively, you could provide an **absolute path** to the *REPROIN* directory.
-* ``nipy/heudiconv:latest`` identifies the Docker container to run (the latest version of heudiconv).
+This tutorial is based on `Dianne Patterson's University of Arizona tutorials <https://neuroimaging-core-docs.readthedocs.io/en/latest/pages/heudiconv.html#lesson-3-reproin-py>`_
+
+`Reproin <https://github.com/ReproNim/reproin>`_ is a setup for
+automatic generation of sharable, version-controlled BIDS datasets from
+MR scanners.
+
+If can control how your image sequences are named at the scanner you can
+use the *reproin* naming convention.  
+
+Get Example Dataset
+-------------------
+
+This example uses a phantom dataset: `reproin_dicom.zip <https://osf.io/4jwk5/>`_ generated by the University of Arizona on their Siemens Skyra 3T with Syngo MR VE11c software on 2018_02_08.
+
+The ``REPROIN`` directory is a simple reproin-compliant DICOM (.dcm) dataset without sessions. 
+(Derived dwi images (ADC, FA etc.) that the scanner produced have been removed.::
+
+    [user@local ~/reproin_dicom/REPROIN]$ tree -I "*.dcm"
+
+        REPROIN
+        ├── data
+        └── dicom
+            └── 001
+                └── Patterson_Coben\ -\ 1
+                    ├── Localizers_4
+                    ├── anatT1w_acqMPRAGE_6
+                    ├── dwi_dirAP_9
+                    ├── fmap_acq4mm_7
+                    ├── fmap_acq4mm_8
+                    ├── fmap_dirPA_15
+                    └── func_taskrest_16
+
+Convert and organize
+--------------------
+
+From the ``REPROIN`` directory::
+
+    heudiconv -f reproin --bids  -o data --files dicom/001 --minmeta
+
 * ``-f reproin`` specifies the converter file to use
-* ``-o /base/data/`` specifies the output directory *data*.  If the output directory does not exist, it will be created.
-* ``--files /base/dicom/001`` identifies the path to the DICOM files.
+* ``-o data/`` specifies the output directory *data*.  If the output directory does not exist, it will be created.
+* ``--files dicom/001`` identifies the path to the DICOM files.
 *  ``--minmeta`` ensures that only the minimum necessary amount of data gets added to the JSON file when created.  On the off chance that there is a LOT of meta-information in the DICOM header, the JSON file will not get swamped by it. fmriprep and mriqc are very sensitive to this information overload and will crash, so minmeta provides a layer of protection against such corruption.
 
-That's it.  Below we'll unpack what happened.
 
 Output Directory Structure
-===============================
+--------------------------
 
-*Reproin* produces a hierarchy of BIDS directories like this::
+Heudiconv's Reproin converter produces a hierarchy of BIDS directories::
 
     data
     └── Patterson
@@ -59,6 +67,7 @@ Output Directory Structure
                 ├── fmap
                 └── func
 
+**TODO --- WHAT IS A REGION AND EXAM???**
 
 * The dataset is nested under two levels in the output directory: *Region* (Patterson) and *Exam* (Coben). *Tree* is reserved for other purposes at the UA research scanner.
 * Although the Program *Patient* is not visible in the output hierarchy, it is important.  If you have separate sessions, then each session should have its own Program name.
@@ -67,7 +76,9 @@ Output Directory Structure
 * The hidden directory is generated: *REPROIN/data/Patterson/Coben/.heudiconv*.
 
 At the Scanner
-====================
+**************
+
+**TODO --- Is this generally useful or should be cut???**
 
 Here is this phantom dataset displayed in the scanner dot cockpit.  The directory structure is defined at the top: *Patterson >> Coben >> Patient*
 
@@ -78,10 +89,10 @@ Here is this phantom dataset displayed in the scanner dot cockpit.  The director
 
 
 Reproin Scanner File Names
-==============================
+****************************
 
 * For both BIDS and *reproin*, names are composed of an ordered series of key-value pairs.  Each key and its value are joined with a dash ``-`` (e.g., ``acq-MPRAGE``, ``dir-AP``).  These key-value pairs are joined to other key-value pairs with underscores ``_``. The exception is the modality label, which is discussed more below.
-* *Reproin* scanner sequence names are simplified relative to the final BIDS output and generally conform to this scheme (but consult the `reference <https://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py>`_ for additional options): ``sequence type-modality label`` _ ``session-session name`` _ ``task-task name`` _ ``acquisition-acquisition detail`` _ ``run-run number`` _ ``direction-direction label``::
+* *Reproin* scanner sequence names are simplified relative to the final BIDS output and generally conform to this scheme (but consult the `reproin heuristics file <https://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py>`_ for additional options): ``sequence type-modality label`` _ ``session-session name`` _ ``task-task name`` _ ``acquisition-acquisition detail`` _ ``run-run number`` _ ``direction-direction label``::
 
     | func-bold_ses-pre_task-faces_acq-1mm_run-01_dir-AP
 
@@ -126,5 +137,3 @@ Reproin Scanner File Names
     `-- task-rest_bold.json
 
 * Note that despite all the the different subject names (e.g., ``01``, ``001`` and ``001_001``), the subject is labeled ``sub-001``.
-
-