Skip to content

2 Installation

Jump to bottom
Christopher Neely edited this page Aug 31, 2021 · 105 revisions

Installation - Docker

GTDB-Tk r95 update!

This section is for current users - proceed to Step 1 if this is your first time downloading MetaSanity.

We have updated the latest MetaSanity docker image to include GTDB-Tk r95!

Update instructions Ensure your python environment is activated (if needed). If you do not still have the install.py script from your original installation, download it in the directory that contains your MetaSanity installation:

wget https://raw.githubusercontent.com/cjneely10/MetaSanity/master/install.py -O install.py

Your directory should look like:

|- install.py
|- MetaSanity/
...

From the path that contains the install.py script:

python3 install.py
cd MetaSanity
python3 download-data.py -d gtdbtk

Availability and speed of data download is subject to the discretion of the hosting facility.

Step One: Create environment

Users are recommended to install MetaSanity within a separate python virtual environment, as packages within this software may conflict with existing package installations.

Create the environment and give it an appropriate name. For example, to create an environment named "metasanity_env", run python3 -m venv metasanity_env.

Once created, initiate the python virtual environment using source metasanity_env/bin/activate.

Install the argparse and wheel packages by using pip3 install argparse wheel.

docker, wget, git, and sed, are also required.

Step Two: Download install script

Install MetaSanity by using its install Python3 script. Download the script from this repository.

wget https://raw.githubusercontent.com/cjneely10/MetaSanity/master/install.py -O install.py

Run the install script to download MetaSanity. For example, python3 install.py will download the default installation (Docker image - docker must be in the user's PATH to run this installation).

Important Note on updating to MetaSanity v1.2.0

Version 1.2 no longer requires aliases to be set in the user's .bashrc. If you are updating from an earlier version of MetaSanity and have either MetaSanity or dbdm set as an alias, please remove them and restart your bash session prior to running your update. See the Make MetaSanity callable section for more instructions.

usage: install.py [-h] [-s SECTIONS] [-t DOWNLOAD_TYPE] [-v VERSION]

Download MetaSanity package

optional arguments:
  -h, --help            show this help message and exit
  -s SECTIONS, --sections SECTIONS
                        Comma-separated list to download.
                        Select from: docker_installation,sourcecode_installation,docker_image,sourcecode,biometadb,scripts
                        (def docker_installation)
  -t DOWNLOAD_TYPE, --download_type DOWNLOAD_TYPE
                        Download type for scripts. Select from: Docker,SourceCode (def Docker)
  -v VERSION, --version VERSION
                        Version to download. (def v1.2.0)

The install.py script may now be deleted. Change directory into the MetaSanity download location. For example, cd MetaSanity.

Step Three: Download required databases

MetaSanity relies on a series of databases to compute its evaluation and annotation pipelines:

  • GTDB-Tk release 89.0
  • CheckM 2015_01_16
  • KoFamScan (most recent release as of Feb 2020)
  • dbCAN HMMdb-V8
  • virsorter-data-v2

The script download-data.py in the program package is available to easily download all needed database files into the MetaSanity installation. Run the script to download all required databases:

python3 download-data.py

This will download and extract ~46GB of database files into the MetaSanity directory. However, users may elect only to download a subset of these databases.

Downloading a subset of the full data (optional)

MetaSanity's functionality is divided between two pipelines that handle genome/MAG/SAG evaluation and annotation. Users may choose to download a subset of the databases if only one pipeline will be used.

MetaSanity's evaluation pipeline requires 2 databases to predict phylogeny and genome/MAG statistics. These can be installed by running the command:

python3 download-data.py -d gtdbtk,checkm

MetaSanity's annotation pipeline requires 3 databases to generate gene annotations. These can be installed by running the command:

python3 download-data.py -d kofamscan,peptidase,virsorter

Database availability is subject to the discretion of each program's hosting institution.

Step Four: Link install to downloads

The install.py script configures the MetaSanity installation for the user's system.

Confirm that the variable DOWNLOAD_DIRECTORY on line 29 in the MetaSanity.py script is the correct location of the program installation. For example, if the program was installed in User's home directory, the line should read DOWNLOAD_DIRECTORY = "/home/User/MetaSanity".

Users who have database files stored in directories not generated by the download-data.py script, or who have external BioMetaDB installations, should update these values as needed in MetaSanity.py. If the download-data.py script was used to download data to a directory other than the default MetaSanity values, update the databases directory location on line 50.

Step Five: Download recommended programs (as desired)

MetaSanity can integrate additional software into its pipeline. However,

Some optional programs in MetaSanity require users to accept additional academic license agreements.

These programs also require additional information about the Docker environment through which they will be called in MetaSanity. Follow the instructions below to configure these programs' binaries.

  • SignalP4.1 may optionally be installed.

    • SignalP is used in the annotation pipeline with PSORTb to predict the presence of signal peptides. If it is not included, some extracellular assignments may be missed.
    • Accept the user-agreement and download, following the website's installation instructions.
    • Open the script using nano /path/to/signalp-4.1/signalp.
    • Replace the line that starts with $ENV{SIGNALP} with $ENV{SIGNALP} = '/home/appuser/signalp';.
    • Your script should resemble the following screenshot

  • RNAmmer1.2 may optionally be installed.

    • RNAmmer may be used to detect ribosomal RNA genes (in place of the default Barrnap). Excluding it will not affect the analysis in any way.
    • Accept the user-agreement and download, following the website's installation instructions.
    • Open the script using nano /path/to/rnammer-1.2.src/rnammer.
    • Replace the line that start with my $INSTALL_PATH with my $INSTALL_PATH = "/home/appuser/rnammer";.
    • Replace the lines that starts with $HMMSEARCH_BINARY with $HMMSEARCH_BINARY = "/usr/bin/hmmsearch";.
    • This section of your script should resemble the following screenshot

    • Replace lines 94 and 95 (assigning $TEMP_WORKING_DIR) with the single line $TEMP_WORKING_DIR = "/home/appuser/rnammer_tmp/";.
    • This section of your script should resemble the following screenshot

  • InterProScan-5.36-75.0 may optionally be installed.

    • InterProScan predicts protein domains in the gene calls. Its use adds significant runtime to an analysis, but it can provide a significant increase in the total number of annotations.
    • wget ftp://ftp.ebi.ac.uk/pub/software/unix/iprscan/5/5.36-75.0/interproscan-5.36-75.0-64-bit.tar.gz
    • Optional Panther database download instructions are available here.
    • The precalculated match lookup is not supported. Change the line 239 in interproscan.properties to be precalculated.match.lookup.service.url=, or include the flag --disable-precalc when incorporating InterProScan in the FuncSanity workflow.

Linking recommended program installations

In the MetaSanity.py script, change the values of the variables INTERPROSCAN_FOLDER, SIGNALP_FOLDER, and RNAMMER_FOLDER to be the location of the above programs that you used. If you do not plan on using a program, do not modify its value.

For example, navigate to the directory containing the signalp-4.1 installation and run pwd. Copy this path and replace the SIGNALP_FOLDER location with this value.

Step 6: Confirming a valid installation

Prior to running your MetaSanity.py script, ensure ALL of the following:

  • The DOWNLOAD_DIRECTORY is the correct location of the MetaSanity directory (line 29).
  • The VERSION is v1.2.0 (line 31).

If you are using any of the recommended programs listed above, make sure that their paths are correct (lines 38-42).

If you installed databases in a separate location than in the MetaSanity installation directory, ensure that lines 50-60 are valid.

(optional) Make MetaSanity callable

  • Create a softlink to any location on your path (in this case, the user's bin directory).
    • ln -s /path/to/MetaSanity/MetaSanity.py ~/bin/MetaSanity
    • ln -s /path/to/MetaSanity/Accessories/* ~/bin/

Your installation is complete! See the full example to test your installation and to learn how to use MetaSanity! Learn more about PhyloSanity and FuncSanity on their wiki pages!

Clone this wiki locally