Installation¶
Python installation¶
BIDScoin is a Python 3 package and can be installed on Linux, MS Windows and on OS-X computers, as long as a Python interpreter (v3.8 or higher) is available on the system. On Linux and OS-X this is usually already the case, but MS Windows users may need to first install Python themselves. See e.g. this Python 3 distribution for instructions.
BIDScoin installation¶
To install BIDScoin on your system run one of the following commands in your command-line interface / shell (tip: you may want or need to install bidscoin in a virtual / conda Python environment):
$ pip install bidscoin # Use this when you want to convert conventional MR imaging data with the dcm2niix2bids plugin
$ pip install bidscoin[spec2nii2bids] # Use this when you want to convert MR spectroscopy data with the spec2nii2bids plugin
$ pip install bidscoin[deface] # Use this when you want to deface anatomical MRI scans. NB: Requires FSL to be installed on your system
$ pip install bidscoin[deface,pet2bids] # Use this when you want to deface anatomical MRI scans and convert PET data with the pet2bids plugin
$ pip install bidscoin[all] # Use this to install all extra packages
These install commands can be run independently and will give you the latest stable release of BIDScoin and its plugins. Alternatively, if you need to use the very latest (development / unstable) version of the software, you can also install BIDScoin directly from the github source code repository:
$ pip install git+https://github.com/Donders-Institute/bidscoin
If you do not have git (or any other version control system) installed you can download and unzip the code yourself in a folder named e.g. ‘bidscoin’ and run:
$ pip install ./bidscoin
Updating BIDScoin¶
Run your pip install command as before with the additional --upgrade
or --force-reinstall
option, e.g.:
$ pip install --upgrade bidscoin # The latest stable release
$ pip install --force-reinstall git+https://github.com/Donders-Institute/bidscoin # The latest code (add ``--no-deps`` to only upgrade the bidscoin package)
Caution
The bidsmaps are not guaranteed to be compatible between different BIDScoin versions
After a successful BIDScoin installation or upgrade, it may be needed to (re)do any adjustments that were done on your template bidsmap (so make a back-up of it before you upgrade)
Dcm2niix installation¶
Unfortunately the pip installer can only install Python software and the default ‘dcm2niix2bids’ plugin relies on an external application named dcm2niix to convert DICOM and PAR/REC source data to NIfTI. To make use of the dcm2niix2bids plugin you should therefore download and install dcm2niix yourself according to the instructions. When done, make sure that the dcm2niix executable is on your user or system path (Windows users can add the path permanently, e.g. by running: setx path "%path%;C:\Program Files\dcm2niix"
). Otherwise, make sure that the command to run the dcm2niix executable (exactly as if you would run it yourself in your command terminal) is set correctly in the Options section in your bidsmap. This can be done in two ways:
Open your template bidsmap with a text editor and adjust the settings as needed. The default template bidsmap is located in the [path_to_bidscoin]/heuristics subfolder – see the output of
bidscoin -p
for the fullpath location on your system.Go to the Options tab the first time the BIDScoin GUI is launched and adjust the settings as needed. Then click the [Set as default] button to save the settings to your default template bidsmap.
Testing BIDScoin¶
You can run the ‘bidscoin’ utility to test the installation of your BIDScoin installation and settings:
$ bidscoin -t # Test with the default template bidsmap
$ bidscoin -t my_template_bidsmap # Test with your custom template bidsmap
See also the Troubleshooting guide for more information on potential installation issues.
Using an Apptainer (Singularity) container¶
An alternative for installing Python, BIDScoin and it’s dependencies yourself is to execute BIDScoin commands using an Apptainer container. Executing BIDScoin commands via a container is less simple than running them directly on your host computer, read the official documentation for installation and usage instructions. NB: “Singularity” has been rebranded as “Apptainer”, so Singularity users should replace apptainer
for singularity
in the commands given below.
The Apptainer current image includes:
Debian Linux (see https://hub.docker.com/_/python)
the latest version of dcm2niix
the latest stable release of BIDScoin and its plugins
The current image does not include this (non-free) software needed for some bidsapps:
FSL (needed for
deface
andslicereport
)Freesurfer/synthstrip (needed for
skullstrip
)
Building the container image¶
Download the Apptainer definition file and execute the following command to build a BIDScoin container image:
$ sudo apptainer build bidscoin.sif apptainer.def
Alternatively, you can first build a Docker image (see instructions in the section below), save it to e.g. bidscoin.tar and then convert it into a Apptainer image using:
$ sudo apptainer build bidscoin.sif bidscoin.tar
Run BIDScoin tools in the container¶
You can use the following command syntax to execute BIDScoin tools in the container:
$ apptainer exec bidscoin.sif <bidscoin_tool> <bidscoin_tool_args>
Where <bidscoin_tool>
is a BIDScoin tool (e.g., bidsmapper
, bidscoiner
, dicomsort
) and <bidscoin_tool_args>
are the tool’s arguments. So for instance, if you have source data in myhome/data/raw
, instead of running bidsmapper data/raw data/bids
and then bidsmapper data/raw data/bids
from your home directory, you now execute:
$ xhost +
$ apptainer exec bidscoin.sif bidsmapper data/raw data/bids
$ xhost -
$ apptainer exec bidscoin.sif bidscoiner data/raw data/bids
The xhost + command allows Apptainer to open a graphical display on your computer and normally needs to be run once before launching a GUI application, i.e. is needed for running the bidseditor.
If your data doesn’t reside in your home folder, then you need to add a --bind <host_dir>:<container_dir>
Apptainer argument which maps a folder from the host system to a folder inside the Apptainer container. So if yuor data is in /myproject/raw
, you run:
$ apptainer exec bidscoin.sif --bind /myproject <bidscoin_tool> <bidscoin_tool_args>
See the documentation for usage and setting environment variables to automatically bind your root paths for all containers.
Using a Docker container¶
If the Apptainer container is not working for you, it is also possible to use a Docker container. The Docker versus Apptainer image and container usage are very similar, and both have their pros and cons. A fundamental argument for using Apptainer is that it doesn’t require root permission (admin rights), whereas a fundamental argument for using Docker is that it is not limited to Linux hosts.
The current Docker image includes the same as the Apptainer image:
Debian Linux (see https://hub.docker.com/_/python)
the latest version of dcm2niix
the latest stable release of BIDScoin and its plugins
Likewise, the current image does not include this (non-free) software needed for some bidsapps:
FSL (needed for
deface
andslicereport
)Freesurfer/synthstrip (needed for
skullstrip
)
Building the container image¶
Download the Dockerfile and execute the following command to build a BIDScoin container image:
$ sudo docker build -t bidscoin .
Run BIDScoin tools in the container¶
Executing BIDScoin commands via Docker is less simple than via Apptainer (and surely less simple than running them directly on your host computer). For instance, it is typically needed to bind-mount your data folder(s) in the container and, for the bidseditor, to bind-mount an x-server socket to display the GUI in your host computer. The syntax to run dockerized bidscoin tools is:
$ docker run --rm -v <bind_mount> bidscoin <bidscoin_tool> <bidscoin_tool_args>
If you have source data in /my/data/raw
, instead of running bidsmapper /my/data/raw /my/data/bids
and then bidsmapper /my/data/raw /my/data/bids
, you now execute for instance:
$ xhost +
$ sudo docker run --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /my/data:/mnt bidscoin bidsmapper /my/data/raw /my/data/bids
$ xhost -
$ sudo docker run --rm -v /my/data:/my/data bidscoin bidscoiner /my/data/raw /my/data/bids
As for Apptainer, the xhost + is normally needed to be launching a GUI application, but a few more arguments are now required, i.e. -e
for setting the display number and -v
for binding the data volume and for binding the x-server socket (see the documentation for usage and configuring bind propagation).