Installation

This is an installation guide for the BacterialTyper pipeline.

BacterialTyper is a pipeline composed of multiple lines of code that calls and automatizes the analysis from multiple bioinformatic tools. Several dependencies (python, perl, additional software and their dependencies and third-party software) are required for the BacterialTyper analysis.

You first need to get BacterialTyper (from different sources available): you can either install BacterialTyper latest version using Python pip or if you want to contribute or see additional details of the project, it’s recommended you install the latest development version.

Once you get the code, before running BacterialTyper you must make sure you have all the dependencies fulfilled from section Requirements and dependencies using the BacterialTyper config module.

Requirements and dependencies

System requirements

Take into account that you may need some system requirements to install BacterialTyper already available in your system such as python3, python3-dev and python3-venv or build-essential libraries among others.

Check and install them by typing:

sudo apt install python3 python3-dev python-dev python3-venv python-pip
sudo apt install build-essential libssl-dev libffi-dev libxml2-dev libxslt1-dev zlib1g-dev

BacterialTyper requirements

We include details on the different modules required by BacterialTyper to successfully run here:

• Python modules
  • Python requirements details
• Perl packages
• Software dependencies
• Third party software

Installing BacterialTyper

If you want to run a stable version of BacterialTyper, install it using pip package following instructions in Installing from pip. On the other hand if you are interested in contributing to BacterialTyper development, running the latest source code, or just like to build everything yourself, you should follow the Installing from source instructions.

Additionally, there are a number of dependencies that might be necessary to install or check within your system in both cases. Choose the appopiate choice according to your intalling BacterialTyper option selected.

Installing from pip

The fastest and most straightforward solution to install the latest release (or any desired version) of BacterialTyper is to install it (and all its python dependencies), using Python pip.

First, we encourage you to create a virtual environment before installing BacterialTyper. See section for Python environment for further details.

To install BacterialTyper using pip type:

python3 -m pip install BacterialTyper

Follow additional pip installing instructions to learn about installing packages.

Also, as BacterialTyper relies in multiple dependencies, external perl packages, software and third-party software, we encourage you to once you install BacterialTyper using pip you check for dependencies using the BacterialTyper config module. See details in BacterialTyper config module section.

Installing from source

Under some circumstancies (develop, bugs fixed, etc) you might be interested in obtaining the latest code version. Take into account, that you will need to install dependencies and fulfill requirements to have a working distribution.

Get source code

The BacterialTyper project uses git as a version control system. To get the code, you can grab the latest version from the BacterialTyper github website, and follow the Install BacterialTyper from source instructions.

Using the command-line, check you have a working distribution of git by typing git --help or install it by typing:

sudo apt update
sudo apt upgrade
sudo apt install git

Once you have git installed and working change directory to a folder of interest where the BacterialTyper project would be download. Type:

git clone https://github.com/JFsanchezherrero/BacterialTyper.git

Additionally, BacterialTyper contains a third-party project, IslandPath-DIMOB (IslandPath [1]) that BacterialTyper developers forked, updated and adapted. See additional details on this project here.

Then, if you are downloading BacterialTyper code from source, you need to retrieve the submodule latest version and install it accordingly. To do so, type:

git clone --recurse-submodules https://github.com/JFsanchezherrero/BacterialTyper.git

On the other hand, you can also do it manually. In the directory containing git BacterialTyper project you would find a third_party folder. Change directory to there and type:

cd BacterialTyper/third_party
git submodule init
git submodule update

For additional details about git submodules see information here: https://git-scm.com/book/en/v2/Git-Tools-Submodules

Install BacterialTyper from source

Once you have BacterialTyper source code available you only need to include the BacterialTyper folder and main script within your path.

export PYTHONPATH=$PYTHONPATH":"$PWD"/BacterialTyper"

export PATH=$PATH":"$PWD"/BacterialTyper.py"

Take into account that before running BacterialTyper you have to make sure you have all the dependencies fulfilled from section Requirements and dependencies. You can either install them yourself, use appropiate scripts for this purpose or use the BacterialTyper config module to check, update and install all dependencies required.

Python environment

It is always recommended to install BacterialTyper and all its dependencies and modules under a python environment.

Take into account that you might need to have installed several developer libraries in your system. See section System requirements for details.

By executing the env/create_python_environment.sh script, it creates an environment, installs all python requirements and activates it for later usage.

You only have to create the environment once and you can populate with additional modules, see details in Install modules.

Make sure to deactivate the environment after finishing the exection of `BacterialTyper or activate it before running it, following the instructions in Deactivate environment or Activate environment sections respectively.

Create environment

To do so, run env/create_python_environment.sh, which is shown below:

#!/usr/bin/env bash

echo ""
echo ""
echo "##### Create a virtual environment for BacterialTyper ####"
echo ""

export PYTHONPATH=""
echo "python3 -m venv env/BacterialTyper"
python3 -m venv env/BacterialTyper
echo "Done..."
echo ""

echo "#### Activate virtual environment ####"
echo "source env/BacterialTyper/bin/activate"
source env/BacterialTyper/bin/activate
echo "Done..."
echo ""

## upgrade pip
echo "#### Upgrade pip package installer ####"
echo "pip install -I --isolated --upgrade pip"
pip install -I --isolated --upgrade pip
echo "Done...."
echo ""

# install BacterialTyper requirements

echo "#### Install pip package requirements ####"
echo "pip install -I --isolated --default-timeout=500 -r BacterialTyper/config/python/min_python_requirements.txt"
pip install -I --isolated --default-timeout=500 -r BacterialTyper/config/python/min_python_requirements.txt
echo "Done...."
echo ""

echo "Exit...."
echo ""

Execute the file from the main directory as:

source env/create_python_environment.sh

Within this create environment script, there is a command to install all python requirements for BacterialTyper:

pip install -r BacterialTyper/config/python_requirements.txt

Activate environemt

Before executing any BacterialTyper module or script, it is convenient to activate the environment.

To do so, run env/activate_environment.sh, which is shown below:

#!/usr/bin/env bash

echo ""
echo ""
echo "##### Activate the virtual environment for BacterialTyper ####"
echo ""

DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
echo "source $DIR/BacterialTyper/bin/activate"
source $DIR/BacterialTyper/bin/activate
echo "Done..."
echo ""

echo "Exit...."
echo ""

Execute the file from the directory BacterialTyper/ as:

source env/activate_environment.sh

Deactivate environemt

After finished the execution of any BacterialTyper module or script, it is convenient to deactivate the environment. You can just close the terminal but it would be more appopiate to conveniently deactivate the environment first.

To do so, execute the following command:

deactivate

Install modules

Once the BacterialTyper environment is created, install using pip BacterialTyper or any additional modules.

e.g.: Install BacterialTyper

python -m pip install BacterialTyper

e.g.: install a list of requirements

pip install -r BacterialTyper/config/python_requirements.txt

Attention

Installing BacterialTyper using pip installs all the python requirements. For additional third-party software and software required for BacterialTyper to work you will need to run the config module.