diff --git a/docs/reproin.rst b/docs/reproin.rst index 870d39f9..a925ee18 100644 --- a/docs/reproin.rst +++ b/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 ` 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 `_ 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 `_ + +`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 `_ 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 `_ 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 `_ 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``. - -