diff --git a/.github/workflows/publish_doc.yaml b/.github/workflows/publish_doc.yaml index ea8aa40c..a3a60886 100644 --- a/.github/workflows/publish_doc.yaml +++ b/.github/workflows/publish_doc.yaml @@ -1,30 +1,46 @@ name: Publish documentation -on: [push] +on: + push: + branches: + - master + pull_request: jobs: build: + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v3 + with: + python-version: "3.10" + - name: Upgrade pip + run: | + # install pip=>20.1 to use "pip cache dir" + python3 -m pip install --upgrade pip - runs-on: ubuntu-latest - strategy: - matrix: - python-version: [3.8] + - name: Get pip cache dir + id: pip-cache + run: echo "::set-output name=dir::$(pip cache dir)" - steps: - - uses: actions/checkout@v2 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 - with: - python-version: ${{ matrix.python-version }} - - name: Install dependencies - run: | - python -m pip install --upgrade pip - if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi - - name: run portray - run: | - portray as_html - - name: Deploy to gh-pages branch - uses: peaceiris/actions-gh-pages@v3.7.3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./site \ No newline at end of file + - name: Cache dependencies + uses: actions/cache@v2 + with: + path: ${{ steps.pip-cache.outputs.dir }} + key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-dev.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Install dependencies + run: python3 -m pip install -r ./requirements-dev.txt + + - name: run portray + run: | + portray as_html + - name: Deploy to gh-pages branch + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.ref == 'refs/heads/master' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site diff --git a/art/dcm_qa_nih_repo.png b/art/dcm_qa_nih_repo.png deleted file mode 100644 index d03516ad..00000000 Binary files a/art/dcm_qa_nih_repo.png and /dev/null differ diff --git a/docs/1-usage.md b/docs/1-usage.md deleted file mode 100644 index c220b0ec..00000000 --- a/docs/1-usage.md +++ /dev/null @@ -1,84 +0,0 @@ -# Usage - -## Introduction - -dcm2bids converts one session at a time. A session is all the acquisitions between the entry and exit of the participant in the scanner. - -You need to build a configuration file of your study to let dcm2bids associates your acquisitions through BIDS sidecar. Every study is different and this step needs a little bit of work. The scanner parameters should not change too much for one study (several MRI sessions), so a few configuration files should work. - -BIDS sidecar[^1] files are `JSON` files with meta informations about the acquisition. `dcm2niix` (DICOM to NIfTI converter used by dcm2bids) creates automatically one BIDS sidecar for each NIfTI file. - -dcm2bids configuration file uses also the `JSON` format. One example is provided in the `example` folder on the github repository. - -It is recommended to use an editor with syntax highlighting to build a correct JSON file. Here is an [online][json-editor] one. - -## Command Line Interface (CLI) - -How to launch dcm2bids when you have build your configuration file ? First `cd` in your BIDS directory. - -```bash -dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -c CONFIG_FILE -``` - -If your participant have a session ID: - -```bash -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. - -## 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 already exists, dcm2bids won't overwrite it. You should use the `--clobber` option to overwrite files. - -If a description matches several sidecars, dcm2bids will add automatically the custom label `run-` to the filename. - -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. - -## Tools - -- Helper - -```bash -dcm2bids_helper -d DICOM_DIR [-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. - -- Scaffold - -```bash -dcm2bids_scaffold [-o OUTPUT_DIR] -``` - -Create basic BIDS files and directories in the output directory (by default folder where the script is launched). - -[json-editor]: http://jsoneditoronline.org/ - - -# Containers - -You can also use all the tools through docker or singularity images. - -=== "Docker" - ```console - docker pull unfmontreal/dcm2bids:latest - ``` - -=== "Singularity" - ```console - singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest - ``` - -[^1]: For each acquisition, `dcm2niix` creates an associated `.json` file, - containing information from the dicom header. These are known as - __sidecars__. These are the sidecars `dcm2bids` uses to filter the groups - of acquisitions. - - To define this filtering you will probably need to review these sidecars. - You can generate all the sidecars for an individual participant using [dcm2bids_helper](1-usage.md#tools). diff --git a/docs/2-tutorial.md b/docs/2-tutorial.md deleted file mode 100644 index 43ef1c90..00000000 --- a/docs/2-tutorial.md +++ /dev/null @@ -1,182 +0,0 @@ -# Tutorial - -## Setup - -Create a new folder for this tutorial. - -```bash -mkdir dcm2bids-tutorial -cd dcm2bids-tutorial -``` - -You can skip this part and go to the next [section](#scaffolding) if `dcm2niix` and `dcm2bids` are already installed. - -The tutorial suppose that [conda][conda] is installed and correctly setup on your computer. It is the easiest way to install dcm2bids and its dependencies on any OS. - -You should know that this is not the best way because conda does not always have the last version of dcm2niix. - -Create a new file `environment.yml` with your favorite text editor with this content: - -```yaml -name: dcm2bids -channels: - - conda-forge -dependencies: - - dcm2niix - - dcm2bids - - pip -``` - -Finaly, create a new conda environment to install dcm2bids: - -```bash -conda env create -f environment.yml -source activate dcm2bids -``` - -We should have access to `dcm2bids` now. Test it with `dcm2bids --help`. - -## Scaffolding - -We can now run the command `dcm2bids_scaffold`. This gives us several generics folders and files. We can have a look at these files and consult the [BIDS specification][bids-spec] for more information. - -One of the created folders is named `sourcedata`, this is the folder to put your DICOMs - -## Downloading test data - -For this tutorial, we will use DICOMs from [neurolabusc](https://github.com/neurolabusc) on github. - -Go to : [https://github.com/neurolabusc/dcm_qa_nih](https://github.com/neurolabusc/dcm_qa_nih) and click on the *Clone or download* button to download as ZIP. - -![dcm_qa_nih_repo](../art/dcm_qa_nih_repo.png) - -Move the zip file to the sourcedata folder and unzip it. Here is how to do it in the terminal but we could do it the way we want. - -```bash -mv ~/Downloads/dcm_qa_nih-master.zip sourcedata/ -cd sourcedata -unzip dcm_qa_nih-master.zip -cd .. -``` - -We should have now a `dcm_qa_nih-master` folder inside sourcedata. - -## DICOM to NIfTI conversion - -`dcm2bids_helper -d sourcedata/dcm_qa_nih-master/In/` - -This command will convert the DICOMs files to NIfTI files and save them inside `tmp_dcm2bids/helper/`. - -We should see a list of compressed NIfTI files (`nii.gz`) with their resective sidecar files (`.json`). For this tutorial, we will only be interested in three acquisitions : - -- `004_In_Axial_EPI-FMRI_(Interleaved_I_to_S)_20180918114023.nii.gz` -- `004_In_EPI_PE=PA_20180918121230.nii.gz` -- `003_In_EPI_PE=AP_20180918121230.nii.gz` - -The first will be our resting state fMRI, the second and third our fieldmap EPI. - -When you will do it with your DICOMs, you should do it with a typical session of one of your participants. - -## Building the configuration file - -Now we will create a configuration file called `dcm2bids_config.json` (this is just an example, it could be whatever we want) in the `code/` folder. Use any text editor to create the file with the contents: - -```json -{ - "descriptions": [] -} -``` - -For example, with our resting state fMRI we see in its sidecar that the field `"SeriesDescription"` is equal to `"Axial_EPI-FMRI_(Interleaved_I_to_S)"`. We can open `004_In_Axial_EPI-FMRI_(Interleaved_I_to_S)_20180918114023.json` to verify that. - -This value could be match with a pattern `"Axial_EPI-FMRI*"`. - -Unfortunately, this criteria is not enough and could match other files. See `006_In_Axial_EPI-FMRI_(Interleaved_S_to_I)_20180918114023.json`. - -In this case we could add another criteria to match the acquisition by the filename of the sidecar with the pattern `"*Interleaved_I_to_S*"`. - -With all this information we could then update our configuration file. - -```json hl_lines="9" -{ - "descriptions": [ - { - "dataType": "func", - "modalityLabel": "bold", - "customLabels": "task-rest", - "criteria": { - "SeriesDescription": "Axial_EPI-FMRI*", - "SidecarFilename": "*Interleaved_I_to_S*" - } - } - ] -} -``` - -For the two fieldmaps, we can see that with patterns of `"*EPI_PE=AP*"` or `"*EPI_PE=PA*"` on the filename is enough to match the correct acquisition. - -We could then update our configuration file. - -```json hl_lines="17 26" -{ - "descriptions": [ - { - "dataType": "func", - "modalityLabel": "bold", - "customLabels": "task-rest", - "criteria": { - "SeriesDescription": "Axial_EPI-FMRI*", - "SidecarFilename": "*Interleaved_I_to_S*" - } - }, - { - "dataType": "fmap", - "modalityLabel": "epi", - "customLabels": "dir-AP", - "criteria": { - "SidecarFilename": "*EPI_PE=AP*" - }, - "intendedFor": 0 - }, - { - "dataType": "fmap", - "modalityLabel": "epi", - "customLabels": "dir-PA", - "criteria": { - "SidecarFilename": "*EPI_PE=PA*" - }, - "intendedFor": 0 - } - ] -} -``` - -For fieldmap, we added an `"intendedFor"` field to show that these fieldmaps should be use with our fMRI acquisition. Have a look at the explanation of [intendedFor](/docs/3-configuration/#intendedfor) in the documentation or in the [BIDS specification][bids-fmap]. - -## Running dcm2bids - -We can now run dcm2bids: - -```bash -dcm2bids -d sourcedata/dcm_qa_nih-master/In/ -p ID01 -c code/dcm2bids_config.json -``` - -A bunch of information is print to the terminal and we can verify that the data are now in BIDS. - -```console -user@pc:data/$ ls sub-ID01/* -sub-ID01/fmap: -sub-ID01_dir-AP_epi.json sub-ID01_dir-AP_epi.nii.gz -sub-ID01_dir-PA_epi.json sub-ID01_dir-PA_epi.nii.gz - -sub-ID01/func: -sub-ID01_task-rest_bold.json sub-ID01_task-rest_bold.nii.gz -``` - -Files that were not grabbed stay in a temporary folder `tmp_dcm2bids/sub-{participant_id}`. In our case : `tmp_dcm2bids/sub-ID01`. - -Have a look at `dcm2bids --help` or the other pages of the documentation for more information. - -[bids-spec]: https://bids-specification.readthedocs.io/en/stable/ -[bids-fmap]: https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#fieldmap-data -[conda]: https://conda.io/en/latest/miniconda.html diff --git a/docs/3-configuration.md b/docs/3-configuration.md deleted file mode 100644 index ab4f97a3..00000000 --- a/docs/3-configuration.md +++ /dev/null @@ -1,102 +0,0 @@ -# Configuration file - -## Configuration file example - -```json -{ - "descriptions": [ - { - "dataType": "func", - "modalityLabel": "bold", - "customLabels": "task-rest", - "criteria": { - "SidecarFilename": "006*", - "ImageType": ["ORIG*", "PRIMARY", "M", "ND", "MOSAIC"] - } - }, - { - "dataType": "anat", - "modalityLabel": "T2w", - "criteria": { - "SeriesDescription": "*T2*", - "EchoTime": 0.1 - }, - "sidecarChanges": { - "ProtocolName": "T2" - } - }, - { - "dataType": "fmap", - "modalityLabel": "fmap", - "intendedFor": 0, - "criteria": { - "ProtocolName": "*field_mapping*" - } - } - ] -} -``` - -The `descriptions` field is a list of descriptions, each describing some acquisition. In this example, the configuration describes three acquisitions, a T2 weighted, resting state fMRI and a fieldmap. - -Each description tells dcm2bids how to group a set of acquisitions and how to label them. In this config file, Dcm2Bids is being told to collect files containing - -```json -{ - "SeriesDescription": "AXIAL_T2_SPACE", - "EchoTime": 0.1 -} -``` - -in their sidecars[^1] and label them as `anat`, `T2w` type images. - -## criteria - -dcm2bids will try to match the sidecars[^1] of dcm2niix to the descriptions of the configuration file. The values you enter inside the criteria dictionary are patterns that will be compared to the corresponding key of the sidecar. - -The pattern matching is shell-style. It's possible to use wildcard `*`, single character `?` etc ... Please have a look at the [GNU documentation][gnu-pattern] to know more. - -For example, in the second description, the pattern `*T2*` will be compared to the value of `SeriesDescription` of a sidecar. `AXIAL_T2_SPACE` will be a match, `AXIAL_T1` won't. - -`dcm2bids` has a `SidecarFilename` key, as in the first description, if you prefer to also match with the filename of the sidecar. - -You can enter several criteria. **All criteria must match** for a description to be linked to a sidecar. - -## dataType - -It is a mandatory field. Here is a definition from `bids v1.2.0` : - -> Data type - a functional group of different types of data. In BIDS we define six data types: func (task based and resting state functional MRI), dwi (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as field maps), anat (structural imaging such as T1, T2, etc.), meg (magnetoencephalography), beh (behavioral). - -## modalityLabel - -It is a mandatory field. It describes the modality of the acquisition like `T1w`, `T2w` or `dwi`, `bold`. - -## customLabels - -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`. - -To know more on how to set these fields, read the [BIDS 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 - -Optional field to change or add information in a sidecar. - -## 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. - -Python index begins at `0` so in the example, `0` means it is intended for `task-rest_bold`. - -[^1]: For each acquisition, `dcm2niix` creates an associated `.json` file, - containing information from the dicom header. These are known as - __sidecars__. These are the sidecars `dcm2bids` uses to filter the groups - of acquisitions. - - To define this filtering you will probably need to review these sidecars. - You can generate all the sidecars for an individual participant using [dcm2bids_helper](1-usage.md#tools). - -[bids-spec]: https://bids-specification.readthedocs.io/en/stable/ -[gnu-pattern]: https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 00000000..2d98b19e --- /dev/null +++ b/docs/assets/extra.css @@ -0,0 +1,55 @@ +:root { + --md-primary-fg-color: hsla(16, 100%, 42%, 1); + --md-primary-fg-color--light: hsla(16, 100%, 64%, 1); + --md-primary-fg-color--dark: #d63900; + --md-typeset-a-color: var(--md-accent-fg-color--transparent) + --md-accent-fg-color: hsla(196, 100%, 44%, 1); + --md-accent-fg-color--transparent: hsla(196, 100%, 44%, 0.1); +} + + /* Hide images by default for dark mode */ + img[src$="#only-dark"] { + display: none; + } + +@media screen { + [data-md-color-scheme="slate"] { + --md-primary-fg-color: var(--md-primary-fg-color--dark); + --md-accent-fg-color: hsla(16, 100%, 42%, 1); + --md-typeset-a-color: #FFA98A; + --md-default-bg-color: #121212 + } + + /* Hide images for light mode */ + [data-md-color-scheme="slate"] img[src$="#only-light"] { + display: none; + } + + /* Show images for dark mode */ + [data-md-color-scheme="slate"] img[src$="#only-dark"] { + display: initial; + } + +} + +/* Add border to images and prevent emojis to get bordered by +injecting this class optional */ +img[src$="#border"], +img[src$="#only-dark#border"], +img[src$="#only-light#border"], +img[src$="#border#only-dark"], +img[src$="#border#only-light"] { + border: .01rem solid var(--md-typeset-kbd-border-color); + border-radius: .1rem; + padding: .25rem +} + +.md-search-result__meta { + /* background-color: var(--md-default-fg-color); */ + color: var(--md-typeset-color); +} + +.md-top { + background-color: #FFA98A; + color: var(--md-default-bg-color) +} \ No newline at end of file diff --git a/docs/assets/img/dcm_qa_nih_repo-dark.png b/docs/assets/img/dcm_qa_nih_repo-dark.png new file mode 100644 index 00000000..39e34015 Binary files /dev/null and b/docs/assets/img/dcm_qa_nih_repo-dark.png differ diff --git a/docs/assets/img/dcm_qa_nih_repo-light.png b/docs/assets/img/dcm_qa_nih_repo-light.png new file mode 100644 index 00000000..54e5ae00 Binary files /dev/null and b/docs/assets/img/dcm_qa_nih_repo-light.png differ diff --git a/docs/assets/img/github-issue-dark.png b/docs/assets/img/github-issue-dark.png new file mode 100644 index 00000000..2e2332cb Binary files /dev/null and b/docs/assets/img/github-issue-dark.png differ diff --git a/docs/assets/img/github-issue-light.png b/docs/assets/img/github-issue-light.png new file mode 100644 index 00000000..2a678b33 Binary files /dev/null and b/docs/assets/img/github-issue-light.png differ diff --git a/docs/assets/img/neurostars-1-dark.png b/docs/assets/img/neurostars-1-dark.png new file mode 100644 index 00000000..795a369b Binary files /dev/null and b/docs/assets/img/neurostars-1-dark.png differ diff --git a/docs/assets/img/neurostars-1-light.png b/docs/assets/img/neurostars-1-light.png new file mode 100644 index 00000000..04ea2a07 Binary files /dev/null and b/docs/assets/img/neurostars-1-light.png differ diff --git a/docs/assets/img/neurostars-2-dark.png b/docs/assets/img/neurostars-2-dark.png new file mode 100644 index 00000000..ded46b15 Binary files /dev/null and b/docs/assets/img/neurostars-2-dark.png differ diff --git a/docs/assets/img/neurostars-2-light.png b/docs/assets/img/neurostars-2-light.png new file mode 100644 index 00000000..86ca3b12 Binary files /dev/null and b/docs/assets/img/neurostars-2-light.png differ diff --git a/docs/assets/img/neurostars-3-dark.png b/docs/assets/img/neurostars-3-dark.png new file mode 100644 index 00000000..2cbcea7c Binary files /dev/null and b/docs/assets/img/neurostars-3-dark.png differ diff --git a/docs/assets/img/neurostars-3-light.png b/docs/assets/img/neurostars-3-light.png new file mode 100644 index 00000000..f2057f90 Binary files /dev/null and b/docs/assets/img/neurostars-3-light.png differ diff --git a/docs/assets/img/neurostars-4-dark.png b/docs/assets/img/neurostars-4-dark.png new file mode 100644 index 00000000..7e54482f Binary files /dev/null and b/docs/assets/img/neurostars-4-dark.png differ diff --git a/docs/assets/img/neurostars-4-light.png b/docs/assets/img/neurostars-4-light.png new file mode 100644 index 00000000..c67595d5 Binary files /dev/null and b/docs/assets/img/neurostars-4-light.png differ diff --git a/docs/get-started/index.md b/docs/get-started/index.md new file mode 100644 index 00000000..b510426c --- /dev/null +++ b/docs/get-started/index.md @@ -0,0 +1,41 @@ +--- +title: Getting started +summary: How to get started with dcm2bids +authors: + - Samuel Guay +date: 2022-04-17 +--- + +# Getting started with dcm2bids + +## How to get the most out of the documentation + +Our documentation is organized in 4 main parts and each fulfills a different +function: + +1. **[Installation][installation]**: A beginner-friendly guide that walks + through the installation process, including the creation of a dedicated + environment. + + - TL;DR: Run `conda install -c conda-forge dcm2bids` or + `pip install dcm2bids` within your project environment. + +2. **[Tutorials][tutorial]**: Aimed at beginners and people new to dcm2bids, + the tutorials are a series of steps that describes in length how to use + dcm2bids in order to understand how dcm2bids works. +3. **[How-to guides][how-to]**: Analogous to recipes, these guides provides + series of steps to address typical problems and use-cases when converting + into BIDS. They are less verbose than tutorials and assume some + understanding of BIDS-related concepts and how dcm2bids works. + + - There is an exception worth reading by anyone: [How-to Get help and + support][get-help] + +4. **[Technical reference][reference]**: Automated rendering of the code that + composes the inner machinery of dcm2bids. + +[installation]: ./install.md +[tutorial]: ../tutorial/first-steps.md +[how-to]: ../how-to +[reference]: /reference/dcm2bids +[get-help]: ../how-to/get-help.md diff --git a/docs/get-started/install.md b/docs/get-started/install.md new file mode 100644 index 00000000..d02bcb6b --- /dev/null +++ b/docs/get-started/install.md @@ -0,0 +1,342 @@ +--- +summary: Set of instructions to help install dcm2bids and dependencies. +authors: + - Samuel Guay +date: 2022-04-17 +--- + +# Installation + +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. + +We recommend to skim-read the full page **before** you start installing anything +considering there are many ways to install software in the Python ecosystem +which are often dependent on the familiarity and preference of the user. + +We offer recommendations at the bottom of the page that will take care of the +whole installation process in one go and make use of a dedicated environment for +dcm2bids. + +??? tip "You just want the installation command?" + + If you are used to installing packages, you can get it from PyPI or conda: + + `pip install dcm2bids` + + `conda install -c conda-forge dcm2bids` + +## Dependencies + +### 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 +above** to run dcm2bids properly. + +If you are unsure what version(s) of Python is available on your machine, you +can find out by opening a terminal and typing `python --version` or `python`. +The former will output the version directly in the terminal while the latter +will open an interactive Python shell with the version displayed in the first +line. + +=== "python --version" + + ```bash hl_lines="2" + sam:~$ python --version + Python 3.10.4 + ``` + +=== "python" + + ```bash hl_lines="2" + sam:~$ python + Python 3.10.4 | packaged by conda-forge | (main, Mar 24 2022, 17:39:04) [GCC 10.3.0] on linux + Type "help", "copyright", "credits" or "license" for more information. + >>> exit() + ``` + +If your system-wide version of Python is lower 3.7, 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. + +If you are a **beginning user** in the Python ecosystem, the odds are that you +have installed [Anaconda][anaconda], which contains all Python versions so you +should be good. If you were not able to find out which version of Python is +installed on your machine or find Anaconda on your machine, we recommend that +you install Python through [Anaconda][anaconda]. + +??? question "Should I install Anaconda or Miniconda?" + + If you unsure what to install read this [section describing the differences between Anaconda and Miniconda][mini-vs-ana] to help you choose. + +### dcm2niix + +[dcm2niix][dcm2niix] can also be installed in a variety of ways as seen on [the +main page of the software][dcm2niix-install]. + +Whether you want to install the latest compiled executable directly on your +machine is up to you but you have to **make sure you can call the software from +any directory**. In other words, you have to make sure it is included in your +`$PATH`. Otherwise, dcm2bids won't be able to run dcm2niix for you. That's why +we recommend to install it at the same time in the dedicated environment. + +As you can see, dcm2niix is available through [conda][conda] so that is the +approach chosen in this guide. We will benefit from the simplicity of installing +all software from the same located at. Steps to install dcm2niix are included in +the next secton. + +## Recommendations + +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 +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 +make your life easier. + +??? info "More info on conda" + + Conda is an open-source package management system and environment management + system that runs on Windows, macOS, and Linux. Conda quickly installs, runs, and + updates packages and their dependencies. Conda easily creates, saves, loads, and + switches between environments on your local computer. The conda package and + environment manager is included in all versions of Anaconda and Miniconda. + - [conda docs](https://docs.conda.io/projects/conda/en/latest/) + +??? question "But I use another package/env management system, what do I do?" + + Of course you can use your preferred package/env management system, whether it + is venv, virtualenv, pyenv, pip, poetry, etc. This guide was built on the + basis that no previous knowledge is required to install and learn dcm2bids by so + providing a simple way to install dcm2bids without having to worry about the + rest. + +??? question "I already created an environment for my project, what do I do?" + + You can update your environment either by: + + 1. installing dcm2bids while your environment is active like any package; or + 2. adding dcm2bids to the dependencies and updating your environment + + Here's an example with conda after updating an `environment.yml` file: + + ```bash + conda env update --file environment.yml --prune + ``` + +### Install dcm2bids + +From now on, it is assumed that [conda][conda] (or [Anaconda][anaconda]) is +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. + +We could install all the software one by one using a series of command: + +```bash +conda install -c conda-forge dcm2bids +conda install -c conda-forge dcm2niix +``` + +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 +dedicated environments, we can create a file, often called `environment.yml`, +which is used to specify things such as the dependencies that need to be +installed inside the environment. + +To create such a file, you can use any code editor or your terminal to write or +paste the information below, and save it in your project directory with the name +`environment.yml`: + +You can create a project directory anywhere on your computer, it does not +matter. You can create `dcm2bids-proj` if you need inspiration. + +```yaml title="environment.yml" +name: dcm2bids +channels: + - conda-forge +dependencies: + - python>=3.7 + - dcm2niix + - dcm2bids +``` + +In short, here's what the fields mean: + +- The `name:` key refers to the name of the dedicated environment. You will have + to use this name to activate your environment and use software installed + inside. The name is arbitrary, you can name it however you want. +- The `channels:` key tells conda where to look for the declared dependencies. + In our case, all our dependencies are located on the [conda-forge + channel][conda-forge]. +- The `dependencies:` key lists all the dependencies to be installed inside the + 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 + satisfied for dcm2bids as the newer version of dcm2bids may face issue with + Python 3.6 and below. + +Now that all the dependencies have been specified, it is time to create the new +conda environment dedicated to dcm2bids! :tada: + +#### Create conda environment + install dcm2bids + +Open a terminal and go in the directory where you put the `environment.yml` run +this command: + +```bash +conda env create --file environment.yml +``` + +If the executation was successful, you should see a message similar to: + +```bash hl_lines="14" +sam:~/dcm2bids-proj$ nano environment.yml +sam:~/dcm2bids-proj$ conda env create --file environment.yml +Collecting package metadata (repodata.json): done +Solving environment: |done + +Downloading and Extracting Packages +future-0.18.2 | 738 KB | ########################################## | 100% +Preparing transaction: done +Verifying transaction: done +Executing transaction: done +# +# To activate this environment, use +# +# $ conda activate dcm2bids +# +# To deactivate an active environment, use +# +# $ conda deactivate +``` + +#### Activate environment + +Last step is to make sure you can activate[^1] your environment by running the +command: + +```bash +conda activate dcm2bids +``` + +:warning: Remember that dcm2bids here refer to the name given specified in the +`environment.yml`. + +```bash hl_lines="2" +sam:~/dcm2bids-proj$ conda activate dcm2bids +(dcm2bids) sam:~/dcm2bids-proj$ +``` + +You can see the environment is activated as a new `(dcm2bids)` appear in front +of the username. + +#### Verify that dcm2bids works + +Finally, you can test that dcm2bids was installed correctly by running the any +dcm2bids command such as `dcm2bids --help`: + +```bash hl_lines="1" +(dcm2bids) sam:~/dcm2bids-proj$ dcm2bids --help +usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c + CONFIG [-o OUTPUT_DIR] [--forceDcm2niix] [--clobber] + [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] + +Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure +dcm2bids 2.1.6 + +options: + -h, --help show this help message and exit + -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...] + DICOM directory(ies) + -p PARTICIPANT, --participant PARTICIPANT + Participant ID + -s SESSION, --session SESSION + Session ID + -c CONFIG, --config CONFIG + JSON configuration file (see example/config.json) + -o OUTPUT_DIR, --output_dir OUTPUT_DIR + Output BIDS directory, Default: current directory + (/home/sam/dcm2bids-proj) + --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists + --clobber Overwrite output if it exists + -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + Set logging level + -a, --anonymizer This option no longer exists from the script in this + release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m + aster/README.md#defaceTpl + + Documentation at https://github.com/unfmontreal/Dcm2Bids +``` + +Voilà, you are ready to use dcm2bids or at least +[move onto the tutorial](../tutorial/first-steps.md)!! + +[Go to the Tutorial section](../../tutorial){ .md-button } + +[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 + +In sum, installing dcm2bids is quite easy if you know how to install Python +packages. The easiest way to install it is to follow the steps below using +[conda][conda] but it is also possible to use other software, including +containers: + +- [ ] Create an [`environment.yml`](#create-environmentyml) file with + dependencies + + - [x] Content: + + name: dcm2bids + channels: + - conda-forge + dependencies: + - python>=3.7 + - dcm2niix + - dcm2bids + + +- [ ] Create conda environment + - [x] `conda env create --file environment.yml` +- [ ] Activate conda environment + - [x] `conda activate dcm2bids` +- [ ] Verify a dcm2bids command + - [x] `dcm2bids --help` +- [ ] Consult how-to guides or follow the tutorial + +[anaconda]: https://www.anaconda.com/distribution +[dcm2niix]: https://github.com/rordenlab/dcm2niix +[dcm2niix-install]: https://github.com/rordenlab/dcm2niix#install +[conda]: https://conda.io/en/latest/miniconda.html +[conda-forge]: https://anaconda.org/conda-forge +[docker]: https://docker.com +[apptainer]: https://apptainer.org +[mini-vs-ana]: + https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html#anaconda-or-miniconda + +[^1]: + To get out of a conda environment, you have to deactivate it with the + `conda deactivate` command. diff --git a/docs/how-to/create-config-file.md b/docs/how-to/create-config-file.md new file mode 100644 index 00000000..005e9899 --- /dev/null +++ b/docs/how-to/create-config-file.md @@ -0,0 +1,159 @@ +# How to create a configuration file + +## Configuration file example + +```json +{ + "descriptions": [ + { + "dataType": "anat", + "modalityLabel": "T2w", + "criteria": { + "SeriesDescription": "*T2*", + "EchoTime": 0.1 + }, + "sidecarChanges": { + "ProtocolName": "T2" + } + }, + { + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", + "criteria": { + "ProtocolName": "func_task-*", + "ImageType": ["ORIG*", "PRIMARY", "M", "MB", "ND", "MOSAIC"] + } + }, + { + "dataType": "fmap", + "modalityLabel": "fmap", + "intendedFor": 1, + "criteria": { + "ProtocolName": "*field_mapping*" + } + }, + { + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-learning", + "criteria": { + "SeriesDescription": "bold_task-learning" + }, + "sidecarChanges": { + "TaskName": "learning" + } + }, + { + "dataType": "fmap", + "modalityLabel": "epi", + "criteria": { + "SeriesDescription": "fmap_task-learning" + }, + "IntendedFor": 2, + "sidecarChanges": { + "TaskName": "learning" + } + } + ] +} +``` + +The `descriptions` field is a list of descriptions, each describing some +acquisition. In this example, the configuration describes five acquisitions, a +T2-weighted, a resting-state fMRI, a fieldmap, and an fMRI learning task with +another fieldmap. + +Each description tells dcm2bids how to group a set of acquisitions and how to +label them. In this config file, Dcm2Bids is being told to collect files +containing + +```json +{ + "SeriesDescription": "AXIAL_T2_SPACE", + "EchoTime": 0.1 +} +``` + +in their sidecars[^1] and label them as `anat`, `T2w` type images. + +## criteria + +dcm2bids will try to match the sidecars[^1] of dcm2niix to the descriptions of +the configuration file. The values you enter inside the criteria dictionary are +patterns that will be compared to the corresponding key of the sidecar. + +The pattern matching is shell-style. It's possible to use wildcard `*`, single +character `?` etc ... Please have a look at the [GNU documentation][gnu-pattern] +to know more. + +For example, in the second description, the pattern `*T2*` will be compared to +the value of `SeriesDescription` of a sidecar. `AXIAL_T2_SPACE` will be a match, +`AXIAL_T1` won't. + +`dcm2bids` has a `SidecarFilename` key, as in the first description, if you +prefer to also match with the filename of the sidecar. Note that filename are +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 + +It is a mandatory field. Here is a definition from `bids v1.2.0` : + +> Data type - a functional group of different types of data. In BIDS we define +> six data types: func (task based and resting state functional MRI), dwi +> (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as +> field maps), anat (structural imaging such as T1, T2, etc.), meg +> (magnetoencephalography), beh (behavioral). + +## modalityLabel + +It is a mandatory field. It describes the modality of the acquisition like +`T1w`, `T2w` or `dwi`, `bold`. + +## customLabels + +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`. + +To know more on how to set these fields, read the [BIDS +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 + +Optional field to change or add information in a sidecar. + +## 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. + +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. + +## Multiple config files + +It is possible to create multiple config files and iterate the `dcm2bids` +command over the different config files to structure data that have different +parameters in their sidecar files. + +[^1]: + For each acquisition, `dcm2niix` creates an associated `.json` file, + containing information from the dicom header. These are known as + **sidecars**. These are the sidecars that `dcm2bids` uses to filter the + groups of acquisitions. + + To define the filters you need, you will probably have to review these + sidecars. You can generate all the sidecars for an individual participant + using the [dcm2bids_helper](./use-main-commands.md#tools) command. + +[bids-spec]: https://bids-specification.readthedocs.io/en/stable/ +[gnu-pattern]: + https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html diff --git a/docs/how-to/get-help.md b/docs/how-to/get-help.md new file mode 100644 index 00000000..3c59cdae --- /dev/null +++ b/docs/how-to/get-help.md @@ -0,0 +1,163 @@ +--- +summary: How-to Get help and support for dcm2bids-related questions +authors: + - Samuel Guay +date: 2022-04-17 +--- + +# How to get help and support + +We work hard to make sure dcm2bids is robust and we welcome comments and +questions to make sure it meets your use case! + +While the dcm2bids volunteers and the neuroimaging community at large do their +best to respond to help requests about dcm2bids, there are steps you can do to +try to find answers and ways to optimize how to ask questions on the different +channels. The path may be different according to your situation whether you want +to ask a usage question or report a bug. + +## Where to **look** for answers + +Before looking for answers on any Web search engine, the best places to look for +answers are: + +### 1. **This documentation** + +You can use the built-in search function with key words or look throughout the +documentation. If you end up finding your answer somewhere else, please inform +us by [opening an issue](#open-an-issue). If you faced an undocumented challenge +while using dcm2bids, it is very likely others will face it as well. By +gathering community knowledge, the documentation will improve drastically. Refer +to the [Request a new feature section](#request-a-new-feature) below if you are +unfamiliar with GitHub and issues. + +### 2. **Community support channels** + +There is a couple of places you can look for + +#### **[NeuroStars][neurostars]** + +!!! info "What is [neurostars.org][neurostars]?" + + [NeuroStars][neurostars] is a question and answer forum for neuroscience + researchers, infrastructure providers and software developers, and free to + access. It is managed by the [International Neuroinformatics Coordinating + Facility (INCF)][incf] and it is widely used by the neuroimaging community. + +[NeuroStars][neurostars] is a gold mine of information about how others solved +their problems or got answered to their questions regarding anything +neuroscience, especially neuroimaging. [NeuroStars][neurostars] is a good place +to ask questions related to dcm2bids and the [BIDS][bids] standards. Before +asking your own questions, you may want to **first browse through questions that +were tagged with the [dcm2bids tag][neurostars-dcm2bids]**. + +To look for everything related to a specific tag, here's how you can do it for +the **dcm2bids** tag: + +!!! tip "The quick way" + + Type in your URL bar [https://neurostars.org/tag/dcm2bids][neurostars-dcm2bids] or click directly on it to bring the page will all post tagged with a dcm2bids tag. Then if you click on search, the **dcm2bids** will already be selected for you. + +1. Go to [https://neurostars.org][neurostars]. +2. Click on the **search** (:mag:) icon. +3. Either **click on options** to bring the advanced search and go to next step + **OR start typing _dcm2bids_**. +4. In the tag section on the right pane, select **dcm2bids**. +5. Type your question in the search bar. + + + - You might have to refine your question a couple of times to find the most + relevant answers. + + +??? example "Steps in pictures" + + ![](../assets/img/neurostars-1-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/neurostars-2-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/neurostars-3-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/neurostars-4-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/neurostars-1-light.png#border#only-light){ loading=lazy } + ![](../assets/img/neurostars-2-light.png#border#only-light){ loading=lazy } + ![](../assets/img/neurostars-3-light.png#border#only-light){ loading=lazy } + ![](../assets/img/neurostars-4-light.png#border#only-light){ loading=lazy } + +The next step before going on a search engine is to go where we develop +dcm2bids, namely GitHub. + +#### **GitHub** + +While we use GitHub to develop dcm2bids, some people have opened issues that +could be relevant to your situation. You can browse through the open and closed +issues: https://github.com/UNFmontreal/Dcm2Bids/issues?q=is%3Aissue and search +for specific keywords or error messages. + +If you find a specific issue and would like more details about it, you can +simply write an additional comment in the _Leave a comment_ section and press +_Comment_. + +??? example "Example in picture" + + ![](../assets/img/github-issue-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/github-issue-light.png#border#only-light){ loading=lazy } + +## Where to **ask** for questions, report a bug or request a feature + +After having read thoroughly all information you could find online about your +question or issue, you may still some lingering questions or even more +questions - that is okay! After all, maybe you would like to use dcm2bids for a +specific use-case that has never been mentioned anywhere before. Below are +described 3 ways to request help depending on your situation: + +1. Ask a question about dcm2bids +2. Report a bug +3. Request a new feature + +### Questions related to using dcm2bids: + +We encourage you to post your question on [NeuroStars][neurostars] with +[dcm2bids][neurostars-dcm2bids] as an optional tag. The tag is really important +because [NeuroStars][neurostars-dcm2bids] will notify the `dcm2bids` team only +if the tag is present. You will get a quicker reply this way. + +### Report a bug + +If you think you've found a bug :bug:, and you could not find an issue already +mentioning the problem, please open an issue on [our +repository][dcm2bids-issues]. If you don't know how to open an issue, refer to +the [open an issue](#open-an-issue) section below. + +### Request a new feature + +If you have more an inquiry or suggestion to make than a bug to report, we +encourage you to start a conversation in the [Discussions +section][dcm2bids-discussions]. Similar to the bug reporting procedure, follow +the [open an issue](#open-an-issue) below. + +--- + +### Open an issue + +To open or comment on an issue, you will need a [GitHub][github] account. + +Issues are individual pieces of work (a bug to fix or a feature) that need to be +completed to move the project forwards. We highly recommend you open an issue to +explain what you want to do and how it echoes a specific demand from the +community. Keep in mind the scope of the `dcm2bids` project. + +A general guideline: if you find yourself tempted to write a great big issue +that is difficult to describe as one unit of work, please consider splitting it +into two or more. Moreover, it will be interesting to see how others approach +your issue and give their opinion and advice to solve it. + +If you have more an inquiry or suggestion to make than a bug to report, we +encourage you to start a conversation in the [Discussions +section][dcm2bids-discussions]. Note that issues may be converted to a +discussion if deemed relevant by the maintainers. + +[bids]: http://bids.neuroimaging.io +[dcm2bids-doc]: https://unfmontreal.github.io/Dcm2Bids/ +[dcm2bids-discussions]: https://github.com/UNFmontreal/Dcm2Bids/discussions/ +[dcm2bids-issues]: https://github.com/UNFmontreal/Dcm2Bids/issues +[github]: https://github.com +[neurostars]: https://neurostars.org/ +[neurostars-dcm2bids]: https://neurostars.org/tag/dcm2bids diff --git a/docs/how-to/index.md b/docs/how-to/index.md new file mode 100644 index 00000000..1d6bb887 --- /dev/null +++ b/docs/how-to/index.md @@ -0,0 +1,21 @@ +--- +title: How-to guides +--- + +# How-to guides + +## Help + +- [Get help and support](./get-help.md) + +## Usage + +- [Use main commands](./use-main-commands.md) + +- [Create a config file](./create-config-file.md) + +- [Use advanced commands](./use-advanced-commands.md) + +## Development and Community + +- [Contribute to dcm2bids](/CONTRIBUTING.md) diff --git a/docs/4-advanced.md b/docs/how-to/use-advanced-commands.md similarity index 59% rename from docs/4-advanced.md rename to docs/how-to/use-advanced-commands.md index 3047b15e..4ac92674 100644 --- a/docs/4-advanced.md +++ b/docs/how-to/use-advanced-commands.md @@ -1,6 +1,7 @@ -# Advanced configuration +# How to use advanced commands and configuration -These optional configurations could be insert in the configuration file at the same level as the `"descriptions"` entry. +These optional configurations could be insert in the configuration file at the +same level as the `"descriptions"` entry. ``` { @@ -17,27 +18,30 @@ These optional configurations could be insert in the configuration file at the s default: `"searchMethod": "fnmatch"` -fnmatch is the behaviour (See criteria) by default and the fall back if this option is set incorrectly. `re` is the other choice if you want more flexibility to match criteria. +fnmatch is the behaviour (See criteria) by default and the fall back if this +option is set incorrectly. `re` is the other choice if you want more flexibility +to match criteria. ## caseSensitive default: `"caseSensitive": "true"` -If false, comparisons between strings/lists will be not case sensitive. -It's only disabled when used with `"searchMethod": "fnmatch"`. +If false, comparisons between strings/lists will be not case sensitive. It's +only disabled when used with `"searchMethod": "fnmatch"`. ## defaceTpl default: `"defaceTpl": None` -!!! danger - The anonymizer option no longer exists from `v2.0.0`. It is still possible to deface the anatomical nifti images. +!!! danger The anonymizer option no longer exists from `v2.0.0`. It is still +possible to deface the anatomical nifti images. For example, if you use the last version of pydeface, add: `"defaceTpl": "pydeface --outfile {dstFile} {srcFile}"` -It is a template string and dcm2bids will replace {srcFile} and {dstFile} by the source file (input) and the destination file (output). +It is a template string and dcm2bids will replace {srcFile} and {dstFile} by the +source file (input) and the destination file (output). ## dcm2niixOptions @@ -49,4 +53,6 @@ Arguments for dcm2niix default: `"compKeys": ["SeriesNumber", "AcquisitionTime", "SidecarFilename"]` -Acquisitions are sorted using the sidecar data. The default behaviour is to sort by `SeriesNumber` then by `AcquisitionTime` then by the `SidecarFilename`. You can change this behaviour setting this key inside the configuration file. +Acquisitions are sorted using the sidecar data. The default behaviour is to sort +by `SeriesNumber` then by `AcquisitionTime` then by the `SidecarFilename`. You +can change this behaviour setting this key inside the configuration file. diff --git a/docs/how-to/use-main-commands.md b/docs/how-to/use-main-commands.md new file mode 100644 index 00000000..ef2223dc --- /dev/null +++ b/docs/how-to/use-main-commands.md @@ -0,0 +1,73 @@ +# How to use main commands + +## Command Line Interface (CLI) + +How to launch dcm2bids when you have build your configuration file ? First `cd` +in your BIDS directory. + +```bash +dcm2bids -d DICOM_DIR -p PARTICIPANT_ID -c CONFIG_FILE +``` + +If your participant have a session ID: + +```bash +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. + +## 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 +already exists, dcm2bids won't overwrite it. You should use the `--clobber` +option to overwrite files. + +If a description matches several sidecars, dcm2bids will add automatically the +custom label `run-` to the filename. + +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. + +## Tools + +- Helper + +```bash +dcm2bids_helper -d DICOM_DIR [-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. + +- Scaffold + +```bash +dcm2bids_scaffold [-o OUTPUT_DIR] +``` + +Create basic BIDS files and directories in the output directory (by default +folder where the script is launched). + +[json-editor]: http://jsoneditoronline.org/ + +[^1]: + For each acquisition, `dcm2niix` creates an associated `.json` file, + containing information from the dicom header. These are known as + **sidecars**. These are the sidecars `dcm2bids` uses to filter the groups of + acquisitions. + + To define this filtering you will probably need to review these sidecars. + You can generate all the sidecars for an individual participant using + [dcm2bids_helper](./use-main-commands.md#tools). + +--8<-- "docs_helper/abbreviations.md" diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css deleted file mode 100644 index bb0cacf8..00000000 --- a/docs/stylesheets/extra.css +++ /dev/null @@ -1,19 +0,0 @@ -:root { - --md-primary-fg-color: hsla(16, 100%, 42%, 1); - --md-primary-fg-color--light: hsla(16, 100%, 64%, 1); - --md-primary-fg-color--dark: hsla(16, 100%, 28%, 1); - - --md-accent-fg-color: hsla(196, 100%, 44%, 1); - --md-accent-fg-color--transparent: hsla(196, 100%, 44%, 0.1); -} - -[data-md-color-scheme="slate"] { - --md-primary-fg-color: var(--md-footer-bg-color--dark); - --md-primary-bg-color: hsla(16, 100%, 42%, 1); - --md-hue: 213; -} - -.md-search-result__meta { - /* background-color: var(--md-default-fg-color); */ - color: var(--md-typeset-color); -} \ No newline at end of file diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md new file mode 100644 index 00000000..a82ba5ae --- /dev/null +++ b/docs/tutorial/first-steps.md @@ -0,0 +1,1125 @@ +# Tutorial - First steps + +## How to use this tutorial + +This tutorial was developed assuming no prior knowledge of the tool, and little +knowledge of the command line (terminal). It aims to be beginner-friendly by +giving a lot of details. To get the most out of it, you recommend that you run +the commands throughout the tutorial and compare your outputs with the outputs +from the example. + +Every time you need to run a command, you will see two tabs, one for the command +you need to run, and another one with the expected output. While you can copy +the command, you recommend that you type each command, which is good for your +procedural memory :brain:. The **Command** and **Output** tabs will look like +these: + +=== "Command" + + ```sh + echo "Hello, World!" + ``` + +=== "Output" + + ```sh + sam:~/$ echo "Hello, World!" + Hello, World! + ``` + +Note that in the Output tab, the content before the command prompt (`$`) will be +dependend or your operating system and terminal configuration. What you want to +compare is what follows it and the output below the command that was ran. The +output you see was taken directly out of your terminal when you tested the +tutorial. + +## Setup + +!!! warning "dcm2bids must be installed" + + If you have not installed dcm2bids yet, now is the time to go to the [installation page](../get-started/install.md) and install dcm2bids with its dependencies. This tutorial does not cover the installation part and assumes you have dcm2bids properly installed. + +### Activate your dcm2bids environment + +If you followed the [installation procedure](../get-started/install.md), you +have to activate your dedicated environment for dcm2bids. + +Note that you use `dcm2bids` as the name of the environment but you should use +the name you gave your environment when you created it. + +=== "Command" + + ```sh + conda activate dcm2bids + ``` + +=== "Output" + + ```sh + conda activate dcm2bids + (dcm2bids) sam:~$ + ``` + +### Test your environment + +It is always good to make sure you have access to the software you want to use. +You can test it with any command but a safe way is to use the `--help` command. + +=== "Command" + + ```sh + dcm2bids --help + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~$ dcm2bids --help + usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c + CONFIG [-o OUTPUT_DIR] [--forceDcm2niix] [--clobber] + [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] + + Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure + dcm2bids 2.1.6 + + options: + -h, --help show this help message and exit + -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...] + DICOM directory(ies) + -p PARTICIPANT, --participant PARTICIPANT + Participant ID + -s SESSION, --session SESSION + Session ID + -c CONFIG, --config CONFIG + JSON configuration file (see example/config.json) + -o OUTPUT_DIR, --output_dir OUTPUT_DIR + Output BIDS directory, Default: current directory + (/home/sam) + --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists + --clobber Overwrite output if it exists + -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + Set logging level + -a, --anonymizer This option no longer exists from the script in this + release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m + aster/README.md#defaceTpl + + Documentation at https://github.com/unfmontreal/Dcm2Bids + + ``` + +??? bug "What you can do if you did not get this output" + + If you got `dcm2bids: command not found`, it means dcm2bids is not either not installed or not accessible in your current environment. Did you activate your environment? + + Visit the [installation page](../get-started/install.md) for more info. + +### Create a new directory for this tutorial + +For the tutorial, you recommend that you create a new directory (folder) instead +of jumping straight into a real project directory with real data. In this +tutorial, we decided to named our project directory `dcm2bids-tutorial`. + +=== "Command" + + ```sh + mkdir dcm2bids-tutorial + cd dcm2bids-tutorial + ``` + +=== "Output" + + ```bash + (dcm2bids) sam:~$ mkdir dcm2bids-tutorial + (dcm2bids) sam:~$ cd dcm2bids-tutorial/ + (dcm2bids) sam:~/dcm2bids-tutorial$ + # no output is printed by mkdir and cd if when the command is successful. + # You can now see that you are inside dcm2bids-tutorial directory. + ``` + +## Scaffolding + +While scaffolding is a not mandatory step before converting data with the main +`dcm2bids` command, it is highly recommended when you plan to convert data. +dcm2bids has a command named **`dcm2bids_scaffold`** that will help you +structure and organize your data in an efficient way by creating automatically +for you a basic directory structure and the core files according to the [Brain +Imaging Data Structure (BIDS) specification][bids-spec]. + +### Tree structure of the scaffold created by dcm2bids + +```sh +scaffold_directory/ +├── CHANGES +├── code/ +├── dataset_description.json +├── derivatives/ +├── participants.json +├── participants.tsv +├── README +└── sourcedata/ + +3 directories, 5 files +``` + +Describing the function of each directory and files is out of the scope of this +tutorial but if you want to learn more about BIDS, you encourage you to go +through the [BIDS Starter Kit][bids-starter-kit]. + +### Run `dcm2bids_scaffold` + +To find out how to run `dcm2bids_scaffold` work, you can use the `--help` +option. + +=== "Command" + + ```sh + dcm2bids_scaffold --help + ``` + +=== "Output" + + ```sh hl_lines="9-10" + (dcm2bids) sam:~/dcm2bids-tutorial$ dcm2bids_scaffold --help + usage: dcm2bids_scaffold [-h] [-o OUTPUT_DIR] + + Create basic BIDS files and directories + + + options: + -h, --help show this help message and exit + -o OUTPUT_DIR, --output_dir OUTPUT_DIR + Output BIDS directory, Default: current directory + + Documentation at https://github.com/unfmontreal/Dcm2Bids + + ``` + +As you can see at lines 9-10, `dcm2bids_scaffold` has an `--output_dir` (or `-o` +for short) option with a default option, which means you can either specify +where you want the scaffolding to happen to be or it will create the scaffold in +the current directory as a default. + +Below you can see the difference between specifying `-o output_dir` and NOT +specifying (using the default) the `-o` option. + +Note that you don't have to create the directory where you want to put the +scaffold beforehand, the command will create it for you. + +=== "Commands" + + ```sh + dcm2bids_scaffold + ``` + **VS** + + ```sh + dcm2bids_scaffold -o bids_project + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial$ dcm2bids_scaffold + (dcm2bids) sam:~/dcm2bids-tutorial$ ls + CHANGES dataset_description.json participants.json README + code derivatives participants.tsv sourcedata + + ``` + **VS** + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial$ dcm2bids_scaffold -o bids_project + (dcm2bids) sam:~/dcm2bids-tutorial$ ls -F + bids_project/ + (dcm2bids) sam:~/dcm2bids-tutorial$ ls -F bids_project/ + CHANGES dataset_description.json participants.json README + code/ derivatives/ participants.tsv sourcedata/ + ``` + +For the purpose of the tutorial, you chose to specify the output directory +**`bids_project`** as if it were the start of a new project. For your real +projects, you can choose to create a new directory with the commands or not, it +is entirely up to you. + +### Change directory to go in your scaffold + +For those who created the scaffold in another directory, you must go inside that +directory. + +=== "Command" + + ```sh + cd bids_project + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial$ cd bids_project/ + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ + ``` + +## Download neuroimaging data + +For this tutorial, you will use a set of DICOMs made available by +[neurolabusc][dcm_qa_nih] on GitHub. + +??? info "Why use these data in particular?" + + You use the [dcm_qa_nih][dcm_qc_nih] data because it is the data used by the + dcm2niix developers to validate the DICOM to NIfTI conversion process and it + has been proven stable since 2017. It also includes data from both GE as + well as Siemens MRI scanners so it gives a bit a diversity of data provenance. + +To download the data, you can use your terminal or the GitHub interface. You can +do it any way you want as long as the directory with the dicoms is in +**sourcedata** directory with the name **dcm_qa_nih**. + +=== "Terminal" + + === "Commands" + + 1. Download the zipped file from . + ```sh + wget -O dcm_qa_nih-master.zip https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip + ``` + + 2. Extract/unzip the zipped file into **sourcedata/**. + ```sh + unzip dcm_qa_nih-master.zip -d sourcedata/ + ``` + + 3. Rename the directory **dcm_qa_nih**. + ```sh + mv sourcedata/dcm_qa_nih-master sourcedata/dcm_qa_nih + ``` + + **OR** + + 1. You can clone the repository if you are familiar with Git. If you did the + steps above, move on. + ```sh + git clone https://github.com/neurolabusc/dcm_qa_nih/ sourcedata/dcm_qa_nih + ``` + + --- + + === "Output" + + ```sh hl_lines="1 18 33" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ wget -O dcm_qa_nih-master.zip https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip + --2022-04-18 22:17:26-- https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip + Resolving github.com (github.com)... 140.82.112.3 + Connecting to github.com (github.com)|140.82.112.3|:443... connected. + HTTP request sent, awaiting response... 302 Found + Location: https://codeload.github.com/neurolabusc/dcm_qa_nih/zip/refs/heads/master [following] + --2022-04-18 22:17:26-- https://codeload.github.com/neurolabusc/dcm_qa_nih/zip/refs/heads/master + Resolving codeload.github.com (codeload.github.com)... 140.82.113.9 + Connecting to codeload.github.com (codeload.github.com)|140.82.113.9|:443... connected. + HTTP request sent, awaiting response... 200 OK + Length: 10258820 (9.8M) [application/zip] + Saving to: ‘dcm_qa_nih-master.zip’ + + dcm_qa_nih-master.zip 100%[======================>] 9.78M 3.24MB/s in 3.0s + + 2022-04-18 22:17:29 (3.24 MB/s) - ‘dcm_qa_nih-master.zip’ saved [10258820/10258820] + + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ unzip dcm_qa_nih-master.zip -d sourcedata/ + Archive: dcm_qa_nih-master.zip + aa82e560d5471b53f0d0332c4de33d88bf179157 + creating: sourcedata/dcm_qa_nih-master/ + extracting: sourcedata/dcm_qa_nih-master/.gitignore + creating: sourcedata/dcm_qa_nih-master/In/ + creating: sourcedata/dcm_qa_nih-master/In/20180918GE/ + inflating: sourcedata/dcm_qa_nih-master/In/20180918GE/README-Study.txt + creating: sourcedata/dcm_qa_nih-master/In/20180918GE/mr_0004/ + inflating: sourcedata/dcm_qa_nih-master/In/20180918GE/mr_0004/README-Series.txt + inflating: sourcedata/dcm_qa_nih-master/In/20180918GE/mr_0004/axial_epi_fmri_interleaved_i_to_s-00001.dcm + # [...] output was manually truncated because it was really really long + inflating: sourcedata/dcm_qa_nih-master/Ref/EPI_PE=RL_5.nii + inflating: sourcedata/dcm_qa_nih-master/batch.sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ mv sourcedata/dcm_qa_nih-master sourcedata/dcm_qa_nih + ``` + + --- + +=== "GitHub" + + 1. Go to: [https://github.com/neurolabusc/dcm_qa_nih][dcm_qc_nih] and click on the + green button (Code) to **download ZIP**. + + ![](../assets/img/dcm_qa_nih_repo-dark.png#border#only-dark){ loading=lazy } + ![](../assets/img/dcm_qa_nih_repo-light.png#border#only-light){ loading=lazy } + + 1. Download the zipped file. + 2. Extract/unzip the zipped file to the **sourcedata** directory inside + your scaffold and rename the newly created directory **dcm_qa_nih**. + + --- + +You should now have a `dcm_qa_nih` directory nested in `sourcedata` with a bunch +of files and directories: + +=== "Command" + + ```sh + ls sourcedata/dcm_qa_nih + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ ls sourcedata/dcm_qa_nih/ + batch.sh In LICENSE README.md Ref + ``` + +## Building the configuration file + +The configuration file is the central element for dcm2bids to organize your data +into the [Brain Imaging Data Structure][bids-spec] standard. dcm2bids uses +information from the config file to determine which data in the protocol will be +converted, and how they will be renamed based on a set of rules. For this +reason, it is important to have a little understanding of the core BIDS +principles. The [BIDS Starter Kit][bids-starter-kit] a good place to start +[Tutorial on Annotating a BIDS dataset][bids-starter-kit-annot] from . + +As you will see below, the configuration file must be structured in the +Javascript Object Notation (JSON) format. + +!!! info "More info about the configuration file" + + The [How-to guide on creating a config file][config] provides useful + information about required and optional fields, and the inner working of a + config file. + +In short you need a configuration file because, for each acquisition, `dcm2niix` +creates an associated `.json` file, containing information from the dicom +header. These are known as **sidecar files**. These are the sidecars that +`dcm2bids` uses to filter the groups of acquisitions based on the configuration +file. + +You have to input the filters yourself, which is way easier to define when you +have access to an example of the sidecar files. + +You can generate all the sidecar files for an individual participant using the +[dcm2bids_helper](./use-main-commands.md#tools) command. + +### `dcm2bids_helper` command + +This command will convert the DICOM files it finds to NIfTI files and save them +inside a temporary directory for you to inspect and make some filters for the +config file. + +As usual the first command will be to request the help info. + +=== "Command" + + ```sh + dcm2bids_helper --help + ``` + +=== "Output" + + ```sh hl_lines="6 8" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids_helper --help + usage: dcm2bids_helper [-h] -d DICOM_DIR [DICOM_DIR ...] [-o OUTPUT_DIR] + + options: + -h, --help show this help message and exit + -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...] + DICOM files directory + -o OUTPUT_DIR, --output_dir OUTPUT_DIR + Output BIDS directory, Default: current directory + + Documentation at https://github.com/unfmontreal/Dcm2Bids + ``` + +To run the commands, you have to specify the `-d` option, namely the input +directory containing the DICOM files. The `-o` option is optional, defaulting to +moving the files inside a new `tmp_dcm2bids/helper` directory from where you run +the command, the current directory. + +!!! tip "Use one participant only" + + For this tutorial, it is easy since you there are only few data. However, in + project with many participants, it is recommended to use data from one + one session of one participant only by targeting their directory, otherwise you may be overwhelmed + by the number of files for nothing. + + In this tutorial, there are two folders with data, one with data coming from a + Siemens scanner (`20180918Si`), and one with data coming from GE (20180918GE). + The tutorial will use the data acquired on both scanners and Siemens scanner + located in `sourcedata/dcm_qa_nih/In/` and pretend it is one participant only. + +=== "Command" + + ```sh + dcm2bids_helper -d sourcedata/dcm_qa_nih/In/ + ``` + +=== "Output" + + ```sh hl_lines="4" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids_helper -d sourcedata/dcm_qa_nih/In/ + Example in: + /home/sam/dcm2bids-tutorial/bids_project/tmp_dcm2bids/helper + ``` + +### Finding what you need in **tmp_dcm2bids/helper** + +You should now able to see a list of compressed NIfTI files (`nii.gz`) with +their respective sidecar files (`.json`). You can tell which file goes with +which file based on their identical names, only with a + +=== "Command" + + ```sh + ls tmp_dcm2bids/helper + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ ls tmp_dcm2bids/helper/ + '003_In_EPI_PE=AP_20180918121230.json' + '003_In_EPI_PE=AP_20180918121230.nii.gz' + 004_In_DCM2NIIX_regression_test_20180918114023.json + 004_In_DCM2NIIX_regression_test_20180918114023.nii.gz + '004_In_EPI_PE=PA_20180918121230.json' + '004_In_EPI_PE=PA_20180918121230.nii.gz' + 005_In_DCM2NIIX_regression_test_20180918114023.json + 005_In_DCM2NIIX_regression_test_20180918114023.nii.gz + '005_In_EPI_PE=RL_20180918121230.json' + '005_In_EPI_PE=RL_20180918121230.nii.gz' + 006_In_DCM2NIIX_regression_test_20180918114023.json + 006_In_DCM2NIIX_regression_test_20180918114023.nii.gz + '006_In_EPI_PE=LR_20180918121230.json' + '006_In_EPI_PE=LR_20180918121230.nii.gz' + 007_In_DCM2NIIX_regression_test_20180918114023.json + 007_In_DCM2NIIX_regression_test_20180918114023.nii.gz + ``` + +As you can see, it is not necessarily easy to tell which scan files (`nii.gz`) +refer to which acquisitions from their names only. That is why you have to go +through their sidecar files to find unique identifiers for one acquisiton you +want to _BIDSify_. + +Go ahead and use any code editor, file viewer or your terminal to inspect the +sidecar files. + +Here, we compare two files that have similar names to highlight their +differences: + +=== "Command" + + ```sh + diff --side-by-side tmp_dcm2bids/helper/"003_In_EPI_PE=AP_20180918121230.json" tmp_dcm2bids/helper/"004_In_EPI_PE=PA_20180918121230.json" + ``` + + - Note than in this example, the filename are wrapped with quotes (`"`) as in + `"filename.ext"` because there is an `=` include in the name. You have to wrap + your filenames if they contains special characters, including spaces. To avoid + weird problems, we highly recommend to use alphanumeric only names when you + can choose the name of your MRI protocols and sequences. + +=== "Output" + + ```sh hl_lines="18 19 25 26 66 69 71 72" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ diff --side-by-side tmp_dcm2bids/helper/003_In_EPI_PE\=AP_20180918121230.json tmp_dcm2bids/helper/004_In_EPI_PE\=PA_20180918121230.json + { { + "Modality": "MR", "Modality": "MR", + "MagneticFieldStrength": 3, "MagneticFieldStrength": 3, + "ImagingFrequency": 123.204, "ImagingFrequency": 123.204, + "Manufacturer": "Siemens", "Manufacturer": "Siemens", + "ManufacturersModelName": "Skyra", "ManufacturersModelName": "Skyra", + "InstitutionName": "NIH", "InstitutionName": "NIH", + "InstitutionalDepartmentName": "FMRIF 3TD", "InstitutionalDepartmentName": "FMRIF 3TD", + "InstitutionAddress": "10 Center Drive Building 10 Ro "InstitutionAddress": "10 Center Drive Building 10 Ro + "DeviceSerialNumber": "45160", "DeviceSerialNumber": "45160", + "StationName": "AWP45160", "StationName": "AWP45160", + "BodyPartExamined": "BRAIN", "BodyPartExamined": "BRAIN", + "PatientPosition": "HFS", "PatientPosition": "HFS", + "ProcedureStepDescription": "FMRIF^QA", "ProcedureStepDescription": "FMRIF^QA", + "SoftwareVersions": "syngo MR E11", "SoftwareVersions": "syngo MR E11", + "MRAcquisitionType": "2D", "MRAcquisitionType": "2D", + "SeriesDescription": "EPI PE=AP", | "SeriesDescription": "EPI PE=PA", + "ProtocolName": "EPI PE=AP", | "ProtocolName": "EPI PE=PA", + "ScanningSequence": "EP", "ScanningSequence": "EP", + "SequenceVariant": "SK", "SequenceVariant": "SK", + "ScanOptions": "FS", "ScanOptions": "FS", + "SequenceName": "epfid2d1_72", "SequenceName": "epfid2d1_72", + "ImageType": ["ORIGINAL", "PRIMARY", "M", "ND", "ECHO "ImageType": ["ORIGINAL", "PRIMARY", "M", "ND", "ECHO + "SeriesNumber": 3, | "SeriesNumber": 4, + "AcquisitionTime": "12:24:58.102500", | "AcquisitionTime": "12:26:54.517500", + "AcquisitionNumber": 1, "AcquisitionNumber": 1, + "ImageComments": "None", "ImageComments": "None", + "SliceThickness": 3, "SliceThickness": 3, + "SpacingBetweenSlices": 12, "SpacingBetweenSlices": 12, + "SAR": 0.00556578, "SAR": 0.00556578, + "EchoTime": 0.05, "EchoTime": 0.05, + "RepetitionTime": 2.43537, "RepetitionTime": 2.43537, + "FlipAngle": 75, "FlipAngle": 75, + "PartialFourier": 1, "PartialFourier": 1, + "BaseResolution": 72, "BaseResolution": 72, + "ShimSetting": [ "ShimSetting": [ + -3717, -3717, + 15233, 15233, + -9833, -9833, + -207, -207, + -312, -312, + -110, -110, + 150, 150, + 226 ], 226], + "TxRefAmp": 316.97, "TxRefAmp": 316.97, + "PhaseResolution": 1, "PhaseResolution": 1, + "ReceiveCoilName": "Head_32", "ReceiveCoilName": "Head_32", + "ReceiveCoilActiveElements": "HEA;HEP", "ReceiveCoilActiveElements": "HEA;HEP", + "PulseSequenceDetails": "%CustomerSeq%\\nih_ep2d_bold "PulseSequenceDetails": "%CustomerSeq%\\nih_ep2d_bold + "CoilCombinationMethod": "Sum of Squares", "CoilCombinationMethod": "Sum of Squares", + "ConsistencyInfo": "N4_VE11C_LATEST_20160120", "ConsistencyInfo": "N4_VE11C_LATEST_20160120", + "MatrixCoilMode": "SENSE", "MatrixCoilMode": "SENSE", + "PercentPhaseFOV": 100, "PercentPhaseFOV": 100, + "PercentSampling": 100, "PercentSampling": 100, + "EchoTrainLength": 72, "EchoTrainLength": 72, + "PhaseEncodingSteps": 72, "PhaseEncodingSteps": 72, + "AcquisitionMatrixPE": 72, "AcquisitionMatrixPE": 72, + "ReconMatrixPE": 72, "ReconMatrixPE": 72, + "BandwidthPerPixelPhaseEncode": 27.778, "BandwidthPerPixelPhaseEncode": 27.778, + "EffectiveEchoSpacing": 0.000499996, "EffectiveEchoSpacing": 0.000499996, + "DerivedVendorReportedEchoSpacing": 0.000499996, "DerivedVendorReportedEchoSpacing": 0.000499996, + "TotalReadoutTime": 0.0354997, "TotalReadoutTime": 0.0354997, + "PixelBandwidth": 2315, "PixelBandwidth": 2315, + "DwellTime": 3e-06, "DwellTime": 3e-06, + "PhaseEncodingDirection": "j-", | "PhaseEncodingDirection": "j", + "SliceTiming": [ "SliceTiming": [ + 0, 0, + 1.45, | 1.4475, + 0.4825, 0.4825, + 1.9325, | 1.93, + 0.9675 ], | 0.965 ], + "ImageOrientationPatientDICOM": [ "ImageOrientationPatientDICOM": [ + 1, 1, + 0, 0, + 0, 0, + 0, 0, + 1, 1, + 0 ], 0 ], + "ImageOrientationText": "Tra", "ImageOrientationText": "Tra", + "InPlanePhaseEncodingDirectionDICOM": "COL", "InPlanePhaseEncodingDirectionDICOM": "COL", + "ConversionSoftware": "dcm2niix", "ConversionSoftware": "dcm2niix", + "ConversionSoftwareVersion": "v1.0.20211006" "ConversionSoftwareVersion": "v1.0.20211006" + } } + + ``` + +Again, when you will do it with your DICOMs, you will want to run +`dcm2bids_helper` on a typical session of one of your participants. You will +probably get more files than this example + +For the purpose of the tutorial, we will be interested in three specific +acquisitions, namely: + +1. `004_In_DCM2NIIX_regression_test_20180918114023` +2. `003_In_EPI_PE=AP_20180918121230` +3. `004_In_EPI_PE=PA_20180918121230` + +The first is an resting-state fMRI acquisiton whereas the second and third are +fieldmap EPI. + +### Setting up the configuration file + +Once you found the data you want to _BIDSify_, you can start setting up your +configuration file. The file name is arbritrary but for the readibility purpose, +you can name it `dcm2bids_config.json` like in the tutorial. You can create in +the `code/` directory. Use any code editor to create the file and add the +following content: + +```json +{ + "descriptions": [] +} +``` + +=== "Command" + + ```sh + nano code/dcm2bids_config.json + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ nano code/dcm2bids_config.json + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ + # No output is shown since nano is an interactive terminal-based editor + ``` + +#### Populating the config file + +To populate the config file, you need to inspect each sidecar files one at a +time and make sure there is a unique match for the acquisition you target. For +example, with the resting-state fMRI data +(`004_In_DCM2NIIX_regression_test_20180918114023`). You can inspect its sidecar +file and look for the `"SeriesDescription"` field for example. It is often a +good unique identifier. + +=== "Command" + + ```sh + cat code/dcm2bids_config.json + ``` + +=== "Output" + + ```sh hl_lines="17" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ cat tmp_dcm2bids/helper/004_In_DCM2NIIX_regression_test_20180918114023.json + { + "Modality": "MR", + "MagneticFieldStrength": 3, + "ImagingFrequency": 127.697, + "Manufacturer": "GE", + "PulseSequenceName": "epiRT", + "InternalPulseSequenceName": "EPI", + "ManufacturersModelName": "DISCOVERY MR750", + "InstitutionName": "NIH FMRIF", + "DeviceSerialNumber": "000301496MR3T6MR", + "StationName": "fmrif3tb", + "BodyPartExamined": "BRAIN", + "PatientPosition": "HFS", + "SoftwareVersions": "27\\LX\\MR Software release:DV26.0_R01_1725.a", + "MRAcquisitionType": "2D", + "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)", + "ProtocolName": "DCM2NIIX regression test", + "ScanningSequence": "EP\\GR", + "SequenceVariant": "SS", + "ScanOptions": "EPI_GEMS\\PFF", + "ImageType": ["ORIGINAL", "PRIMARY", "EPI", "NONE"], + "SeriesNumber": 4, + "AcquisitionTime": "11:48:15.000000", + "AcquisitionNumber": 1, + "SliceThickness": 3, + "SpacingBetweenSlices": 5, + "SAR": 0.0166392, + "EchoTime": 0.03, + "RepetitionTime": 5, + "FlipAngle": 60, + "PhaseEncodingPolarityGE": "Unflipped", + "CoilString": "32Ch Head", + "PercentPhaseFOV": 100, + "PercentSampling": 100, + "AcquisitionMatrixPE": 64, + "ReconMatrixPE": 64, + "EffectiveEchoSpacing": 0.000388, + "TotalReadoutTime": 0.024444, + "PixelBandwidth": 7812.5, + "PhaseEncodingDirection": "j-", + "SliceTiming": [ + 0, + 2.66667, + 0.333333, + 3, + 0.666667, + 3.33333, + 1, + 3.66667, + 1.33333, + 4, + 1.66667, + 4.33333, + 2, + 4.66667, + 2.33333 ], + "ImageOrientationPatientDICOM": [ + 1, + -0, + 0, + -0, + 1, + 0 ], + "InPlanePhaseEncodingDirectionDICOM": "COL", + "ConversionSoftware": "dcm2niix", + "ConversionSoftwareVersion": "v1.0.20211006" + } + ``` + +To match the `"SeriesDescription"` field, a pattern like `Axial EPI-FMRI*` could +match it. However, we need to make sure we will match only one acquisition. You +can test it by looking manually at inside all sidecar files but it is now +recommend. It is rather trivial for the computer to look in all the .json files +for you with the `grep` command: + +=== "Command" + + ```sh + grep "Axial EPI-FMRI*" tmp_dcm2bids/helper/*.json + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ grep "Axial EPI-FMRI*" tmp_dcm2bids/helper/*.json + tmp_dcm2bids/helper/004_In_DCM2NIIX_regression_test_20180918114023.json: "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)", + tmp_dcm2bids/helper/005_In_DCM2NIIX_regression_test_20180918114023.json: "SeriesDescription": "Axial EPI-FMRI (Sequential I to S)", + tmp_dcm2bids/helper/006_In_DCM2NIIX_regression_test_20180918114023.json: "SeriesDescription": "Axial EPI-FMRI (Interleaved S to I)", + tmp_dcm2bids/helper/007_In_DCM2NIIX_regression_test_20180918114023.json: "SeriesDescription": "Axial EPI-FMRI (Sequential S to I)", + ``` + +Unfortunately, this criteria is not enough and it could match other 4 files. + +In this situation, you can add another criteria to match the specific +acquisition. Which one do you think would be more appropriate? Go back to the +content of the fMRI sidecar file and find a another criteria that, in +combination with the `"SeriesDescription"`, will uniquely match the fMRI data. + +Right, maybe instead of trying to look for another field, you could simply +extend the criteria for the `"SeriesDescription"`. How many files does it match +if you extend it to the full value (`Axial EPI-FMRI (Interleaved I to S)`? + +=== "Command" + + ```sh + grep "Axial EPI-FMRI (Interleaved I to S)*" tmp_dcm2bids/helper/*.json + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ grep "Axial EPI-FMRI (Interleaved I to S)*" tmp_dcm2bids/helper/*.json + tmp_dcm2bids/helper/004_In_DCM2NIIX_regression_test_20180918114023.json: "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)", + ``` + +:tada:, there is only one match! It means you can now update your configuration +file by adding a couple of necessary fields for which you can find a description +in [How to create a config file][config]. Since it is a resting-stage fMRI +acquisition, you want to specify it like this then make dcm2bids change your +task name: + +```json hl_lines="3-10" +{ + "descriptions": [ + { + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", + "criteria": { + "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)*" + "sidecarChanges": { + "TaskName": "rest" + } + } + } + ] +} +``` + +=== "Command" + + ```sh + nano code/dcm2bids_config.json + ``` + +=== "Output" + + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ nano code/dcm2bids_config.json + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ cat code/dcm2bids_config.json + { + "descriptions": [ + { + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", + "criteria": { + "SeriesDescription": "*Axial EPI-FMRI (Interleaved I to S)*" + }, + "sidecarChanges": { + "TaskName": "rest" + } + } + ] + } + ``` + +!!! warning "Avoid using filename as criteria" + + While you can take file names to match as criteria, we do not recommend this + as different versions of dcm2niix can lead to different file names (Refer to + the [release notes of version 17-March-2021 (v1.0.20210317)][dcm2niix-release] + of dcmniix to now more, especially the [GE file naming behavior changes (%p protocol name and %d description) section](https://github.com/rordenlab/dcm2niix/issues/476). + +Moving to the two fieldmaps, if you inspect their sidecar files (the same ones +that were compared in the +[dcm2bids_helper section](#finding-what-you-need-in-tmpdcm2bidshelper)), you can +see a pattern of `"EPI PE=AP"` or `"EPI PE=PA"` in the `SeriesDescription` once +again. Is it enough to match only the correct acquisition? + +You can test it, of course! + +=== "Command" + + ```sh + grep "EPI PE=AP" tmp_dcm2bids/helper/*.json + grep "EPI PE=PA" tmp_dcm2bids/helper/*.json + ``` + +=== "Output" + + There are two matches per pattern but they come from the same file, so it is okay. + ```sh + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ grep "EPI PE=AP" tmp_dcm2bids/helper/*.json + tmp_dcm2bids/helper/003_In_EPI_PE=AP_20180918121230.json: "SeriesDescription": "EPI PE=AP", + tmp_dcm2bids/helper/003_In_EPI_PE=AP_20180918121230.json: "ProtocolName": "EPI PE=AP", + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ grep "EPI PE=PA" tmp_dcm2bids/helper/*.json + tmp_dcm2bids/helper/004_In_EPI_PE=PA_20180918121230.json: "SeriesDescription": "EPI PE=PA", + tmp_dcm2bids/helper/004_In_EPI_PE=PA_20180918121230.json: "ProtocolName": "EPI PE=PA", + + ``` + +Once you are sure of you matching criteria, you can update your configuration +file with the appropriate info. + +```json hl_lines="21 30" +{ + "descriptions": [ + { + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", + "criteria": { + "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)*" + }, + "sidecarChanges": { + "TaskName": "rest" + } + }, + { + "dataType": "fmap", + "modalityLabel": "epi", + "customLabels": "dir-AP", + "criteria": { + "SeriesDescription": "EPI PE=AP*" + }, + "intendedFor": 0 + }, + { + "dataType": "fmap", + "modalityLabel": "epi", + "customLabels": "dir-PA", + "criteria": { + "SeriesDescription": "EPI PE=PA*" + }, + "intendedFor": 0 + } + ] +} +``` + +For fieldmaps, you need to add an `"intendedFor"` field to show that these +fieldmaps should be used with your fMRI acquisition. Have a look at the +explanation of [intendedFor](/docs/3-configuration/#intendedfor) in the +documentation or in the [BIDS specification][bids-fmap]. + +!!! tip "Use an online JSON validator" + + Editing JSON file is prone to errors such as misplacing or forgetting a comma or + not having matched opening and closing `[]` or `{}`. JSON linters are useful to + validate that we did enter all information successfully. You can find these + tools online, for example . + +Now that you have a configuration file ready, it is time to finally run +`dcm2bids`. + +## Running `dcm2bids` + +By now, you should be used to getting the `--help` information before running a +command. + +=== "Command" + + ```sh + dcm2bids --help + ``` + +=== "Output" + + ```sh hl_lines="2-3" + (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids --help + usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c CONFIG [-o OUTPUT_DIR] [--forceDcm2niix] [--clobber] + [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] + + Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure + dcm2bids 2.1.6 + + options: + -h, --help show this help message and exit + -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...] + DICOM directory(ies) + -p PARTICIPANT, --participant PARTICIPANT + Participant ID + -s SESSION, --session SESSION + Session ID + -c CONFIG, --config CONFIG + JSON configuration file (see example/config.json) + -o OUTPUT_DIR, --output_dir OUTPUT_DIR + Output BIDS directory, Default: current directory (/home/sam/dcm2bids-tutorial/bids_project) + --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists + --clobber Overwrite output if it exists + -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + Set logging level + -a, --anonymizer This option no longer exists from the script in this release. See:https://github.com/unfmontreal/Dcm2Bids/blob/master/README.md#defaceTpl + + Documentation at https://github.com/unfmontreal/Dcm2Bids + + ``` + +As you can see, to run the `dcm2bids` command, you have to specify at least 3 +required options with their argument. + +```sh +dcm2bids -d path/to/source/data -p subject_id -c path/to/config/file.json +``` + +`dcm2bids` will create a directory which will be named after the argument +specified for `-p`, and put the _BIDSified_ data in it. + +For the tutorial, pretend that the subject_id is simply `ID01`. + +Note that if you don't specify the `-o` option, your current directory will be +populated with the `sub-