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