Installation

Installation instructions:

This guide is not a substite for computing expertise. Users are recommended to not install GRAViTy-V2 if they do not understand the installation instructions and should defer to their system administrator's guidance. Always check the terminal output.

This guide is tested on Windows Subsystems Linux 22.04, Ubuntu 22.04 LTS and Ubuntu Server 22.04 LTS. We anticipate that variations in operating system and system architecture (in particular, servers) will necessitate amendments to the process outlined below, hence this is advisory only.

Users should opt for one of the following methods: install from source, pull pre-build Docker container from DockerHub, build Docker container from source. Docker builds require less setup and do not require the user to have administrator access to their machine, but specific skills are needed to interact with them. See Advanced usage options for more details on how to run GRAViTy-V2 from a Docker container.

Install from source

1. Ensure you have Conda installed: https://conda.io/projects/conda/en/latest/user-guide/install/index.html
2. Create a new Conda environment called gravity with python 3.10: conda create -n gravity python=3.10
3. Activate your Conda environment: conda activate gravity
4. Clone GRAViTy-V2 repo: git clone "https://github.com/Mayne941/gravity2" (or, use SSH equivalent)
5. Navigate to GRAViTy-V2 directory: cd {path-to-dir}
6. Install command line tool requirements: bash install_deps_local.sh
7. Install Python libraries with pip: pip install -r requirements.txt
8. (Bash only) echo "alias gravity='conda activate gravity && uvicorn app.api:app --reload --port 8000'" >> ~/.bashrc, then refresh your terminal with $ source ~/.bashrc.
9. Check that installation of libraries and third party tools was successful. Activate your GRAViTy-V2 Conda environment with $ conda activate gravity, then call the dependency test with $ python3 -m cli.dep_test. Check the terminal output for success/error messages.
10. Trigger an example run python3 -m cli.example_run. Check the terminal output for success/error messages. Output will be saved to ./output/GRAViTyV2_example_run.

Pull DockerHub container

Users may pull a pre-made image from DockerHub at this link. This contains version 7 of the Castanet application, all of its dependencies and a Kraken2 database for labelling Human reads.

1. Pull container with $ docker pull mayne941/gravityv2

Build Docker container from source

Users may build a Docker container from source using the following instructions.

1. Ensure your system has Docker installed.
2. Navigate to the GRAViTy-V2 repository.
3. Build the container with $ docker build --tag 'gravityv2' .
4. Run the container with $ docker run -d -v /path/to/data:/path/to/mount 'gravityv2' sleep infinity, changing path/to/data to the volume you wish to mount and path/to/mount to where your mounted directory should live inside the container.