Installation

Tranquillyzer is available through one of two methods - either through a Docker image (the suggested method) or building yourself from the GitHub repository.

Tranquillyzer Containerization

The suggested method for running Tranquillyzer is through the provided image file. This addresses all necessary dependencies and provides better reproducibility across systems.

Important Notes for Containers

When running a container and trying to access the GPUs, you may need to bind the path to the CUDA toolkit you are using to the run or exec command.
Containers access GPU resources in different ways. Please ensure your containerization tool of choice is properly set up to access GPUs.
Some model files may be already included in the image file. To test which models, if any, are available, run tranquillyzer availablemodels with your containerization tool of choice. If no models are available or the model you want is not available, bind the directory containing your models to the run/exec command and then copy the model files into the models/ directory of Tranquillyzer.

Pre-Built Tranquillyzer Image

Tranquillyzer is available on DockerHub. It can be pulled and run from Docker, Singularity, and Apptainer.

Note

In the following pull commands, replace TAG with the specific version you are downloading. The specific version names can be found in the tags tab of DockerHub.

Docker

# Pull from DockerHub
docker pull varishenlab/tranquillyzer:tranquillyzer_TAG

# Run container
docker run -it --gpus all varishenlab:tranquillyzer /bin/bash

# Run specific Tranquillyzer subcommand via the image file
# Note, this can only access GPUs if the varishenlab:tranquillyzer is running
#     and initialized with GPU support
docker exec varishenlab:tranquillyzer tranquillyzer available-gpus

Singularity

# Pull from DockerHub
singularity pull \
    tranquillyzer.sif \
    docker://varishenlab/tranquillyzer:tranquillyzer_TAG

# Run container
singularity shell --nv tranquillyzer.sif

# Run specific Tranquillyzer subcommand via the image file
singularity exec --nv tranquillyzer.sif tranquillyzer available-gpus

Apptainer

# Pull from DockerHub
apptainer pull \
    tranquillyzer.sif \
    docker://varishenlab/tranquillyzer:tranquillyzer_TAG

# Run container (--nv needed for NVIDIA support)
apptainer run --nv tranquillyzer.sif

# Run specific Tranquillyzer subcommand via the image file (--nv needed for
#     NVIDIA support)
apptainer exec --nv tranquillyzer.sif tranquillyzer available-gpus

Build Your Own

The Dockerfile used to generate the image available on DockerHub is available within the Tranquillyzer GitHub repository. It can be used to build your own image of Tranquillyzer to run.

# Clone repository
git clone git@github.com:huishenlab/tranquillyzer.git
cd tranquillyzer

# IMPORTANT: Copy model files to models/ directory
# (See Step 2 of the GitHub installation instructions below)
# This saves having to bind and copy the model files later

# Build new image
docker build --no-cache --tag tranquillyzer --file Dockerfile .

# Run container
docker run -it --gpus all tranquillyzer /bin/bash

GitHub

We recommend using mamba for efficient environment setup and reproducibility. The following steps will guide you through a clean GPU-enabled installation.

Installation Prerequisites

Tranquillyzer is currently only available on GitHub and requires the following tools to perform the installation:

git
mamba

pip is also required; however, this will be installed when creating the virtual environment and does not need to be installed ahead of time.

1. Clone the Repository

git clone https://github.com/huishenlab/tranquillyzer.git
cd tranquillyzer

2. Add Model Files

Before proceeding with the installation, download the model files this Dropbox link and manually place the required model files inside the models/ directory.

For the REG model (i.e., the base model), the following files are required:

<model_name>.h5
<model_name>_lbl_bin.pkl

The CRF model, on the other hand, requires the following files:

<model_name>_w_CRF.h5
<model_name>_w_CRF_lbl_bin.pkl
<model_name>_w_CRF_params.json

These files are needed for the annotation and visualization functionality.

3. Create and Activate Virtual Environment

mamba env create -f environment.yml
mamba activate tranquillyzer

Note, this step could be run with conda instead of mamba.

4. Install GPU-enabled TensorFlow and Add-ons

Note, this step only needs to be run for version 0.1.*. For those installing version 0.2.0 or greater, skip to Step 5.

To ensure compatibility with Tranquillyzer, be sure to specify version 2.15.1 for TensorFlow. Further, specify tensorflow[and-cuda] and NOT tensorflow to avoid system-wide CUDA requirements.

# TensorFlow with CUDA support
pip install \
    "tensorflow[and-cuda]==2.15.1" \
    --extra-index-url https://pypi.nvidia.com

# TensorFlow Add-ons
pip install "tensorflow-addons==0.22.*"

Fix Any Missing Dependencies

If you see errors or warnings after installing TensorFlow, especially related to bx-python or scikit-learn, one possible solution is to run:

pip install bx-python scikit-learn

Then, try rerunning the TensorFlow installation.

5. Install Tranquillyzer

From the root directory of the Tranquillyzer repository, run:

pip install -e .

6. Verify Installation

To verify that Tranquillyzer is installed correctly, run:

tranquillyzer --help

You should see the CLI help message with the available sub-commands including (but not limited to):

availablemodels
preprocessfasta
annotate-reads
visualize