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[phys2bidscoin]            # Use this when you want to convert physiological data with the phys2bidscoin plugin -- EXPERIMENTAL!
$ 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,spec2nii2bids]     # Use this to install two extra packages of interest
$ 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 --upgrade 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

Tip

On certain (Linux) systems you may get an error message saying: ‘Could not load the Qt platform plugin “xcb” in “” even though it was found’. This may be solved by downgrading your PyQt5 library, e.g. by running:

pip uninstall pyqt5

pip install pyqt5==5.14

Updating BIDScoin

Run your pip install command as before with the additional --upgrade option, e.g.:

$ pip install --upgrade bidscoin

Caution

  • The bidsmaps are not garanteed to be compatible between different BIDScoin versions

  • After a succesful 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 command to run the dcm2niix executable is set correctly in the Options section in your bidsmap. This can be done in two ways:

  1. 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 -t for the fullpath location on your system.

  2. 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

Note that, as a test, dcm2niix inquires the internet for available updates. On some (e.g. Ubuntu) systems that may generate an (innocent) error because the curl aplication may not be installed (see also the singularity definition file). Please consult the documentation for your operating system if you like to install curl.

Using a singularity container

An alternative for installing Python, BIDScoin and it’s dependencies yourself is to execute BIDScoin commands using a Singularity image. Read Singularity documentation for installation and usage instructions.

The current image includes:

  • Debian stable,

  • the latest version of dcm2niix,

  • the latest stable release of BIDScoin and its spec2nii2bids and phys2bidscoin plugins.

Dependencies:

  • Debian (or Debian-like, e.g., Ubuntu) host system,

  • debootstrap package.

Building the image

Execute the following command to build the BIDScoin image.

$ sudo singularity build bidscoin.sif singularity.def

Run BIDScoin tools from the image

Execute BIDScoin tool using the following command:

$ singularity 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.

If your data doesn’t reside in home folder, add --bind Singularity argument which maps a folder from the host system to one inside the Singularity container.

$ singularity exec bidscoin.sif --bind <host_dir>:<container_dir> <bidscoin_tool> <bidscoin_tool_args>

For example:

$ singularity exec --bind /my/data:/mnt bidscoin.sif bidscoiner /my/data/source /my/data/bids

Tip

Since there is no fixed entry point to the container, you can also use it to execute dcm2niix.

Latest develop release

To install the latest develop realease of BIDScoin, substitute

pip3 install bidscoin

with

pip3 install --upgrade git+https://github.com/Donders-Institute/bidscoin

in the definition singularity.def file.

Speed up building the image

To speed up building the Singularity image, you can change the apt servers to download the packages from a location closer to you. For example, add the following line as the first command in the %post section of singularity.def file to download the packages from Austria (at).

echo 'deb http://ftp.at.debian.org/debian stable main' > /etc/apt/sources.list

Troubleshooting

The image didn’t work after copying it to a CentOS 7 host system. The problem was kernel version older than 3.15. A working fix is to add the following line at the end of %post section of singularity.def file.

strip --remove-section=.note.ABI-tag /usr/lib/x86_64-linux-gnu/libQt5Core.so.5

The fix comes from these resources: