Installation

Note

Currently, VALIS requires Python 3.9 or 3.10

DockerHub

VALIS is available as a Docker image and can be downloaded from DockerHub. Starting a container will launch an Ubuntu shell, and so Python needs to be called when executing the script. In this example, the user has a file called “register.py” that takes src_dir and dst_dir arguments, which registers all of the images in src_dir and saves the results in dst_dir. This example bind mounts the home directory, and thus the full paths need to be specified.

$ docker run --memory=20g  -v "$HOME:$HOME" cdgatenbee/valis-wsi python3 full/path/to/register.py -src_dir full/path/to/images_to_align -dst_dir full/path/to/where_to_save_results

Important

To avoid the container from shutting down prematurely, be sure to set appropriately high memory limits (including in Docker Desktop).

Pip install

VALIS can be downloaded from PyPI as the valis-wsi package using the pip command. However, also VALIS requires several system level packages, which will need to be installed first (see Prerequisites below).

$ pip install valis-wsi

One can also use pip to install directly from Github

$ pip install git+https://github.com/MathOnco/valis.git

Prerequisites

VALIS uses Bioformats to read many slide formats. Bioformats is written in Java, and VALIS uses the Python package jpype to access the Bioformats jar. Therefore, the user will need to have installed a Java Development Kit (JDK) containing the Java Runtime Environment (JRE):

  1. Download appropriate JDK from java downloads

  2. Edit your system and environment variables to update the Java home

    $ export JAVA_HOME=/usr/libexec/java_home

  3. Verify the path has been added:

    $ echo $JAVA_HOME

    should print something like usr/libexec/java_home

  4. Install Maven <https://maven.apache.org/index.html>_, which is also required to use Bioformats

  5. (optional) If you will be working with files that have extensions: ‘.vmu’, ‘.mrxs’ ‘.svslide’, you will also need to install OpenSlide. Note that this is not the same as openslide-python, which contains Python wrappers for OpenSlide.

    Important

    OpenSlide requires pixman, which must be version 0.40.0. If pixman is a different version, then the slides may be distorted when reading from any pyramid level other than 0.

  6. VALIS uses pyvips to warp and save the whole slide images (WSI) as ome.tiffs. Pyvips requires libvips (not a Python package) to be on your library search path, and so libvips must be installed separately. See the pyvips installation notes for instructions on how to do this for your operating system. If you already have libvips installed, please make sure it’s version is >= 8.11.

Install

Once the above prerequisites have been satistifed, valis can be installed using pip, idealy within a virtual environment

$ python3 -m venv venv_valis
$ source ./venv_valis/bin/activate
$ python3 -m pip install --upgrade pip
$ python3 pip install valis-wsi

SimpleElastix (optional)

The defaults used by VALIS work well, but VALIS also provides optional classes that require SimpleElastix. In particular, these classes are:

  1. affine_optimizer.AffineOptimizerMattesMI, which uses sitk.ElastixImageFilter to simultaneously maximize Mattes Mutual Information and minimize the spatial distance between matched features.

  2. non_rigid_registrars.SimpleElastixWarper, which uses sitk.ElastixImageFilter to find non-rigid transformations between pairs of images.

  3. non_rigid_registrars.SimpleElastixGroupwiseWarper, which uses sitk.ElastixImageFilter to find non-rigid transformations using groupwise registration.

To install SimpleElastix, you should probably uninstall the current version of SimpleITK in your environment, and then install SimpleElastix as described in the SimpleElastix docs.

From source

One will need to install and use Poetry to install VALIS from the source code. As Poetry only installs the Python dependencies, one will also need to follow the steps above to install the JDK, Maven, libvips, and openslide. Note that the poetry lock file is included in the repository, which can be deleted before installation if so desired.