Installation
BIDScoin can be installed directly on your operating system, or in a so-called container. Direct installation is arguably simpler and lighter, but containerized installations are better guaranteed to always work and be reproducible. Below you find instructions for direct installation, followed by instructions for installation in a container. Alternatively, if you like to use a container but don’t like the complexity of its overhead, you can install Neurodesk and use its pre-installed transparent BIDScoin container without needing to know anything about containers.
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 (important tip: you probably want or need to create and activate a virtual / conda Python environment first and then):
$ pip install bidscoin # Use this to install the BIDScoin-framework only and independently install the software dependencies of the plugin(s) (such as dcm2niix)
$ pip install bidscoin[dcm2niix2bids] # Use this when you want to convert conventional MR imaging data with the dcm2niix2bids plugin and would like to have dcm2niix pip-installed
$ 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 (but see the Apptainer file for doing a minimal install)
$ pip install bidscoin[deface,spec2nii2bids] # Use this when you want to deface anatomical MRI scans and convert MRS data with the spec2nii2bids 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, e.g. like this:
$ pip install git+https://github.com/Donders-Institute/bidscoin # The BIDScoin-framework only
$ pip install bidscoin[dcm2niix2bids]@git+https://github.com/Donders-Institute/bidscoin # The BIDScoin-framework + dcm2niix2bids plugin
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[dcm2niix2bids]
If you are installing BIDScoin on an older system and you are getting Qt6 errors, you can try to install a +qt5 build, e.g. for version 4.3.2:
$ pip install bidscoin[dcm2niix2bids]@git+https://github.com/Donders-Institute/bidscoin@v4.3.2+qt5
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
Dcm2niix installation
The default ‘dcm2niix2bids’ plugin relies on an external application named dcm2niix for converting DICOM and PAR/REC source data to NIfTI. To use the plugin you must pip-install dcm2niix when installing BIDScoin or install it yourself (e.g. when pip-installing dcm2niix does not work for your platform) as explained in the dcm2niix installation 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 (for instance when you want to use the Linux module system or fixate the software version), 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 your
[home]/.bidscoin/[version]/templatesfolder (see the output ofbidscoin -pfor 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 current Apptainer image includes:
Debian stable,
The latest stable release (v4.3.2+qt5) of BIDScoin
The latest versions of dcm2niix, pydeface, spec2nii
This image does not include 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 pull a BIDScoin Docker image and convert it into an Apptainer image using:
$ sudo apptainer build bidscoin.sif docker://marcelzwiers/bidscoin:<version>
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 does not 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 your 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 does not 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 stable,
The latest stable release of BIDScoin (v4.3.2+qt5)
The latest versions of dcm2niix, pydeface, spec2nii and some FSL tools
Likewise, the current image does not include 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 .
Alternatively, you can pull a pre-build image from Docker Hub
$ sudo docker pull marcelzwiers/bidscoin:<version>
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 built the image from the Dockerfile
$ docker run --rm -v <bind_mount> marcelzwiers/bidscoin:<version> <bidscoin_tool> <bidscoin_tool_args> # If you pulled the image from Docker Hub
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).