Document new features + docker

.github/workflows/publish_doc.yaml

@@ -6,6 +6,7 @@ on:
   push:
     branches:
       - master
+      - dev
     tags:
       - '[0-9]+.[0-9]+.[0-9]+'
   release:
@@ -50,6 +51,7 @@ jobs:
           dcm2bids -h > docs_helper/help.txt
           dcm2bids_helper -h > docs_helper/helper.txt
           dcm2bids_scaffold -h > docs_helper/help_scaffold.txt
+          echo "export VERSION=$(dcm2bids -v | awk '/dcm2bids/ {print $3}')" > docs_helper/version.txt
 
       - name: Set git credentials
         run: |
@@ -76,7 +78,7 @@ jobs:
           mike deploy -p ${{ github.ref_name }}
 
       - name: Deploy dev version
-        if: ${{ github.ref == 'refs/heads/master' }}
+        if: ${{ github.ref == 'refs/heads/dev' }}
         run: |
           VERSION=$(dcm2bids -v | awk '/dcm2bids/ {print $3}')
           echo "Version: $VERSION"

.gitignore

@@ -139,3 +139,4 @@ tests/data/*
 docs_helper/help.txt
 docs_helper/help_scaffold.txt
 docs_helper/helper.txt
+docs_helper/version.txt

README.md

@@ -48,7 +48,8 @@ Please take a look at the [documentation][dcm2bids-doc] to:
 
 * [Learn about bids][bids-spec] with some dataset [examples][bids-examples]
 * [Install dcm2bids][dcm2bids-install]
-* [Follow the tutorial][dcm2bids-tutorial]
+* [Use docker and Apptainer/Singularity][dcm2bids-container]
+* [Follow the tutorials][dcm2bids-tutorial]
 * [Seek for more advanced usage][dcm2bids-advanced]
 
 ## Issues and Questions
@@ -68,6 +69,7 @@ Before posting your question, you may want to first browse through questions tha
 [dcm2bids-install]: https://unfmontreal.github.io/Dcm2Bids/latest/get-started/install/
 [dcm2bids-tutorial]: https://unfmontreal.github.io/Dcm2Bids/latest/tutorial/first-steps/#tutorial-first-steps
 [dcm2bids-advanced]: https://unfmontreal.github.io/Dcm2Bids/latest/advanced/
+[dcm2bids-container]: https://unfmontreal.github.io/Dcm2Bids/latest/how-to/container/
 [dcm2bids-upgrade]: https://unfmontreal.github.io/Dcm2Bids/dev/upgrade/
 [dcm2bids-issues]: https://github.com/UNFmontreal/Dcm2Bids/issues
 [dcm2niix-install]: https://github.com/rordenlab/dcm2niix#install

dcm2bids/version.py

@@ -2,8 +2,8 @@
 
 # Format expected by setup.py and doc/source/conf.py: string of form "X.Y.Z"
 _version_major = 3
-_version_minor = 1
-_version_micro = 1
+_version_minor = 2
+_version_micro = 0
 _version_extra = ''
 
 # Construct full version string from these.

docs/get-started/install.md

@@ -9,6 +9,25 @@ date: 2022-04-17
 
 There are several ways to install dcm2bids.
 
+## Containers
+
+We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator.
+You can install it using [Docker][docker] or [Apptainer/Singularity][apptainer].
+
+=== "Docker"
+
+    ```
+    --8<-- "docs_helper/version.txt"
+    docker pull unfmontreal/dcm2bids:${VERSION}
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    --8<-- "docs_helper/version.txt"
+    apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:${VERSION}
+    ```
+
 ## Installing binary executables
 
 From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
@@ -104,7 +123,7 @@ dcm2bids.
 ### Python
 
 As dcm2bids is a Python package, the first prerequisite is that Python must be
-installed on the machine you will use dcm2bids. You will need **Python 3.7 or
+installed on the machine you will use dcm2bids. You will need **Python 3.8 or
 above** to run dcm2bids properly.
 
 If you are unsure what version(s) of Python is available on your machine, you
@@ -129,7 +148,7 @@ line.
     >>> exit()
     ```
 
-If your system-wide version of Python is lower 3.7, it is okay. We will make
+If your system-wide version of Python is lower 3.8, it is okay. We will make
 sure to use a higher version in the isolated environment that will be created
 for dcm2bids. The important part is to verify that Python is installed.
 
@@ -163,7 +182,7 @@ the next section.
 
 We recommend to install all the dependencies at once when installing dcm2bids on
 a machine or server. As mentioned above the minimal installation requires only
-dcm2bids, dcm2niix and Python >= 3.7. For ease of use and to make sure we have a
+dcm2bids, dcm2niix and Python >= 3.8. For ease of use and to make sure we have a
 reproducible environment, we recommend to use a dedicated environment through
 [conda][conda] or, for those who have it installed, [Anaconda][anaconda]. Note
 that you **don't need** to use specifically them to use dcm2bids, but it will
@@ -260,7 +279,7 @@ name: dcm2bids
 channels:
   - conda-forge
 dependencies:
-  - python>=3.7
+  - python>=3.8
   - dcm2niix
   - dcm2bids
 ```
@@ -277,7 +296,7 @@ In short, here's what the fields mean:
   environment. If you are creating an environment for your analysis project,
   this is where you would list other dependencies such as `nilearn`, `pandas`,
   and especially as `pip` since you don't want to use the pip outside of your
-  environment Note that we specify `python>=3.7` to make sure the requirement is
+  environment Note that we specify `python>=3.8` to make sure the requirement is
   satisfied for dcm2bids as the newer version of dcm2bids may face issue with
   Python 3.6 and below.
 
@@ -353,18 +372,6 @@ Voilà, you are ready to use dcm2bids or at least
 
 [Go to the How-to section](../../how-to/){ .md-button }
 
-## Containers
-
-We also provide a container image that includes both dcm2niix and dcm2bids which
-you can install using [Docker][docker] or [Apptainer/Singularity][apptainer].
-
-=== "Docker"
-
-    `docker pull unfmontreal/dcm2bids:latest`
-
-=== "Apptainer/Singularity"
-
-    `singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest `
 
 ## Summary of the steps
 
@@ -384,7 +391,7 @@ containers:
             channels:
                 - conda-forge
             dependencies:
-                - python>=3.7
+                - python>=3.8
                 - dcm2niix
                 - dcm2bids
 

docs/how-to/container.md

@@ -0,0 +1,134 @@
+# dcm2bids with Docker and Apptainer / Singularity
+
+We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator. You can find it on [Docker Hub](https://hub.docker.com/r/unfmontreal/dcm2bids).
+
+You can install it using [Docker](https://www.docker.com/get-started) or [Apptainer/Singularity](https://www.apptainer.org).
+
+## Prerequisites
+
+Before you begin, make sure you have at least one of the following installed:
+
+- Docker: [Download and install Docker](https://www.docker.com/get-started)
+- Apptainer, formerly known as Singularity : [Download and install Apptainer](https://apptainer.org/docs/admin/main/installation.html)
+
+!!! note
+    If you are using a HPC cluster, Apptainer is the recommended choice and is probably installed on your system. Simply load the module (e.g., 
+    `module load apptainer`) and use the `apptainer` command,
+
+## Step 1: Pull the dcm2bids container
+
+To start, you can either pull the dcm2bids image from the Docker Hub repository or [build it from the Dockerfile in the repository](https://github.com/UNFmontreal/Dcm2Bids/blob/dev/Dockerfile).:
+
+
+
+=== "Docker"
+
+    ```
+    --8<-- "docs_helper/version.txt"
+    docker pull unfmontreal/dcm2bids:${VERSION}
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    --8<-- "docs_helper/version.txt"
+    apptainer pull dcm2bids_${VERSION}.sif docker://unfmontreal/dcm2bids:${VERSION}
+    ```
+
+## Step 2: Test dcm2bids
+
+The default command, or the point of entry, for the container is `dcm2bids`. So every time you run the container, you can pass the `dcm2bids` arguments and options directly. To test the container, run the following command to display the help message for the `dcm2bids` command.
+
+=== "Docker"
+
+    ```
+    docker run --rm -it unfmontreal/dcm2bids:${VERSION} --help
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer run -e --containall dcm2bids.sif --help
+    ```
+
+## Step 3: Run `dcm2bids_scaffold`
+
+To run `dcm2bids_scaffold` with Apptainer/Singularity, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). You need to bind the respective volumes.
+
+=== "Docker"
+
+    ```
+    docker run --rm -it \
+    --entrypoint /venv/bin/dcm2bids_scaffold \
+    -v /path/to/bids:/bids \
+    unfmontreal/dcm2bids:${VERSION} -o /bids/new_scaffold
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer exec \
+    -e --containall \
+    -B /path/to/bids:/bids \
+    dcm2bids.sif dcm2bids_scaffold -o /bids/new_scaffold
+    ```
+
+
+## Step 4: Run `dcm2bids_helper`
+
+To run `dcm2bids_helper` with Apptainer/Singularity, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). To bind the respective volumes, you have two options:
+
+1. Put the input data in the same parent directory as the output directory.
+2. Specify the input data directory as a separate volume.
+
+If you bind the newly scaffolded directory on its own, you can simply use the `-o /bids` instead of having to specify the full path to the scaffolded directory. Same goes for the input data directory, if the input data directory is one subject, you can bind it directly to `/dicoms`. If it is the parent directory of multiple subjects, you can bind it to `/dicoms` and specify the specific subject directory (e.g, `-d /dicoms/subject-01`).
+
+=== "Docker"
+
+    ```
+    docker run --rm -it --entrypoint /venv/bin/dcm2bids_helper \
+    -v /path/to/dicoms:/dicoms:ro \
+    -v /path/to/bids/new_scaffold:/bids \
+    unfmontreal/dcm2bids:${VERSION} -o /bids -d /dicoms
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer exec \
+    -e --containall \
+    -B /path/to/dicoms:/dicoms:ro \
+    -B /path/to/bids/new_scaffold:/bids \
+    dcm2bids.sif dcm2bids_helper -o /bids -d /dicoms
+    ```
+
+## Step 5: Run `dcm2bids`
+
+You can use `run` as in Step 2 or use `exec dcm2bids` to run `dcm2bids` with the appropriate arguments and options. You need to bind the respective volumes.
+
+You can put input data in the same parent directory as the output directory, or you can specify the input data directory as a separate volume. You must also specify the path to the configuration file. If you use the scaffolded dataset, the config file is usually in the `code/` directory.
+
+You can also [deface your data](use-advanced-commands.md#post_op) and [validate your BIDS data](use-advanced-commands.md#-bids_validate) using the `--bids_validate` flag.
+
+=== "Docker"
+
+    ```
+    docker run --rm -it \
+    -v /path/to/dicoms:/dicoms:ro \
+    -v /path/to/config.json:/config.json:ro \
+    -v /path/to/bids/new_scaffold:/bids \
+    unfmontreal/dcm2bids:${VERSION} --auto_extract_entities --bids_validate \
+    -o /bids -d /dicoms -c /config.json -p 001
+    ```
+
+=== "Apptainer/Singularity"
+
+    ```
+    apptainer run \
+    -e --containall \
+    -B /path/to/dicoms:/dicoms:ro \
+    -B /path/to/config.json:/config.json:ro \
+    -B /path/to/bids/new_scaffold:/bids \
+    dcm2bids.sif --auto_extract_entities --bids_validate \
+    -o /bids -d /dicoms -c /config.json -p 001
+    ```

docs/how-to/create-config-file.md

@@ -128,9 +128,8 @@ specifications][bids-spec].
 For a longer example of a Dcm2Bids config json, see
 [here](https://github.com/unfmontreal/Dcm2Bids/blob/master/example/config.json).
 
-Note that the different bids labels must come in a very specific order to be
-bids valid filenames. If the custom_entities fields that are entered that are in
-the wrong order, then dcm2bids will reorder them for you.
+
+Note that the different BIDS entities have a specific order to be considered valid filenames, as specified in the [Entity table of the BIDS Specification](https://bids-specification.readthedocs.io/en/stable/appendices/entity-table.html). If the custom_entities fields are entered in a different order, dcm2bids will automatically reorder them for you.
 
 For example if you entered:
 
@@ -149,6 +148,12 @@ WARNING:dcm2bids.structure:✅ Filename was reordered according to BIDS entity t
 custom_entities could also be combined with extractors. See
 [custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
 
+### Manuel ordering
+
+!!! tip "`--do_not_reorder_entities`"
+
+    If you prefer to have manual control over the order of `custom_entities`, you can use the `--do_not_reorder_entities` flag. This flag allows you to keep the order defined by you, the user, in the `custom_entities` field. However, please note that this flag cannot be used in conjunction with the `--auto_extract_entities` flag. Also please keep in mind that a custom non-BIDS compliant entity order may preclude downstream usage of BIDS apps such as fMRIPrep.
+
 ## sidecar_changes, id and IntendedFor
 
 Optional field to change or add information in a sidecar.

docs/how-to/index.md

@@ -16,6 +16,8 @@ title: How-to guides
 
 - [Use advanced commands](./use-advanced-commands.md)
 
+- [Use dcm2bids with Docker or Apptainer/Singularity](./container.md)
+
 ## Development and Community
 
 - [Contribute to dcm2bids](./contributing.md)