Merge pull request #734 from asmacdo/add-dianne-tutorials

Add dianne tutorials

LICENSE

@@ -1,4 +1,4 @@
-Copyright [2014-2019] [Heudiconv developers]
+Copyright [2014-2024] [HeuDiConv developers]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -11,3 +11,10 @@ Copyright [2014-2019] [Heudiconv developers]
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+
+Some parts of the codebase/documentation are borrowed from other sources:
+
+- HeuDiConv tutorial from https://bitbucket.org/dpat/neuroimaging_core_docs/src
+
+  Copyright 2023 Dianne Patterson

README.rst

@@ -115,3 +115,17 @@ Docker image preparation being found in ``.github/workflows/release.yml``.
 ---------------------
 
 - https://github.com/courtois-neuromod/ds_prep/blob/main/mri/convert/heuristics_unf.py
+
+
+Support
+-------
+
+All bugs, concerns and enhancement requests for this software can be submitted here:
+https://github.com/nipy/heudiconv/issues.
+
+If you have a problem or would like to ask a question about how to use ``heudiconv``,
+please submit a question to `NeuroStars.org <http://neurostars.org/tags/heudiconv>`_ with a ``heudiconv`` tag.
+NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.
+
+All previous ``heudiconv`` questions are available here:
+http://neurostars.org/tags/heudiconv/

docs/commandline.rst

@@ -0,0 +1,12 @@
+=============
+CLI Reference
+=============
+
+``heudiconv`` processes DICOM files and converts the output into user defined
+paths.
+
+.. argparse::
+   :ref: heudiconv.cli.run.get_parser
+   :prog: heudiconv
+   :nodefault:
+   :nodefaultconst:

docs/container.rst

@@ -0,0 +1,49 @@
+==============================
+Using heudiconv in a Container
+==============================
+
+If heudiconv is :ref:`installed via a Docker container <install_container>`, you
+can run the commands in the following format::
+   
+    docker run nipy/heudiconv:latest [heudiconv options]
+
+So a user running via container would check the version with this command::
+
+    docker run nipy/heudiconv:latest --version
+
+Which is equivalent to the locally installed command::
+
+    heudiconv --version
+
+Bind mount
+----------
+
+Typically, users of heudiconv will be operating on data that is on their local machine. We can give heudiconv access to that data via a ``bind mount``, which is the ``-v`` syntax.
+
+Once common pattern is to share the working directory with ``-v $PWD:$PWD``, so heudiconv will behave as though it is installed on your system. However, you should be aware of how permissions work depending on your container toolset.
+
+
+Docker Permissions
+******************
+
+When you run a container with docker without specifying a user, it will be run as root.
+This isn't ideal if you are operating on data owned by your local user, so for ``Docker`` it is recommended to specify that the container will run as your user.::
+
+    docker run --user=$(id -u):$(id -g) -e "UID=$(id -u)" -e "GID=$(id -g)" --rm -t -v $PWD:$PWD nipy/heudiconv:latest --version
+
+Podman Permissions
+******************
+
+When running Podman without specifying a user, the container is run as root inside the container, but your user outside of the container.
+This default behavior usually works for heudiconv users::
+
+    docker run -v $PWD:PWD nipy/heudiconv:latest --version
+
+Other Common Options
+--------------------
+
+We typically recommend users make use of the following flags to Docker and Podman
+
+* ``-it`` Interactive terminal
+* ``--rm`` Remove the changes to the container when it completes
+

docs/heuristics.rst

@@ -1,6 +1,6 @@
-=========
-Heuristic
-=========
+===============
+Heuristics File
+===============
 
 The heuristic file controls how information about the DICOMs is used to convert
 to a file system layout (e.g., BIDS). ``heudiconv`` includes some built-in
@@ -12,6 +12,14 @@ covered by the existing heuristics. This section will outline what makes up a
 heuristic file, and some useful functions available when making one.
 
 
+Provided Heuristics
+-------------------
+
+Running ``heudiconv`` without a heuristic file results in the generation of a skeleton for the user to customize to their needs. 
+
+``heudiconv`` also provides more than 10 additional heuristics, which can be seen `here <https://github.com/nipy/heudiconv/tree/master/heudiconv/heuristics>`_
+These heuristic files are documented in their code comments.
+
 Components
 ==========
 

docs/index.rst

@@ -14,7 +14,9 @@ Contents
 
    installation
    changes
-   usage
-   heuristics
    tutorials
+   heuristics
+   commandline
+   container
    api
+

docs/installation.rst

@@ -4,6 +4,7 @@ Installation
 
 ``Heudiconv`` is packaged and available from many different sources.
 
+.. _install_local:
 
 Local
 =====
@@ -21,23 +22,24 @@ subsequently it would be able to download and install dcm2niix binary.
 On Debian-based systems, we recommend using `NeuroDebian <http://neuro.debian.net>`_,
 which provides the `heudiconv package <http://neuro.debian.net/pkgs/heudiconv.html>`_.
 
+.. _install_container:
 
-Docker
-======
-If `Docker <https://docs.docker.com/install/>`_ is available on your system, you
-can visit `our page on Docker Hub <https://hub.docker.com/r/nipy/heudiconv/tags>`_
-to view available releases. To pull the latest release, run::
+Containers
+==========
 
-    $ docker pull nipy/heudiconv:latest
+Our container image releases are availe on `our Docker Hub <https://hub.docker.com/r/nipy/heudiconv/tags>`_
 
-Note that when using HeuDiConv via ``docker run``, you might need to provide your user and group IDs so they map correspondingly
-within the container, i.e.::
+If `Docker <https://docs.docker.com/install/>`_ is available on your system, you can pull the latest release::
 
-    $ docker run --user=$(id -u):$(id -g) -e "UID=$(id -u)" -e "GID=$(id -g)" --rm -t -v $PWD:$PWD nipy/heudiconv:latest [OPTIONS TO FOLLOW]
+    $ docker pull nipy/heudiconv:latest
 
 Additionally, HeuDiConv is available through the Docker image at `repronim/reproin <https://hub.docker.com/r/repronim/reproin>`_ provided by
 `ReproIn heuristic project <http://reproin.repronim.org>`_, which develops the ``reproin`` heuristic.
 
+To maintain provenance, it is recommended that you use the ``latest`` tag only when testing out heudiconv. 
+Otherwise, it is recommended that you use an explicit version and record that information alongside the produced data.
+
+
 Singularity
 ===========
 If `Singularity <https://www.sylabs.io/singularity/>`_ is available on your system,

docs/quickstart.rst

@@ -0,0 +1,92 @@
+Quickstart
+==========
+
+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>`_
+
+This guide assumes you have already :ref:`installed heudiconv and dcm2niix <install_local>` and 
+demonstrates how to use the heudiconv tool with a provided `heuristic.py` to convert DICOMS into the BIDS data structure.
+
+.. _prepare_dataset:
+
+Prepare Dataset
+***************
+
+Download and unzip `sub-219_dicom.zip <https://datasets.datalad.org/?dir=/repronim/heudiconv-tutorial-example/>`_. 
+
+We will be working from a directory called MRIS. Under the MRIS directory is the *dicom* subdirectory: Under the subject number *219* the session *itbs* is nested.  Each dicom sequence folder is nested under the session::
+
+    dicom
+    └── 219
+        └── itbs
+            ├── Bzero_verify_PA_17
+            ├── DTI_30_DIRs_AP_15
+            ├── Localizers_1
+            ├── MoCoSeries_19
+            ├── MoCoSeries_31
+            ├── Post_TMS_restingstate_30
+            ├── T1_mprage_1mm_13
+            ├── field_mapping_20
+            ├── field_mapping_21
+            └── restingstate_18
+    Nifti
+    └── code 
+        └── heuristic1.py
+
+Basic Conversion
+****************
+
+Next we will use heudiconv convert DICOMS into the BIDS data structure.
+The example dataset includes an example heuristic file, `heuristic1.py`.
+Typical use of heudiconv will require the creation and editing of your :doc:`heuristics file <heuristics>`, which we will cover
+in a :doc:`later tutorial <custom-heuristic>`.
+
+    .. note:: Heudiconv requires you to run the command from the parent
+              directory of both the Dicom and Nifti directories, which is `MRIS` in
+              our case.
+
+Run the following command::
+
+    heudiconv  --files dicom/219/itbs/*/*.dcm -o Nifti -f Nifti/code/heuristic1.py -s 219 -ss itbs -c dcm2niix -b --minmeta --overwrite
+
+
+* We specify the dicom files to convert with `--files`
+* The heuristic file is provided with the `-f` option
+* We tell heudiconv to place our output in the Nifti dir with `-o`
+* `-b` indicates that we want to output in BIDS format
+* `--minmeta` guarantees that meta-information in the dcms does not get inserted into the JSON sidecar. This is good because the information is not needed but can overflow the JSON file causing some BIDS apps to crash.
+
+Output
+******
+
+The *Nifti* directory will contain a bids-compliant subject directory::
+    
+    
+        └── sub-219
+            └── ses-itbs
+                ├── anat
+                ├── dwi
+                ├── fmap
+                └── func
+    
+The following required BIDS text files are also created in the Nifti directory. Details for filling in these skeleton text files can be found under `tabular files <https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#tabular-files>`_ in the BIDS specification::
+    
+        CHANGES
+        README
+        dataset_description.json
+        participants.json
+        participants.tsv
+        task-rest_bold.json
+    
+Validation
+**********
+
+Ensure that everything is according to spec by using `bids validator <https://bids-standard.github.io/bids-validator/>`_ 
+
+Click `Choose File` and then select the *Nifti* directory.  There should be no errors (though there are a couple of warnings).
+
+      .. Note:: Your files are not uploaded to the BIDS validator, so there are no privacy concerns!
+
+Next 
+****
+
+In the following sections, you will modify *heuristic.py* yourself so you can test different options and understand how to work with your own data.