Installation

There are three ways you can use pyradiomics: 1. Install via pip 2. Install from source 3. Use 3D Slicer Radiomics extension 4. Use pyradiomics Docker

1. Install via pip

Pre-built binaries are available on PyPi for installation via pip. For the python versions mentioned below, wheels are automatically generated for each release of PyRadiomics, allowing you to install pyradiomics without having to compile anything. For other python versions, a source distribution is also available, but this requires compiling the C extensions.

  • Ensure that you have python installed on your machine, version 3.5, 3.6 or 3.7 (64-bits).

  • Install PyRadiomics:

    python -m pip install pyradiomics
    

2. Install via conda

Besides pre-built binaries for PyPi, PyRadiomics is also available on conda cloud. To install PyRadiomics on Conda, run:

conda install -c radiomics pyradiomics

3. Install from source

PyRadiomics can also be installed from source code. This allows for the bleeding edge version, but does require you to have a compiler set up for python, as PyRadiomics comes with C extensions for the calculation of texture matrices and some shape features.

  • Ensure you have the version control system git installed on your machine.

  • Ensure that you have python installed on your machine, at least version 3.5 (64-bits).

  • Clone the repository:

    git clone git://github.com/Radiomics/pyradiomics
    
  • For unix like systems (MacOSX, linux):

    cd pyradiomics
    python -m pip install -r requirements.txt
    python setup.py install
    
    • To use your build for interactive use and development:

      python setup.py build_ext --inplace
      
    • If you don’t have sudo/admin rights on your machine, you need to locally install numpy, nose, tqdm, PyWavelets, SimpleITK (specified in requirements.txt). In a bash shell:

      pip install --user --upgrade pip
      export PATH=$HOME/.local/bin:$PATH
      pip install --user -r requirements.txt
      export PYTHONPATH=$HOME/.local/lib64/python2.7/site-packages
      
  • For Windows:

    cd pyradiomics
    python -m pip install -r requirements.txt
    python setup.py install
    
  • If the installation fails, check out the Frequently Asked Questions. If your error is not listed there, contact us by creating an issue on the PyRadiomics Github.

3. Use 3D Slicer Radiomics extension

3D Slicer is a free open source research platform for medical image computing. Learn more and download 3D Slicer binary for your platform here: http://slicer.org.

Once installed, you can use 3D Slicer ExtensionManager to install Radiomics extension, which provides a graphical user interface to the pyradiomics library. The advantage of using pyradiomics from 3D Slicer is that you can view images and segmentations, you can import existing segmentations and confirm their quality, or you can use the variety of tools in 3D Slicer to automate your segmentation tasks.

More detailed instructions about installing 3D Slicer Radiomics extension are available here: https://github.com/Radiomics/SlicerRadiomics

4. Use pyradiomics Docker

This approach may be preferred if you are interested in using pyradiomics from the command line, but have difficulties installing the library on your system.

First, you will need to install Docker on your system, if it is not installed already. You can follow the instructions below to do this.

Once Docker is installed, you can issue docker pull radiomics/pyradiomics:CLI command in the shell to download the pyradiomics Docker image. After that you can invoke pyradiomics tool as follows:

docker run radiomics/pyradiomics:CLI --help

Docker containers cannot directly access the filesystem of the host. In order to pass files as arguments to pyradiomics and to access files that converters create, an extra step is required to specify which directories will be used for file exchange using the -v argument:

-v <HOST_DIR>:<CONTAINER_DIR>

The argument above will make the HOST_DIR path available within the container at CONTAINER_DIR location. The files that will be read or written by the converter run from the docker container should be referred to via the CONTAINER_DIR path.

Setting up Docker

Docker (http://docker.com) is a project that automates deployment of applications inside software containers. Docker application is defined by _images_ that contain all of the components and steps needed to initialize the application instance. A _container_ is a running instance of the image. We provide an image that contains the compiled pyradiomics library in the docker/pyradiomics:CLI image. By using pyradiomics Docker container you can use pyradiomics on any operating system that supports Docker without having to compile pyradiomics. All you need to do is install Docker on your system, and download the pyradiomics Docker image.

You will first need to install Docker on your system following these instructions. Docker is available for Mac, Windows and Linux. For the most part Docker installation is straightforward, but some extra steps need to be taken on Windows as discussed below.

If you use Docker on Windows …

Note the system requirements:

  • you will need to have Windows 10 Pro or above
  • you will need to enable Hyper-V package (Docker will prompt you)
  • you will need to enable virtualization; read this to learn how to check if it is enabled, and if it is not - here is one guide that may help you do that, but it assumes you can access your BIOS settings

IMPORTANT: You will also need to share the drive you will be using to communicate data to and from Docker image in Docker Settings as shown in the screenshot below.

Most likely you will experience the display of an error message similar to the one shown below:

C:\Program Files\Docker\Docker\Resources\bin\docker.exe: Error response from daemon:
C: drive is not shared. Please share it in Docker for Windows Settings.
See 'C:\Program Files\Docker\Docker\Resources\bin\docker.exe run --help'.

If you have this error, make sure that the drive, where the HOST_DIR is located, is shared:

  1. right click onto the Docker task bar icon and choose “Settings”
  2. choose “Shared Drives” from the left menu (a list of drives that are available to share will be displayed)
  3. select the drive for your HOST_DIR to be shared
  4. confirm with Apply and continue
_images/docker-windows.jpg