Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document new features + docker #311

Merged
merged 19 commits into from
Jul 26, 2024
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/publish_doc.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ on:
push:
branches:
- master
- dev
tags:
- '[0-9]+.[0-9]+.[0-9]+'
release:
Expand Down Expand Up @@ -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"
Expand Down
200 changes: 200 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
26 changes: 0 additions & 26 deletions containers/Dockerfile

This file was deleted.

2 changes: 0 additions & 2 deletions containers/singularity.def

This file was deleted.

4 changes: 2 additions & 2 deletions dcm2bids/version.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
37 changes: 19 additions & 18 deletions docs/get-started/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

=== "Apptainer/Singularity"

`singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest`
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

## Installing binary executables

From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
Expand Down Expand Up @@ -104,7 +117,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
Expand All @@ -129,7 +142,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.

Expand Down Expand Up @@ -163,7 +176,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
Expand Down Expand Up @@ -260,7 +273,7 @@ name: dcm2bids
channels:
- conda-forge
dependencies:
- python>=3.7
- python>=3.8
- dcm2niix
- dcm2bids
```
Expand All @@ -277,7 +290,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.

Expand Down Expand Up @@ -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

Expand All @@ -384,7 +385,7 @@ containers:
channels:
- conda-forge
dependencies:
- python>=3.7
- python>=3.8
- dcm2niix
- dcm2bids

Expand Down
125 changes: 125 additions & 0 deletions docs/how-to/container.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# dcm2bids with Docker and Apptainer / Singularity

We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator. You can find it on [Docker Hub](https://hub.docker.com/r/unfmontreal/dcm2bids).

You can install it using [Docker](https://www.docker.com/get-started) or [Apptainer/Singularity](https://www.apptainer.org).

## Prerequisites

Before you begin, make sure you have at least one of the following installed:

- Docker: [Download and install Docker](https://www.docker.com/get-started)
- Apptainer, formerly known as Singularity : [Download and install Apptainer](https://apptainer.org/docs/admin/main/installation.html)

!!! note
If you are using a HPC cluster, Apptainer is the recommended choice and is probably installed on your system. Simply load the module (e.g.,
`module load apptainer`) and use the `apptainer` command,

## Step 1: Pull the dcm2bids container

To start, you can either pull the dcm2bids image from the Docker Hub repository or [build it from the Dockerfile in the repository](https://github.com/UNFmontreal/Dcm2Bids/blob/dev/Dockerfile).:

=== "Docker"

```
docker pull unfmontreal/dcm2bids:latest
SamGuay marked this conversation as resolved.
Show resolved Hide resolved
```

=== "Apptainer/Singularity"

```
apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:latest
SamGuay marked this conversation as resolved.
Show resolved Hide resolved
```

## 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
SamGuay marked this conversation as resolved.
Show resolved Hide resolved
```

## 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.
arnaudbore marked this conversation as resolved.
Show resolved Hide resolved

=== "Docker"

```
docker run --rm -it \
--entrypoint /venv/bin/dcm2bids_scaffold \
-v /path/to/output-dir:/output \
unfmontreal/dcm2bids:latest -o /output/new_bids_dataset
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

=== "Apptainer/Singularity"

```
singularity exec \
-B /path/to/output-dir:/output \
dcm2bids.sif dcm2bids_scaffold -o /output/new_bids_dataset
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved


## 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:
arnaudbore marked this conversation as resolved.
Show resolved Hide resolved

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`).
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

=== "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
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

=== "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
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

## Step 5: Run `dcm2bids`

You can use `run` as in Step 2 or use `exec dcm2bids` to run `dcm2bids` with the appropriate arguments and options. You need to bind the respective volumes.

You can put input data in the same parent directory as the output directory, or you can specify the input data directory as a separate volume. You must also specify the path to the configuration file. If you use the scaffolded dataset, the config file is usually in the `code/` directory.

You can also [deface your data](use-advanced-commands.md#post_op) and [validate your BIDS data](use-advanced-commands.md#-bids_validate) using the `--bids_validate` flag.

=== "Docker"

```
docker run --rm -it \
-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
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved

=== "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
```
SamGuay marked this conversation as resolved.
Show resolved Hide resolved
11 changes: 8 additions & 3 deletions docs/how-to/create-config-file.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.
arnaudbore marked this conversation as resolved.
Show resolved Hide resolved

## sidecar_changes, id and IntendedFor

Optional field to change or add information in a sidecar.
Expand Down
2 changes: 2 additions & 0 deletions docs/how-to/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
20 changes: 17 additions & 3 deletions docs/how-to/use-advanced-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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.

Expand All @@ -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": []`
Expand Down Expand Up @@ -290,6 +297,13 @@ 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.

### `--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
Expand Down
Loading
Loading