Installation⚓︎
There are several ways to install dcm2bids.
Installing binary executables⚓︎
From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux (debian-based and rhel-based).
They can easily been downloaded from the release page.
Once downloaded, you should be able to extract the dcm2bids
,
dcm2bids_scaffold
, and dcm2bids_helper
files and use them with the full
path.
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
|
Installing using pip or conda⚓︎
Before you can use dcm2bids, you will need to get it installed. This page guides you through a minimal, typical dcm2bids installation workflow that is sufficient to complete all dcm2bids tasks.
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.
You just want the installation command?
You can use the binaries provided with each release (starting with dcm2bids>=3)
If you are used to installing packages, you can get it from PyPI or conda:
pip install dcm2bids
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.
1 2 |
|
1 2 3 4 |
|
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, 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.
Should I install Anaconda or Miniconda?
If you unsure what to install read this section describing the differences between Anaconda and Miniconda to help you choose.
dcm2niix⚓︎
dcm2niix can also be installed in a variety of ways as seen on the main page of the software.
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 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 section.
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 or, for those who have it installed, Anaconda. Note that you don't need to use specifically them to use dcm2bids, but it will make your life easier.
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
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.
I already created an environment for my project, what do I do?
You can update your environment either by:
- installing dcm2bids while your environment is active like any package; or
- adding dcm2bids to the dependencies and updating your environment
Here's an example with conda after updating an environment.yml
file:
1 |
|
Install dcm2bids⚓︎
From now on, it is assumed that conda (or 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.
If you installed Anaconda and want to use the graphical user interface (GUI), you can follow the steps as demonstrated below and only read the steps until the end of the installation guide.
Create your environment with the Anaconda Navigator GUI
- Open Anaconda Navigator
- Click on Environments, then the + button at the bottom
- Enter the name of the environment, it can be anything. You can call it dcm2bids then select Python
- Click on the new dcm2bids environment, then on Channels
- If you only see defaults, click on Add... then enter conda-forge then click on Update channels
- You now need to add the two main software, so you need to search for them in the top right corner. You should see them appear as soon as you right dcm2. You can select both at the same time.
- If you don't seem them, you probabble need to select All channels instead of Installed.
- It will ask you to install a bunch of packages, Apply.
- You environment should now be ready, click on the green circle with the white arrow to start the environment. A terminal window should open.
- You should see the name of your environment (dcm2bids) to the left. You can now test that dcm2bids works.
We could install all the software one by one using a series of command:
1 2 |
|
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.
1 2 3 4 5 6 7 |
|
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. - 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 asnilearn
,pandas
, and especially aspip
since you don't want to use the pip outside of your environment Note that we specifypython>=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!
Create conda environment + install dcm2bids⚓︎
Open a terminal and go in the directory where you put the environment.yml
run
this command:
1 |
|
If the execution was successful, you should see a message similar to:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Activate environment⚓︎
Last step is to make sure you can activate1 your environment by running the command:
1 |
|
Remember that dcm2bids here refer to the name given specified in the
environment.yml
.
1 2 |
|
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
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
|
Voilà, you are ready to use dcm2bids or at least move onto the tutorial!!
Containers⚓︎
We also provide a container image that includes both dcm2niix and dcm2bids which you can install using Docker or Apptainer/Singularity.
docker pull unfmontreal/dcm2bids:latest
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 but it is also possible to use other software, including containers:
-
Create an
environment.yml
file with dependencies- Content:
1 2 3 4 5 6 7
name: dcm2bids channels: - conda-forge dependencies: - python>=3.7 - dcm2niix - dcm2bids
- Content:
-
Create conda environment
-
conda env create --file environment.yml
-
- Activate conda environment
-
conda activate dcm2bids
-
- Verify a dcm2bids command
-
dcm2bids --help
-
- Consult how-to guides or follow the tutorial
-
To get out of a conda environment, you have to deactivate it with the
conda deactivate
command. ↩
Created: 2022-04-17