From cd163b32bea4a05793525e5ece8e5c556df797e4 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 09:17:21 -0400 Subject: [PATCH 01/19] add --do_not_reorder_entities doc --- docs/how-to/create-config-file.md | 11 ++++++++--- docs/how-to/use-advanced-commands.md | 3 +++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/how-to/create-config-file.md b/docs/how-to/create-config-file.md index 1681eb71..65993736 100644 --- a/docs/how-to/create-config-file.md +++ b/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. + ## sidecar_changes, id and IntendedFor Optional field to change or add information in a sidecar. diff --git a/docs/how-to/use-advanced-commands.md b/docs/how-to/use-advanced-commands.md index 5684a3da..397a7c22 100644 --- a/docs/how-to/use-advanced-commands.md +++ b/docs/how-to/use-advanced-commands.md @@ -290,6 +290,9 @@ like this. :radioactive: You can find more detailed information by looking at the file [`dcm2bids/utils/utils.py`](../dcm2bids/utils/utils/) and more specifically *`auto_extractors`* and *`auto_entities`* variables. +!!! danger "You cannot use `--auto_extract_entities` in conjunction with `--do_not_reorder_entities`" + Refer to the [Manuel ordering](../create-config-file/#custom_entities) section for more information. + ### `--bids_validate` By default, dcm2bids will not validate your final BIDS structure. If needed, you From 3a3bf7f76bdc639dc19c2166eab8b6e4b60ac035 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 09:44:07 -0400 Subject: [PATCH 02/19] add bids_uri doc --- docs/how-to/use-advanced-commands.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/how-to/use-advanced-commands.md b/docs/how-to/use-advanced-commands.md index 397a7c22..d6e09fab 100644 --- a/docs/how-to/use-advanced-commands.md +++ b/docs/how-to/use-advanced-commands.md @@ -58,7 +58,7 @@ field. By using the same keys in custom_entities and if found, it will add this new entities directly into the final filename. custom_entities can be a list that combined extractor keys and regular entities. If key is `task` it will -automatically add the field "TaskName" inside the sidecase file. +automatically add the field "TaskName" inside the sidecar file. ### `search_method` @@ -72,11 +72,11 @@ to match criteria. default: `"dup_method": "run"` -run is the default behavior and will add '\_run-' to the customEntities of the +run is the default behavior and will add `_run-` to the custom_entities of the acquisition if it finds duplicate destination roots. dup will keep the last duplicate description and put `_dup-`to the -customEntities of the other acquisitions. This behavior is a +custom_entities of the other acquisitions. This behavior is a [heudiconv](https://heudiconv.readthedocs.io/en/latest/changes.html) inspired feature. @@ -87,6 +87,13 @@ default: `"case_sensitive": "true"` If false, comparisons between strings/lists will be not case sensitive. It's only disabled when used with `"search_method": "fnmatch"`. +### `bids_uri` + +default: `"bids_uri": "URI"` +option: `"bids_uri": "relative"` + +Using `"bids_uri": "relative"` triggers the old behavior of dcm2bids (v2.1.9) that provides the path relative to within the subject directory without the BIDS URI (e.g., `bids::sub-01/`). This option has been brought back for compatibility reasons, especially for [fMRIprep users (pre v24.0.0)](https://fmriprep.org/en/latest/changes.html#june-17-2024). + ### `post_op` default: `"post_op": []` From e9da2c551d59a01409f77479074d7ec1fc209817 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 10:43:46 -0400 Subject: [PATCH 03/19] fix gha + order main commands --- .github/workflows/publish_doc.yaml | 3 +- docs/how-to/use-main-commands.md | 49 ++++++++++++++++-------------- 2 files changed, 29 insertions(+), 23 deletions(-) diff --git a/.github/workflows/publish_doc.yaml b/.github/workflows/publish_doc.yaml index 3a4676d5..036127e4 100644 --- a/.github/workflows/publish_doc.yaml +++ b/.github/workflows/publish_doc.yaml @@ -6,6 +6,7 @@ on: push: branches: - master + - dev tags: - '[0-9]+.[0-9]+.[0-9]+' release: @@ -76,7 +77,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" diff --git a/docs/how-to/use-main-commands.md b/docs/how-to/use-main-commands.md index 75570e8b..dbef4b6b 100644 --- a/docs/how-to/use-main-commands.md +++ b/docs/how-to/use-main-commands.md @@ -1,9 +1,14 @@ # How to use main commands -## Command Line Interface (CLI) +## Command Line Interface (CLI) usage -How to launch dcm2bids when you have build your configuration file ? First `cd` -in your BIDS directory. +See `dcm2bids -h` or `dcm2bids --help` to show the complete list of options and arguments. + +```bash +--8<-- "docs_helper/help.txt" +``` + +### Main command: `dcm2bids` ```bash dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -c CONFIG_FILE @@ -15,11 +20,6 @@ If your participant have a session ID: dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -s SESSION_ID -c CONFIG_FILE ``` -dcm2bids creates log files inside `tmp_dcm2bids/log` - -See `dcm2bids -h` or `dcm2bids --help` to show the help message that contains -more information. - !!! important If your directory or file names have space in them, we recommend that you @@ -29,14 +29,12 @@ more information. `dcm2bids -d "DICOM DIR" -p PARTICIPANT_ID -c "path/with spaces to/CONFIG FILE.json"` - - ## Output dcm2bids creates a `sub-` directory in the output directory (by default the folder where the script is launched). -Sidecars with one matching description will be convert to BIDS. If a file +Sidecars with one matching description will be converted to BIDS. If a file already exists, dcm2bids won't overwrite it. You should use the `--clobber` option to overwrite files. @@ -47,28 +45,35 @@ Sidecars with no or more than one matching descriptions are kept in `tmp_dcm2bids` directory. Users can review these mismatches to change the configuration file accordingly. +dcm2bids creates log files inside `tmp_dcm2bids/log` directory. + ## Tools -- Helper +### Scaffold + +the `dcm2bids_scaffold` command creates basic BIDS files and directories based on the [bids-starter-kit](https://github.com/bids-standard/bids-starter-kit). The output directory is set to the location where the script is launched by default. ```bash -dcm2bids_helper -d DICOM_DIR [-o OUTPUT_DIR] +dcm2bids_scaffold [-o OUTPUT_DIR] ``` -To build the configuration file, you need to have a example of the sidecars. You -can use `dcm2bids_helper` with the DICOMs of one participant. It will launch -dcm2niix and save the result inside the `tmp_dcm2bids/helper` of the output -directory. +```bash +--8<-- "docs_helper/help_scaffold.txt" +``` + +### Helper -- Scaffold +To build the configuration file, you need to have examples of sidecar files. You +can use `dcm2bids_helper` with the DICOMs of one participant. It will launch +dcm2niix and save the result inside the `tmp_dcm2bids/helper` directory by default. ```bash -dcm2bids_scaffold [-o OUTPUT_DIR] +dcm2bids_helper -d DICOM_DIR [-o OUTPUT_DIR] ``` -Create basic BIDS files and directories in the output directory (by default -folder where the script is launched). - +```bash +--8<-- "docs_helper/helper.txt" +``` [json-editor]: http://jsoneditoronline.org/ [^1]: From e723e1bb144c983702f407e3f8f6205e28c4e570 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 10:54:36 -0400 Subject: [PATCH 04/19] add readme me doc --- docs_helper/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs_helper/README.md diff --git a/docs_helper/README.md b/docs_helper/README.md new file mode 100644 index 00000000..2e2145d8 --- /dev/null +++ b/docs_helper/README.md @@ -0,0 +1,12 @@ +# How to build the doc locally + +The GHA workflow is set to build the documentation and has more steps than +the usual `mkdocs serve`. So if you want to see the documentation locally, +you can use the following steps: + +1. Create a virtual environment and install the dependencies in `requirements-docs.txt` with python 3.11. +2. Install dcm2bids within the virtual environment: `pip install -e .`. +3. Run `dcm2bids -h > docs_helper/help.txt && dcm2bids_helper -h > docs_helper/helper.txt && dcm2bids_scaffold -h > docs_helper/help_scaffold.txt` +4. Run `mkdocs serve` to see the documentation locally. + +Note that this will only run the latest local version of the documentation. `mike` takes care of the versioning through the GHA workflow. \ No newline at end of file From eeb7d6101ad708f8ce17476bb9f2516c5fe49c4e Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 11:18:53 -0400 Subject: [PATCH 05/19] add do_not_reorder to advance comm --- docs/how-to/use-advanced-commands.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/how-to/use-advanced-commands.md b/docs/how-to/use-advanced-commands.md index d6e09fab..5fccff5d 100644 --- a/docs/how-to/use-advanced-commands.md +++ b/docs/how-to/use-advanced-commands.md @@ -300,6 +300,10 @@ more specifically *`auto_extractors`* and *`auto_entities`* variables. !!! danger "You cannot use `--auto_extract_entities` in conjunction with `--do_not_reorder_entities`" Refer to the [Manuel ordering](../create-config-file/#custom_entities) section for more information. +### `--do_not_reorder_entities` + +This option will keep the order of the entities as they are entered in the config file by the user in the `custom_entities` field. However, please note that this flag cannot be used in conjunction with the `--auto_extract_entities` flag. + ### `--bids_validate` By default, dcm2bids will not validate your final BIDS structure. If needed, you From 9cf58f922ea7820719184fc1770a96b1b3ddac48 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 11:39:53 -0400 Subject: [PATCH 06/19] up py3.7 to 3.8 --- docs/get-started/install.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 8f7952e1..f3d05540 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -104,7 +104,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 +129,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 +163,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 +260,7 @@ name: dcm2bids channels: - conda-forge dependencies: - - python>=3.7 + - python>=3.8 - dcm2niix - dcm2bids ``` @@ -277,7 +277,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. @@ -384,7 +384,7 @@ containers: channels: - conda-forge dependencies: - - python>=3.7 + - python>=3.8 - dcm2niix - dcm2bids From 41fdaab9f9990ea79181575d49e16052745e6243 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 12:21:55 -0400 Subject: [PATCH 07/19] long due update for changelog --- CHANGELOG.md | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e3acfb1c..91ff3ae3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,205 @@ # CHANGELOG +## [3.1.1](https://github.com/UNFmontreal/Dcm2Bids/releases/tag/3.1.1) - 2023-10-12 + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.1.1) + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.1.1) + +Here is the newest release of dcm2bids ! πŸŽ‰ πŸ₯³ + +No new feature but two useful fixes ! +Hope you like this new feature less buggy β›” πŸ› + +Arnaud and Sam + +### What's Changed + +- Bump gitpython from 3.1.35 to 3.1.37 by [@dependabot](https://github.com/dependabot) in [#277](https://github.com/UNFmontreal/Dcm2Bids/pull/277) +- [BF] Auto extractors and merge regex expressions by [@arnaudbore](https://github.com/arnaudbore) in [#275](https://github.com/UNFmontreal/Dcm2Bids/pull/275) +- [ENH] fix binary by [@arnaudbore](https://github.com/arnaudbore) in [#278](https://github.com/UNFmontreal/Dcm2Bids/pull/278) + +**Full Changelog**: [3.1.0...3.1.1](https://github.com/UNFmontreal/Dcm2Bids/compare/3.1.0...3.1.1) + +## [3.1.0](https://github.com/UNFmontreal/Dcm2Bids/releases/tag/3.1.0) - 2023-09-13 + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.1.0) + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.1.0) + +We are excited to announce the newest release of dcm2bids ! πŸŽ‰ πŸ₯³ + +This update introduces some new features, improvements, and bug fixes to enhance your DICOM to BIDS conversion experience. +Everything embedded into this version comes from the community ❀️. Here are few examples. + +- During OHBM we've been asked to support archives as a dicom input, it's part of Dcm2bids 3.1.0. Check `dcm2bids --help` output. [link](https://unfmontreal.github.io/Dcm2Bids/3.1.0/tutorial/first-steps/#running-dcm2bids) +- While helping people on Neurostars, [@smeisler](https://github.com/smeisler) indicates that he needed to run pydeface after dcm2bids conversion since he needed both versions before and after defacing, it's now part of Dcm2bids 3.1.0. Check custom_entities in post-op section. [link](https://unfmontreal.github.io/Dcm2Bids/3.1.0/how-to/use-advanced-commands/#post_op) +- If you want to speed up dcm2bids conversion [@SamGuay](https://github.com/SamGuay) wrote a really nice [tutorial](https://unfmontreal.github.io/Dcm2Bids/3.1.0/tutorial/parallel/) to convert your data faster than ever. + +Your questions and concerns remain our top priority and continue to shape the future of Dcm2bids! + +Thank you +Arnaud and Sam + +We would like to thank [@smeisler](https://github.com/smeisler), [@Remi-Gau](https://github.com/Remi-Gau), [@raniaezzo](https://github.com/raniaezzo), [@arokem](https://github.com/arokem) and the users from [neurostars](https://neurostars.org/tag/dcm2bids) for their feedbacks. + +### What's Changed + +- [MAINT] validate citation.cff by [@Remi-Gau](https://github.com/Remi-Gau) in [#257](https://github.com/UNFmontreal/Dcm2Bids/pull/257) +- Bump gitpython from 3.1.32 to 3.1.34 by [@dependabot](https://github.com/dependabot) in [#259](https://github.com/UNFmontreal/Dcm2Bids/pull/259) +- Bump gitpython from 3.1.34 to 3.1.35 by [@dependabot](https://github.com/dependabot) in [#261](https://github.com/UNFmontreal/Dcm2Bids/pull/261) +- Fix typos in scaffold files by [@SamGuay](https://github.com/SamGuay) in [#263](https://github.com/UNFmontreal/Dcm2Bids/pull/263) +- [ENH] Add possibility to input dicom tar or zip archives by [@arnaudbore](https://github.com/arnaudbore) in [#262](https://github.com/UNFmontreal/Dcm2Bids/pull/262) +- Fix post op - pydeface by [@arnaudbore](https://github.com/arnaudbore) in [#260](https://github.com/UNFmontreal/Dcm2Bids/pull/260) +- Fix release tags in GHA by [@SamGuay](https://github.com/SamGuay) in [#266](https://github.com/UNFmontreal/Dcm2Bids/pull/266) +- Release 3.0.3 by [@arnaudbore](https://github.com/arnaudbore) in [#265](https://github.com/UNFmontreal/Dcm2Bids/pull/265) +- [ENH] - Automate help message in doc by [@SamGuay](https://github.com/SamGuay) in [#267](https://github.com/UNFmontreal/Dcm2Bids/pull/267) +- [DOC] - Tutorial on parallel x dcm2bids by [@SamGuay](https://github.com/SamGuay) in [#268](https://github.com/UNFmontreal/Dcm2Bids/pull/268) + +**Full Changelog**: [3.0.2...3.1.0](https://github.com/UNFmontreal/Dcm2Bids/compare/3.0.2...3.1.0) + +## [3.0.2](https://github.com/UNFmontreal/Dcm2Bids/releases/tag/3.0.2) - 2023-31-23 + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.2) + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.2) + +First of all thank you to everybody who came see our poster during OHBM 2023 in Montreal ! + +We listened to you and we added an option to reorganize your NIFTIs into a BIDS structure. Check this [link](https://unfmontreal.github.io/Dcm2Bids/3.0.1/how-to/use-advanced-commands/#-skip_dcm2niix). +We also extended the possibilities provided by the item sidecar_changes. + +Congrats πŸ₯³ + +### What's Changed + +- codespell: add config and action to codespell the code to avoid known typos by [@yarikoptic](https://github.com/yarikoptic) in [#245](https://github.com/UNFmontreal/Dcm2Bids/pull/245) +- Bump certifi from 2023.5.7 to 2023.7.22 by [@dependabot](https://github.com/dependabot) in [#247](https://github.com/UNFmontreal/Dcm2Bids/pull/247) +- Bring all 3 Arnauds into 1 by [@yarikoptic](https://github.com/yarikoptic) in [#246](https://github.com/UNFmontreal/Dcm2Bids/pull/246) +- Add option to skip_dcm2niix and reorganize NIFTI and JSON files by [@arnaudbore](https://github.com/arnaudbore) in [#248](https://github.com/UNFmontreal/Dcm2Bids/pull/248) +- Allowing Numericals in JSON custom fields by [@smeisler](https://github.com/smeisler) in [#250](https://github.com/UNFmontreal/Dcm2Bids/pull/250) +- Bump gitpython from 3.1.31 to 3.1.32 by [@dependabot](https://github.com/dependabot) in [#251](https://github.com/UNFmontreal/Dcm2Bids/pull/251) + +### New Contributors + +- [@yarikoptic](https://github.com/yarikoptic) made their first contribution in [#245](https://github.com/UNFmontreal/Dcm2Bids/pull/245) +- [@dependabot](https://github.com/dependabot) made their first contribution in [#247](https://github.com/UNFmontreal/Dcm2Bids/pull/247) + +**Full Changelog**: [3.0.1...3.0.2](https://github.com/UNFmontreal/Dcm2Bids/compare/3.0.1...3.0.2) + +## [3.0.1](https://github.com/UNFmontreal/Dcm2Bids/releases/tag/3.0.1) - 2023-07-23 + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.1) + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.1) + +We could not be more proud of the 3.0.1 dcm2bids release 😊 . We put everything we've learned from our past experiences and listen to all our users' ideas into this version. + +Advanced searching criterias such as extractors combined with custom entities, the ability to compare floats or the auto_extract_entities option directly accessible from dcm2bids command will make the conversion to BIDS smoother than ever and significantly reduce the complexity and the length of your configuration file especially for multi-site acquisitions. + +We highly encourage you to dive into the [documentation](https://unfmontreal.github.io/Dcm2Bids/3.0.1) since we added quite a lot of new features. + +Please don't hesitate to give us your feedback using this [#240](https://github.com/UNFmontreal/Dcm2Bids/discussions/240). + +Thank you again for all our users who contributed in some ways to this release. Thank you [@SamGuay](https://github.com/SamGuay) for the long discussions and late debug sessions. πŸŽ‰ + +Arnaud + +### What's Changed + +- [DOC] fix typo and add detail about entity reordering by [@Remi-Gau](https://github.com/Remi-Gau) in [#183](https://github.com/UNFmontreal/Dcm2Bids/pull/183) +- update version to match release by [@SamGuay](https://github.com/SamGuay) in [#185](https://github.com/UNFmontreal/Dcm2Bids/pull/185) +- [ENH] Refactorisation - Major API upgrade by [@arnaudbore](https://github.com/arnaudbore) in [#200](https://github.com/UNFmontreal/Dcm2Bids/pull/200) +- Get README from bids toolkit by [@arnaudbore](https://github.com/arnaudbore) in [#201](https://github.com/UNFmontreal/Dcm2Bids/pull/201) +- Add bids-validator option by [@arnaudbore](https://github.com/arnaudbore) in [#206](https://github.com/UNFmontreal/Dcm2Bids/pull/206) +- Upgrade feature Intended for by [@arnaudbore](https://github.com/arnaudbore) in [#207](https://github.com/UNFmontreal/Dcm2Bids/pull/207) +- [ENH] Upgrade custom entities by [@arnaudbore](https://github.com/arnaudbore) in [#208](https://github.com/UNFmontreal/Dcm2Bids/pull/208) +- [FIX] Broken scaffold no more by [@SamGuay](https://github.com/SamGuay) in [#209](https://github.com/UNFmontreal/Dcm2Bids/pull/209) +- [FIX,ENH] - Improve dcm2bids_helper mod by [@SamGuay](https://github.com/SamGuay) in [#210](https://github.com/UNFmontreal/Dcm2Bids/pull/210) +- Generalization of sidecarchanges using ids by [@arnaudbore](https://github.com/arnaudbore) in [#213](https://github.com/UNFmontreal/Dcm2Bids/pull/213) +- [ENH] dataType -> datatype and modalityLabel -> suffix by [@arnaudbore](https://github.com/arnaudbore) in [#214](https://github.com/UNFmontreal/Dcm2Bids/pull/214) +- Fix log n version by [@SamGuay](https://github.com/SamGuay) in [#219](https://github.com/UNFmontreal/Dcm2Bids/pull/219) +- [BF] valid participant by [@arnaudbore](https://github.com/arnaudbore) in [#215](https://github.com/UNFmontreal/Dcm2Bids/pull/215) +- Allow a criteria item to be a dict with a key - any (or) or all (and) by [@arnaudbore](https://github.com/arnaudbore) in [#217](https://github.com/UNFmontreal/Dcm2Bids/pull/217) +- Add an option to use duplicates instead of runs as suggested in heudiconv project. by [@arnaudbore](https://github.com/arnaudbore) in [#218](https://github.com/UNFmontreal/Dcm2Bids/pull/218) +- [BF] Valid session by [@arnaudbore](https://github.com/arnaudbore) in [#222](https://github.com/UNFmontreal/Dcm2Bids/pull/222) +- add test helper by [@arnaudbore](https://github.com/arnaudbore) in [#220](https://github.com/UNFmontreal/Dcm2Bids/pull/220) +- [BF] dcm2bids_scaffold by [@arnaudbore](https://github.com/arnaudbore) in [#224](https://github.com/UNFmontreal/Dcm2Bids/pull/224) +- prevent doc deployment by pushing to master by [@SamGuay](https://github.com/SamGuay) in [#226](https://github.com/UNFmontreal/Dcm2Bids/pull/226) +- [ENH] Add major OS executables on new release by [@SamGuay](https://github.com/SamGuay) in [#221](https://github.com/UNFmontreal/Dcm2Bids/pull/221) +- [ENH] Generalization of defaceTpl to post_op by [@arnaudbore](https://github.com/arnaudbore) in [#225](https://github.com/UNFmontreal/Dcm2Bids/pull/225) +- [ENH] Rename all cap var by [@arnaudbore](https://github.com/arnaudbore) in [#227](https://github.com/UNFmontreal/Dcm2Bids/pull/227) +- Revert doc to 2.1.9 by [@arnaudbore](https://github.com/arnaudbore) in [#228](https://github.com/UNFmontreal/Dcm2Bids/pull/228) +- Automated version-control documentation for 2.1.9 and up by [@SamGuay](https://github.com/SamGuay) in [#231](https://github.com/UNFmontreal/Dcm2Bids/pull/231) +- Fix GHA for docs + layouts by [@SamGuay](https://github.com/SamGuay) in [#234](https://github.com/UNFmontreal/Dcm2Bids/pull/234) +- [ENH] Add float comparison by [@arnaudbore](https://github.com/arnaudbore) in [#229](https://github.com/UNFmontreal/Dcm2Bids/pull/229) +- [Quick Fix] Add specific message when no acquisition was found by [@arnaudbore](https://github.com/arnaudbore) in [#235](https://github.com/UNFmontreal/Dcm2Bids/pull/235) +- Fix typo src_file dst_file by [@arnaudbore](https://github.com/arnaudbore) in [#236](https://github.com/UNFmontreal/Dcm2Bids/pull/236) +- Improve doc for v3.0.0 by [@arnaudbore](https://github.com/arnaudbore) in [#223](https://github.com/UNFmontreal/Dcm2Bids/pull/223) +- [FIX] - update the alias for dev and latest by [@SamGuay](https://github.com/SamGuay) in [#237](https://github.com/UNFmontreal/Dcm2Bids/pull/237) +- Quick fix version by [@arnaudbore](https://github.com/arnaudbore) in [#238](https://github.com/UNFmontreal/Dcm2Bids/pull/238) +- Update docs by [@smeisler](https://github.com/smeisler) in [#239](https://github.com/UNFmontreal/Dcm2Bids/pull/239) +- [BF] fix sidecars suggested by Sam by [@arnaudbore](https://github.com/arnaudbore) in [#243](https://github.com/UNFmontreal/Dcm2Bids/pull/243) + +### New Contributors + +- [@Remi-Gau](https://github.com/Remi-Gau) made their first contribution in [#183](https://github.com/UNFmontreal/Dcm2Bids/pull/183) +- [@smeisler](https://github.com/smeisler) made their first contribution in [#239](https://github.com/UNFmontreal/Dcm2Bids/pull/239) + +**Full Changelog**: [2.1.9...3.0.1](https://github.com/UNFmontreal/Dcm2Bids/compare/2.1.9...3.0.1) + +## [3.0.0rc1](https://github.com/UNFmontreal/Dcm2Bids/releases/tag/3.0.0rc1) - 2023-07-17 + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.0rc1) + +[](https://github.com/UNFmontreal/Dcm2Bids/releases/edit/3.0.0rc1) + +Ok let's be clear after working very hard on this we are definitively biased so we decided to ask ChatGPT to write for us a short fun description for our brand new version. + +Introducing the latest version of dcm2bids: the superhero of medical imaging data conversion! With simplified configuration, enhanced DICOM handling, comprehensive data validation, advanced options, and amazing new features, dcm2bids will transform your data into BIDS format like magic. Join the fun and unleash your scientific superpowers today! + +Please check the documentation πŸŽ‰ + +⚠️This is a release candidate. + +### What's Changed + +- [DOC] fix typo and add detail about entity reordering by [@Remi-Gau](https://github.com/Remi-Gau) in [#183](https://github.com/UNFmontreal/Dcm2Bids/pull/183) +- update version to match release by [@SamGuay](https://github.com/SamGuay) in [#185](https://github.com/UNFmontreal/Dcm2Bids/pull/185) +- [ENH] Refactorisation - Major API upgrade by [@arnaudbore](https://github.com/arnaudbore) in [#200](https://github.com/UNFmontreal/Dcm2Bids/pull/200) +- Get README from bids toolkit by [@arnaudbore](https://github.com/arnaudbore) in [#201](https://github.com/UNFmontreal/Dcm2Bids/pull/201) +- Add bids-validator option by [@arnaudbore](https://github.com/arnaudbore) in [#206](https://github.com/UNFmontreal/Dcm2Bids/pull/206) +- Upgrade feature Intended for by [@arnaudbore](https://github.com/arnaudbore) in [#207](https://github.com/UNFmontreal/Dcm2Bids/pull/207) +- [ENH] Upgrade custom entities by [@arnaudbore](https://github.com/arnaudbore) in [#208](https://github.com/UNFmontreal/Dcm2Bids/pull/208) +- [FIX] Broken scaffold no more by [@SamGuay](https://github.com/SamGuay) in [#209](https://github.com/UNFmontreal/Dcm2Bids/pull/209) +- [FIX,ENH] - Improve dcm2bids_helper mod by [@SamGuay](https://github.com/SamGuay) in [#210](https://github.com/UNFmontreal/Dcm2Bids/pull/210) +- Generalization of sidecarchanges using ids by [@arnaudbore](https://github.com/arnaudbore) in [#213](https://github.com/UNFmontreal/Dcm2Bids/pull/213) +- [ENH] dataType -> datatype and modalityLabel -> suffix by [@arnaudbore](https://github.com/arnaudbore) in [#214](https://github.com/UNFmontreal/Dcm2Bids/pull/214) +- Fix log n version by [@SamGuay](https://github.com/SamGuay) in [#219](https://github.com/UNFmontreal/Dcm2Bids/pull/219) +- [BF] valid participant by [@arnaudbore](https://github.com/arnaudbore) in [#215](https://github.com/UNFmontreal/Dcm2Bids/pull/215) +- Allow a criteria item to be a dict with a key - any (or) or all (and) by [@arnaudbore](https://github.com/arnaudbore) in [#217](https://github.com/UNFmontreal/Dcm2Bids/pull/217) +- Add an option to use duplicates instead of runs as suggested in heudiconv project. by [@arnaudbore](https://github.com/arnaudbore) in [#218](https://github.com/UNFmontreal/Dcm2Bids/pull/218) +- [BF] Valid session by [@arnaudbore](https://github.com/arnaudbore) in [#222](https://github.com/UNFmontreal/Dcm2Bids/pull/222) +- add test helper by [@arnaudbore](https://github.com/arnaudbore) in [#220](https://github.com/UNFmontreal/Dcm2Bids/pull/220) +- [BF] dcm2bids_scaffold by [@arnaudbore](https://github.com/arnaudbore) in [#224](https://github.com/UNFmontreal/Dcm2Bids/pull/224) +- prevent doc deployment by pushing to master by [@SamGuay](https://github.com/SamGuay) in [#226](https://github.com/UNFmontreal/Dcm2Bids/pull/226) +- [ENH] Add major OS executables on new release by [@SamGuay](https://github.com/SamGuay) in [#221](https://github.com/UNFmontreal/Dcm2Bids/pull/221) +- [ENH] Generalization of defaceTpl to post_op by [@arnaudbore](https://github.com/arnaudbore) in [#225](https://github.com/UNFmontreal/Dcm2Bids/pull/225) +- [ENH] Rename all cap var by [@arnaudbore](https://github.com/arnaudbore) in [#227](https://github.com/UNFmontreal/Dcm2Bids/pull/227) +- Revert doc to 2.1.9 by [@arnaudbore](https://github.com/arnaudbore) in [#228](https://github.com/UNFmontreal/Dcm2Bids/pull/228) +- Automated version-control documentation for 2.1.9 and up by [@SamGuay](https://github.com/SamGuay) in [#231](https://github.com/UNFmontreal/Dcm2Bids/pull/231) +- Fix GHA for docs + layouts by [@SamGuay](https://github.com/SamGuay) in [#234](https://github.com/UNFmontreal/Dcm2Bids/pull/234) +- [ENH] Add float comparison by [@arnaudbore](https://github.com/arnaudbore) in [#229](https://github.com/UNFmontreal/Dcm2Bids/pull/229) +- [Quick Fix] Add specific message when no acquisition was found by [@arnaudbore](https://github.com/arnaudbore) in [#235](https://github.com/UNFmontreal/Dcm2Bids/pull/235) +- Fix typo src_file dst_file by [@arnaudbore](https://github.com/arnaudbore) in [#236](https://github.com/UNFmontreal/Dcm2Bids/pull/236) +- Improve doc for v3.0.0 by [@arnaudbore](https://github.com/arnaudbore) in [#223](https://github.com/UNFmontreal/Dcm2Bids/pull/223) + +### New Contributors + +- [@Remi-Gau](https://github.com/Remi-Gau) made their first contribution in [#183](https://github.com/UNFmontreal/Dcm2Bids/pull/183) + +**Full Changelog**: [2.1.8...3.0.0rc1](https://github.com/UNFmontreal/Dcm2Bids/compare/2.1.8...3.0.0rc1) + ## **2.1.9 - 2022-06-17** Some issues with pypi. Sorry for this. From 027d5fb33e119e33db7dacd001ec74a540cd9ef1 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 17:45:02 -0400 Subject: [PATCH 08/19] add container doc --- CHANGELOG.md | 2 +- README.md | 4 +- containers/Dockerfile | 26 -------- containers/singularity.def | 2 - docs/get-started/install.md | 25 ++++---- docs/how-to/container.md | 115 ++++++++++++++++++++++++++++++++++++ docs/how-to/index.md | 2 + mkdocs.yml | 4 +- 8 files changed, 137 insertions(+), 43 deletions(-) delete mode 100644 containers/Dockerfile delete mode 100644 containers/singularity.def create mode 100644 docs/how-to/container.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 91ff3ae3..21ab9c13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -95,7 +95,7 @@ Congrats πŸ₯³ We could not be more proud of the 3.0.1 dcm2bids release 😊 . We put everything we've learned from our past experiences and listen to all our users' ideas into this version. -Advanced searching criterias such as extractors combined with custom entities, the ability to compare floats or the auto_extract_entities option directly accessible from dcm2bids command will make the conversion to BIDS smoother than ever and significantly reduce the complexity and the length of your configuration file especially for multi-site acquisitions. +Advanced searching criteria such as extractors combined with custom entities, the ability to compare floats or the auto_extract_entities option directly accessible from dcm2bids command will make the conversion to BIDS smoother than ever and significantly reduce the complexity and the length of your configuration file especially for multi-site acquisitions. We highly encourage you to dive into the [documentation](https://unfmontreal.github.io/Dcm2Bids/3.0.1) since we added quite a lot of new features. diff --git a/README.md b/README.md index d249d0bb..67359872 100644 --- a/README.md +++ b/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 diff --git a/containers/Dockerfile b/containers/Dockerfile deleted file mode 100644 index c23b365f..00000000 --- a/containers/Dockerfile +++ /dev/null @@ -1,26 +0,0 @@ -From ubuntu:latest -ENV DEBIAN_FRONTEND=noninteractive - -MAINTAINER Arnaud BorΓ© - -RUN apt-get update -RUN apt-get -y upgrade - -RUN apt-get -y install wget build-essential cmake git pigz \ - nodejs python3 python3-pip unzip - -RUN pip3 install dcm2bids - -# Install dcm2niix from github -ENV DCM2NIIX_VERSION="v1.0.20230411" - -WORKDIR /usr/local/src -RUN git clone https://github.com/rordenlab/dcm2niix.git -WORKDIR /usr/local/src/dcm2niix -RUN git checkout tags/${DCM2NIIX_VERSION} -b install -RUN mkdir build -WORKDIR /usr/local/src/dcm2niix/build -RUN cmake .. -RUN make install - -WORKDIR / diff --git a/containers/singularity.def b/containers/singularity.def deleted file mode 100644 index 101dde23..00000000 --- a/containers/singularity.def +++ /dev/null @@ -1,2 +0,0 @@ -BootStrap: docker -From: unfmontreal/dcm2bids:latest diff --git a/docs/get-started/install.md b/docs/get-started/install.md index f3d05540..b3da9988 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -9,6 +9,19 @@ 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" + + `docker pull unfmontreal/dcm2bids:latest` + +=== "Apptainer/Singularity" + + `singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest` + ## Installing binary executables From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux @@ -353,18 +366,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 diff --git a/docs/how-to/container.md b/docs/how-to/container.md new file mode 100644 index 00000000..d33550ac --- /dev/null +++ b/docs/how-to/container.md @@ -0,0 +1,115 @@ +# 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/r/unfmontreal/dcm2bids](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" + + ``` + docker pull unfmontreal/dcm2bids:latest + ``` + +=== "Apptainer/Singularity" + + ``` + apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:latest + ``` + +## 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:latest --help + ``` + +=== "Apptainer/Singularity" + + ``` + apptainer run dcm2bids.sif --help + ``` + +## Step 3: Run `dcm2bids_scaffold` + +To run `dcm2bids_scaffold`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). You need to bind the respective volumes. + +=== "Docker" + + ``` + docker run + ``` + +=== "Apptainer/Singularity" + + ``` + singularity exec \ + -B /path/to/output-dir:/output \ + dcm2bids.sif dcm2bids_scaffold -o /output/new_bids_dataset + ``` + + +## Step 4: Run `dcm2bids_helper` + +To run `dcm2bids_helper`, 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 /output` 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 `/input`. If it is the parent directory of multiple subjects, you can bind it to `/input` and specify the specific subject directory (e.g, `-d /input/subject-01`). + +=== "Docker" + + ``` + docker run + ``` + +=== "Apptainer/Singularity" + + ``` + singularity exec \ + -B /path/to/input-data:/input \ + -B /path/to/output-dir/new_bids_dataset:/output \ + dcm2bids.sif dcm2bids_helper -o /output -d /input + ``` + +## 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 and validate your BIDS data using the `--bids_validate` flag. + +=== "Docker" + + ``` + docker run --rm -v + ``` + +=== "Apptainer/Singularity" + + ``` + singularity run \ + -B /path/to/input-data:/input \ + -B /path/to/output-dir/new_bids_dataset:/output \ + dcm2bids.sif --auto_extract_entities --bids_validate \ + -o /output -d /input -c /output/code/config.json -p 001 + ``` diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 1c8e215a..77ca0ce6 100644 --- a/docs/how-to/index.md +++ b/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) diff --git a/mkdocs.yml b/mkdocs.yml index f41d4b26..cfe0631c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,10 +29,11 @@ nav: - Use main commands: how-to/use-main-commands.md - Create a config file: how-to/create-config-file.md - Use advanced commands: how-to/use-advanced-commands.md + - Use container images: how-to/container.md + - Upgrade dcm2bids: upgrade.md - Contribute to dcm2bids: how-to/contributing.md - Changelog: - changelog/index.md - - How to upgrade: upgrade.md - API Reference: dcm2bids - Code of conduct: code_of_conduct.md @@ -76,6 +77,7 @@ theme: - content.action.view - content.code.annotate - content.code.copy + # - content.tabs.link - content.tooltips - navigation.footer - navigation.indexes From 5f7aee6ec1920025d4433e0fb2eee8ad0636463d Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Wed, 24 Jul 2024 17:45:09 -0400 Subject: [PATCH 09/19] bump version --- dcm2bids/version.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dcm2bids/version.py b/dcm2bids/version.py index f9b3b65c..530c5ab3 100644 --- a/dcm2bids/version.py +++ b/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. From 89445ca6115db5cc43afe36a7b0b5b4dd02933c5 Mon Sep 17 00:00:00 2001 From: arnaudbore Date: Thu, 25 Jul 2024 13:38:51 -0400 Subject: [PATCH 10/19] update container with links --- docs/how-to/container.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index d33550ac..6c5af36e 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -49,12 +49,15 @@ The default command, or the point of entry, for the container is `dcm2bids`. So ## Step 3: Run `dcm2bids_scaffold` -To run `dcm2bids_scaffold`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). You need to bind the respective volumes. +To run `dcm2bids_scaffold`, `with 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 + docker run --rm -it \ + --entrypoint /venv/bin/dcm2bids_scaffold \ + -v /path/to/output-dir:/output \ + unfmontreal/dcm2bids:latest -o /output/new_bids_dataset ``` === "Apptainer/Singularity" @@ -68,7 +71,7 @@ To run `dcm2bids_scaffold`, you need to *execute* a command instead of *running* ## Step 4: Run `dcm2bids_helper` -To run `dcm2bids_helper`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). To bind the respective volumes, you have two options: +To run `dcm2bids_helper`, `with 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. @@ -78,7 +81,10 @@ If you bind the newly scaffolded directory on its own, you can simply use the `- === "Docker" ``` - docker run + docker run --rm -it --entrypoint /venv/bin/dcm2bids_helper \ + -v /path/to/input-data:/input \ + -v /path/to/output-dir/new_bids_dataset:/output \ + unfmontreal/dcm2bids:latest -o /output -d /input ``` === "Apptainer/Singularity" @@ -96,12 +102,16 @@ You can use `run` as in Step 2 or use `exec dcm2bids` to run `dcm2bids` with the 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 and validate your BIDS data using the `--bids_validate` flag. +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 -v + docker run --rm -it \ + -B /path/to/input-data:/input \ + -B /path/to/output-dir/new_bids_dataset:/output \ + unfmontreal/dcm2bids:latest --auto_extract_entities --bids_validate \ + -o /output -d /input -c /output/code/config.json -p 001 ``` === "Apptainer/Singularity" From d8f3482d4989aefefcc5f7e85de151efc681246c Mon Sep 17 00:00:00 2001 From: arnaudbore Date: Thu, 25 Jul 2024 14:03:43 -0400 Subject: [PATCH 11/19] fix typo --- docs/how-to/container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index 6c5af36e..dd4589ea 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -1,6 +1,6 @@ # 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/r/unfmontreal/dcm2bids](https://hub.docker.com/r/unfmontreal/dcm2bids). +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). From 8f6d1bf86128746df0354d2d965936e9a6656569 Mon Sep 17 00:00:00 2001 From: Arnaud Bore Date: Thu, 25 Jul 2024 14:42:42 -0400 Subject: [PATCH 12/19] Update docs/how-to/container.md Co-authored-by: Samuel Guay --- docs/how-to/container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index dd4589ea..1eaa29fe 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -71,7 +71,7 @@ To run `dcm2bids_scaffold`, `with singularity`, you need to *execute* a command ## Step 4: Run `dcm2bids_helper` -To run `dcm2bids_helper`, `with singularity`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). To bind the respective volumes, you have two options: +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. From d656c1726c88adab0f3b347a6aa7e780c5f52359 Mon Sep 17 00:00:00 2001 From: Arnaud Bore Date: Thu, 25 Jul 2024 14:42:48 -0400 Subject: [PATCH 13/19] Update docs/how-to/container.md Co-authored-by: Samuel Guay --- docs/how-to/container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index 1eaa29fe..39212642 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -49,7 +49,7 @@ The default command, or the point of entry, for the container is `dcm2bids`. So ## Step 3: Run `dcm2bids_scaffold` -To run `dcm2bids_scaffold`, `with singularity`, you need to *execute* a command instead of *running* the pre-specified command (`dcm2bids`). You need to bind the respective volumes. +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" From 27dd27eb2e86a20f145b651420b14e171f189cdf Mon Sep 17 00:00:00 2001 From: Arnaud Bore Date: Thu, 25 Jul 2024 19:54:19 -0400 Subject: [PATCH 14/19] Update docs/how-to/create-config-file.md Co-authored-by: Steven Meisler --- docs/how-to/create-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/create-config-file.md b/docs/how-to/create-config-file.md index 65993736..e89e5a8b 100644 --- a/docs/how-to/create-config-file.md +++ b/docs/how-to/create-config-file.md @@ -152,7 +152,7 @@ custom_entities could also be combined with extractors. See !!! 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. + 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 From 5e645fdf8ef9ff60e023a000084a537d6596ee6c Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Fri, 26 Jul 2024 08:37:41 -0400 Subject: [PATCH 15/19] Apply suggestions from code review Edited a bit to make sure dcm2bids_scaffold creates it in a newly created dir. Co-authored-by: Steven Meisler --- docs/how-to/container.md | 49 +++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index 39212642..e5c892ef 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -28,7 +28,7 @@ To start, you can either pull the dcm2bids image from the Docker Hub repository === "Apptainer/Singularity" ``` - apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:latest + apptainer pull dcm2bids_${VERSION}.sif docker://unfmontreal/dcm2bids:${VERSION} ``` ## Step 2: Test dcm2bids @@ -44,7 +44,7 @@ The default command, or the point of entry, for the container is `dcm2bids`. So === "Apptainer/Singularity" ``` - apptainer run dcm2bids.sif --help + apptainer run -e --containall dcm2bids.sif --help ``` ## Step 3: Run `dcm2bids_scaffold` @@ -56,16 +56,17 @@ To run `dcm2bids_scaffold` with Apptainer/Singularity, you need to *execute* a c ``` docker run --rm -it \ --entrypoint /venv/bin/dcm2bids_scaffold \ - -v /path/to/output-dir:/output \ - unfmontreal/dcm2bids:latest -o /output/new_bids_dataset + -v /path/to/bids:/bids \ + unfmontreal/dcm2bids:${VERSION} -o /bids/new_scaffold ``` === "Apptainer/Singularity" ``` - singularity exec \ - -B /path/to/output-dir:/output \ - dcm2bids.sif dcm2bids_scaffold -o /output/new_bids_dataset + apptainer exec \ + -e --containall \ + -B /path/to/bids:/bids \ + dcm2bids.sif dcm2bids_scaffold -o /bids/new_scaffold ``` @@ -76,24 +77,24 @@ To run `dcm2bids_helper` with Apptainer/Singularity, you need to *execute* a com 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 /output` 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 `/input`. If it is the parent directory of multiple subjects, you can bind it to `/input` and specify the specific subject directory (e.g, `-d /input/subject-01`). +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/input-data:/input \ - -v /path/to/output-dir/new_bids_dataset:/output \ - unfmontreal/dcm2bids:latest -o /output -d /input + -v /path/to/dicoms:/dicoms:ro \ + -v /path/to/bids/new_scaffold:/bids \ + unfmontreal/dcm2bids:${VERSION} -o /bids -d /dicoms ``` === "Apptainer/Singularity" ``` - singularity exec \ - -B /path/to/input-data:/input \ - -B /path/to/output-dir/new_bids_dataset:/output \ - dcm2bids.sif dcm2bids_helper -o /output -d /input + apptainer exec \ + -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` @@ -108,18 +109,20 @@ You can also [deface your data](use-advanced-commands.md#post_op) and [validate ``` docker run --rm -it \ - -B /path/to/input-data:/input \ - -B /path/to/output-dir/new_bids_dataset:/output \ - unfmontreal/dcm2bids:latest --auto_extract_entities --bids_validate \ - -o /output -d /input -c /output/code/config.json -p 001 + -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" ``` - singularity run \ - -B /path/to/input-data:/input \ - -B /path/to/output-dir/new_bids_dataset:/output \ + apptainer run \ + -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 /output -d /input -c /output/code/config.json -p 001 + -o /bids -d /dicoms -c /config.json -p 001 ``` From 0a30af6291d65b82c934a58b08dcf89a6a687741 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Fri, 26 Jul 2024 08:39:36 -0400 Subject: [PATCH 16/19] Update docs/get-started/install.md Co-authored-by: Steven Meisler --- docs/get-started/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/install.md b/docs/get-started/install.md index b3da9988..07f944b9 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -20,7 +20,7 @@ You can install it using [Docker][docker] or [Apptainer/Singularity][apptainer]. === "Apptainer/Singularity" - `singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest` + `apptainer pull dcm2bids_${VERSION}.sif docker://unfmontreal/dcm2bids:${VERSION}` ## Installing binary executables From 17e82051f36904024d28647d5eaeba4f4597f189 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Fri, 26 Jul 2024 08:42:20 -0400 Subject: [PATCH 17/19] Apply ${VERSION} everywhere for consistency --- docs/get-started/install.md | 2 +- docs/how-to/container.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 07f944b9..22102614 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -16,7 +16,7 @@ You can install it using [Docker][docker] or [Apptainer/Singularity][apptainer]. === "Docker" - `docker pull unfmontreal/dcm2bids:latest` + `docker pull unfmontreal/dcm2bids:${VERSION}` === "Apptainer/Singularity" diff --git a/docs/how-to/container.md b/docs/how-to/container.md index e5c892ef..fd490d5b 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -22,7 +22,7 @@ To start, you can either pull the dcm2bids image from the Docker Hub repository === "Docker" ``` - docker pull unfmontreal/dcm2bids:latest + docker pull unfmontreal/dcm2bids:${VERSION} ``` === "Apptainer/Singularity" From 74f749be1d92151c9118b69f35ca5f46a5c80c64 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Fri, 26 Jul 2024 08:55:16 -0400 Subject: [PATCH 18/19] add missing -e --containall --- docs/how-to/container.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/how-to/container.md b/docs/how-to/container.md index fd490d5b..96f73c0f 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -92,6 +92,7 @@ If you bind the newly scaffolded directory on its own, you can simply use the `- ``` 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 @@ -120,6 +121,7 @@ You can also [deface your data](use-advanced-commands.md#post_op) and [validate ``` 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 \ From e4b7123cac573178f65f035f39060a273c527757 Mon Sep 17 00:00:00 2001 From: Samuel Guay Date: Fri, 26 Jul 2024 09:22:51 -0400 Subject: [PATCH 19/19] add export version to containers --- .github/workflows/publish_doc.yaml | 1 + .gitignore | 1 + docs/get-started/install.md | 10 ++++++++-- docs/how-to/container.md | 6 +++++- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish_doc.yaml b/.github/workflows/publish_doc.yaml index 036127e4..ba4819cb 100644 --- a/.github/workflows/publish_doc.yaml +++ b/.github/workflows/publish_doc.yaml @@ -51,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: | diff --git a/.gitignore b/.gitignore index ee1d0b5f..104f9265 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,4 @@ tests/data/* docs_helper/help.txt docs_helper/help_scaffold.txt docs_helper/helper.txt +docs_helper/version.txt \ No newline at end of file diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 22102614..cd9d7148 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -16,11 +16,17 @@ You can install it using [Docker][docker] or [Apptainer/Singularity][apptainer]. === "Docker" - `docker pull unfmontreal/dcm2bids:${VERSION}` + ``` + --8<-- "docs_helper/version.txt" + docker pull unfmontreal/dcm2bids:${VERSION} + ``` === "Apptainer/Singularity" - `apptainer pull dcm2bids_${VERSION}.sif docker://unfmontreal/dcm2bids:${VERSION}` + ``` + --8<-- "docs_helper/version.txt" + apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:${VERSION} + ``` ## Installing binary executables diff --git a/docs/how-to/container.md b/docs/how-to/container.md index 96f73c0f..9a693577 100644 --- a/docs/how-to/container.md +++ b/docs/how-to/container.md @@ -19,15 +19,19 @@ Before you begin, make sure you have at least one of the following installed: 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} ``` @@ -38,7 +42,7 @@ The default command, or the point of entry, for the container is `dcm2bids`. So === "Docker" ``` - docker run --rm -it unfmontreal/dcm2bids:latest --help + docker run --rm -it unfmontreal/dcm2bids:${VERSION} --help ``` === "Apptainer/Singularity"