Merge pull request #223 from arnaudbore/update_doc_v3

Improve doc for v3.0.0

Author: arnaudbore

README.md

@@ -24,6 +24,16 @@ Your friendly DICOM converter.
 
 `dcm2bids` reorganises NIfTI files using [dcm2niix][dcm2niix-github] into the [Brain Imaging Data Structure][bids] (BIDS).
 
+
+## Major upgrade with dcm2bids >=3.0.0
+
+⚠️ Breaking changes alert ⚠️
+
+**dcm2bids>=3.0.0 is not compatible with config files made for v2.1.9 and below**.
+In order to develop dcm2bids new features we had to rewrite some of its code.  
+Since v3.0.0, dcm2bids has become **more powerful** and **more flexible** while reducing the burden of creating config files. Porting your config file should be relatively easy by following the [How-to upgrade][dcm2bids-upgrade] page.
+If you have any issues with it don't hesitate to report it on [Neurostars][neurostars-dcm2bids].
+
 ## Scope
 
 `dcm2bids` is a community-centered project. It aims to be a friendly,
@@ -55,12 +65,13 @@ Before posting your question, you may want to first browse through questions tha
 [bids-examples]: https://github.com/bids-standard/bids-examples
 [bids-spec]: https://bids-specification.readthedocs.io/en/stable/
 [dcm2bids-doc]: https://unfmontreal.github.io/Dcm2Bids
-[dcm2bids-install]: https://unfmontreal.github.io/Dcm2Bids/docs/get-started/install/
-[dcm2bids-tutorial]: https://unfmontreal.github.io/Dcm2Bids/docs/tutorial/first-steps/#tutorial-first-steps
-[dcm2bids-advanced]: https://unfmontreal.github.io/Dcm2Bids/docs/advanced/
+[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-upgrade]: https://unfmontreal.github.io/Dcm2Bids/latest/upgrade/
 [dcm2bids-issues]: https://github.com/UNFmontreal/Dcm2Bids/issues
 [dcm2niix-install]: https://github.com/rordenlab/dcm2niix#install
 [dcm2niix-github]: https://github.com/rordenlab/dcm2niix
 [neurostars]: https://neurostars.org/
 [neurostars-dcm2bids]: https://neurostars.org/tag/dcm2bids
-[dcm2bids-contributing]:  https://unfmontreal.github.io/Dcm2Bids/CONTRIBUTING
+[dcm2bids-contributing]:  https://unfmontreal.github.io/Dcm2Bids/latest/how-to/contributing/

dcm2bids/cli/dcm2bids.py

@@ -49,7 +49,7 @@ def _build_arg_parser():
     p.add_argument("--auto_extract_entities",
                    action='store_true',
                    help="If set, it will automatically try to extract entity"
-                   "information [task, dir, echo] based on the suffix and dataType."
+                   "information [task, dir, echo] based on the suffix and datatype."
                    " [%(default)s]")
 
     p.add_argument("--bids_validate",

dcm2bids/version.py

@@ -4,7 +4,7 @@
 _version_major = 3
 _version_minor = 0
 _version_micro = 0
-_version_extra = 'dev'
+_version_extra = 'rc1'
 
 # Construct full version string from these.
 _ver = [_version_major, _version_minor]

docs/changelog.md docs/changelog/index.mddocs/changelog.md renamed to docs/changelog/index.md

@@ -37,5 +37,5 @@ function:
 [installation]: ./install.md
 [tutorial]: ../tutorial/first-steps.md
 [how-to]: ../how-to
-[reference]: /reference/dcm2bids
+[reference]: ../dcm2bids
 [get-help]: ../how-to/get-help.md

docs/get-started/index.md

@@ -7,6 +7,76 @@ date: 2022-04-17
 
 # Installation
 
+There are several ways to install dcm2bids.
+
+## Installing binary executables
+
+From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
+(debian-based and rhel-based).
+
+They can easily been downloaded from
+[the release page](https://github.com/UNFmontreal/Dcm2Bids/releases/latest).
+
+Once downloaded, you should be able to extract the `dcm2bids`,
+`dcm2bids_scaffold`, and `dcm2bids_helper` files and use them with the full
+path.
+
+=== "Example on Ubuntu 22.04"
+
+    ```bash
+    sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.rc1.tar.gz
+    sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
+    sam:~/software$ cd ../data
+    sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project
+    ```
+
+=== "Ouput"
+
+    ```bash
+    sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.0rc1.tar.gz
+    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                  Dload  Upload   Total   Spent    Left  Speed
+    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
+    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
+    100 40.6M  100 40.6M    0     0  23.2M      0  0:00:01  0:00:01 --:--:-- 36.4M
+
+    sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
+    dcm2bids
+    dcm2bids_helper
+    dcm2bids_scaffold
+
+    sam:~/software$ cd ../data
+
+    sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project
+    INFO    | --- dcm2bids_scaffold start ---
+    INFO    | Running the following command: /home/sam/software/dcm2bids_scaffold -o new-bids-project
+    INFO    | OS version: Linux-5.15.0-76-generic-x86_64-with-glibc2.31
+    INFO    | Python version: 3.10.12 | packaged by conda-forge | (main, Jun 23 2023, 22:40:32) [GCC 12.3.0]
+    INFO    | dcm2bids version: 3.0.rc1
+    INFO    | Checking for software update
+    INFO    | Currently using the latest version of dcm2bids.
+    INFO    | The files used to create your BIDS directory were taken from https://github.com/bids-standard/bids-starter-kit.
+
+    INFO    | Tree representation of new-bids-project/
+    INFO    | new-bids-project/
+    INFO    | ├── code/
+    INFO    | ├── derivatives/
+    INFO    | ├── sourcedata/
+    INFO    | ├── tmp_dcm2bids/
+    INFO    | │   └── log/
+    INFO    | │       └── scaffold_20230716-122220.log
+    INFO    | ├── .bidsignore
+    INFO    | ├── CHANGES
+    INFO    | ├── dataset_description
+    INFO    | ├── participants.json
+    INFO    | ├── participants.tsv
+    INFO    | └── README
+    INFO    | Log file saved at new-bids-project/tmp_dcm2bids/log/scaffold_20230716-122220.log
+    INFO    | --- dcm2bids_scaffold end ---
+    ```
+
+## Installing using pip or conda
+
 Before you can use dcm2bids, you will need to get it installed. This page guides
 you through a minimal, typical dcm2bids installation workflow that is sufficient
 to complete all dcm2bids tasks.
@@ -21,6 +91,8 @@ dcm2bids.
 
 ??? tip "You just want the installation command?"
 
+    You can use the binaries provided with each release (starting with dcm2bids>=3)
+
     If you are used to installing packages, you can get it from PyPI or conda:
 
     `pip install dcm2bids`
@@ -134,8 +206,9 @@ installed and correctly setup on your computer as it is the easiest way to
 install dcm2bids and its dependencies on any OS. We assume that if you want to
 install it in a different way, you have enough skills to do it on your own.
 
-If you installed Anaconda and want to use the graphical user interface (GUI), you can follow the steps as
-demonstrated below and only read the steps until the end of the installation guide.
+If you installed Anaconda and want to use the graphical user interface (GUI),
+you can follow the steps as demonstrated below and only read the steps until the
+end of the installation guide.
 
 ??? info "Create your environment with the **Anaconda Navigator** GUI"
 
@@ -168,8 +241,6 @@ But this would install the software in the main environment instead of a
 dedicated one, assuming none were active. This could have atrocious dependencies
 issues in the long-term if you want to install other software.
 
-
-
 #### Create environment.yml
 
 That is exactly why dedicated environments were invented. To help creating

docs/get-started/install.md

@@ -6,53 +6,57 @@
 {
   "descriptions": [
     {
-      "dataType": "anat",
-      "modalityLabel": "T2w",
+      "datatype": "anat",
+      "suffix": "T2w",
       "criteria": {
         "SeriesDescription": "*T2*",
         "EchoTime": 0.1
       },
-      "sidecarChanges": {
+      "sidecar_changes": {
         "ProtocolName": "T2"
       }
     },
     {
-      "dataType": "func",
-      "modalityLabel": "bold",
-      "customLabels": "task-rest",
+      "id": "task-rest",
+      "datatype": "func",
+      "suffix": "bold",
+      "custom_entities": "task-rest",
       "criteria": {
         "ProtocolName": "func_task-*",
         "ImageType": ["ORIG*", "PRIMARY", "M", "MB", "ND", "MOSAIC"]
       }
     },
     {
-      "dataType": "fmap",
-      "modalityLabel": "fmap",
-      "intendedFor": 1,
+      "datatype": "fmap",
+      "suffix": "fmap",
       "criteria": {
         "ProtocolName": "*field_mapping*"
+      },
+      "sidecar_changes": {
+        "IntendedFor": "task_rest"
       }
     },
     {
-      "dataType": "func",
-      "modalityLabel": "bold",
-      "customLabels": "task-learning",
+      "id": "id_task_learning",
+      "datatype": "func",
+      "suffix": "bold",
+      "custom_entities": "task-learning",
       "criteria": {
         "SeriesDescription": "bold_task-learning"
       },
-      "sidecarChanges": {
+      "sidecar_changes": {
         "TaskName": "learning"
       }
     },
     {
-      "dataType": "fmap",
-      "modalityLabel": "epi",
+      "datatype": "fmap",
+      "suffix": "epi",
       "criteria": {
         "SeriesDescription": "fmap_task-learning"
       },
-      "IntendedFor": 2,
-      "sidecarChanges": {
-        "TaskName": "learning"
+      "sidecar_changes": {
+        "TaskName": "learning",
+        "IntendedFor": "id_task_learning"
       }
     }
   ]
@@ -98,7 +102,7 @@ subject to change depending on the dcm2niix version in use.
 You can enter several criteria. **All criteria must match** for a description to
 be linked to a sidecar.
 
-## dataType
+## datatype
 
 It is a mandatory field. Here is a definition from `bids v1.2.0` :
 
@@ -108,12 +112,12 @@ It is a mandatory field. Here is a definition from `bids v1.2.0` :
 > field maps), anat (structural imaging such as T1, T2, etc.), meg
 > (magnetoencephalography), beh (behavioral).
 
-## modalityLabel
+## suffix
 
 It is a mandatory field. It describes the modality of the acquisition like
 `T1w`, `T2w` or `dwi`, `bold`.
 
-## customLabels
+## custom_entities
 
 It is an optional field. For some acquisitions, you need to add information in
 the file name. For resting state fMRI, it is usually `task-rest`.
@@ -124,19 +128,52 @@ specifications][bids-spec].
 For a longer example of a Dcm2Bids config json, see
 [here](https://github.com/unfmontreal/Dcm2Bids/blob/master/example/config.json).
 
-## sidecarChanges
+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.
+
+For example if you entered:
+
+```json
+"custom_entities": "run-01_task-rest"
+```
+
+when running dcm2bids, you will get the following warning:
+
+```bash
+WARNING:dcm2bids.structure:✅ Filename was reordered according to BIDS entity table order:
+                from:   sub-ID01_run-01_task-rest_bold
+                to:     sub-ID01_task-rest_run-01_bold
+```
+
+custom_entities could also be combined with extractors. See
+[custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
+
+## sidecar_changes, id and IntendedFor
 
 Optional field to change or add information in a sidecar.
 
-## intendedFor
+:warning: `IntendedFor` is now considered a sidecar_changes.
+
+Example:
+
+```json
+{
+  "sidecar_changes": {
+    "IntendedFor": "task_rest"
+  }
+}
+```
+
+If you want to add an `IntendedFor` entry or any extra sidecar linked to a
+specific file, you will need to set an id to the corresponding description and
+put the same id with `IntendedFor`.
 
-Optional field to add an `IntendedFor` entry in the sidecar of a fieldmap. Just
-put the index or a list of indices of the description(s) that's intended for.
+Fo example, **`task_rest`** means it is intended for `task-rest_bold` and
+**`id_task_learning`** is intended for `task-learning_bold`.
 
-Python index begins at `0` so in the example, **`1`** means it is intended for
-`task-rest_bold` and **`2`** is intended for `task-learning` which will be
-renamed to only `learning` because of the
-`"sidecarChanges": { "TaskName": "learning" }` field.
+You could also use this feature to feed sidecar such as `Source`` for example or
+anything that suits your needs.
 
 ## Multiple config files
 

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

@@ -18,4 +18,4 @@ title: How-to guides
 
 ## Development and Community
 
-- [Contribute to dcm2bids](/CONTRIBUTING.md)
+- [Contribute to dcm2bids](./contributing.md)