Requirements and Installation

Requirements

m2m uses Pathway Tools for the reconstruction of draft metabolic networks from annotated genomes.

Pathway-Tools version 22.5 or higher (free for academic users)
- Pathway-Tools requirements
  
  Linux: Gnome terminal and Libxm4
  
  apt-get update && apt-get install gnome-terminal libxm4
  
  All OS: NCBI Blast and a ncbirc file in user’s home directory
  
  Install with apt-get
  
  apt-get update && apt-get install gnome-terminal libxm4 ncbi-blast+ echo "[ncbi]\nData=/usr/bin/data" > ~/.ncbirc
  
  Install with a dmg installer on MacOS
- Pathway-Tools install
  
  Linux
  
  chmod +x ./pathway-tools-22.5-linux-64-tier1-install ./pathway-tools-22.5-linux-64-tier1-install
  
  and follow the instructions during the interactive install
  
  For a silent install:
  
  ./pathway-tools-22.5-linux-64-tier1-install --InstallDir your/install/directory/pathway-tools --PTOOLS_LOCAL_PATH your/chosen/directory/for/data/ptools --InstallDesktopShortcuts 0 --mode unattended
  
  MacOS
  
  Install though a .dmg installer with a graphical interface.
  
  Warning
  
  /!\ For all OS, Pathway-Tools must be in $PATH.
  
  On Linux and MacOS: export PATH=$PATH:/your/install/directory/pathway-tools.
  
  Consider adding Pathway Tools in $PATH permanently by running
  
  echo 'export PATH="$PATH:/your/install/directory/pathway-tools:"' >> ~/.bashrc
  
  Then source bashrc file:
  
  source ~/.bashrc

m2m relies on several Python packages:

mpwt to automatize metabolic network reconstruction with Pathway-Tools.
padmet to manage metabolic networks.
menetools to analyze individual metabolic capabilities using logic programming.
miscoto to analyze collective metabolic capabilities and select communities within microbiota using logic programming.

A list of Python dependencies is available in requirements.txt

Developed and tested on Linux (Ubuntu, Fedora, Debian) and MacOs (version 10.14) with Python3.8.

Continuous Integration using GitHub Actions with Python3.8 and Python3.9 on ubuntu-latest, macos-latest and windows-latest (corresponding virtual environment).

Installation with pip

pip install Metage2Metabo

Installation with Docker

To create the m2m image, use the Dockerfile found in Recipes of the Github repository. Note that the Pathway-Tools installer and the Oog.jar file need to be placed in the same folder than the Dockerfile. The name of the installer file is currently hardcoded in the Dockerfile. Hence it must be changed if you use a different version of Pathway-Tools. Please note that the following commands (especially due to the use of root privileges) apply to Linux OS.

# Launch docker.
sudo systemctl start docker

" Build image locally.
sudo docker build -t my_image .

To create and launch the container in interactive mode:

sudo docker run -ti -v /my/path/to/my/data:/shared --name="my_container" my_image bash

Then you can exit the contanier with exit. You can launch again the container with:

sudo docker start my_container

sudo docker exec -ti my_container bash

Installation with Singularity (e.g. on a cluster)

Singularity with Pathway Tools

Singularity [Ku2017] can be used to launch m2m on a cluster. Please refer to the recipe of the Github repository of the project. The Singularity container has to be created from the recipe. You might need to do it on a personal computer since it requires administrator priviledges. To use the container on a cluster, the path to Pathway Tools ptools folder should be indicated in the recipe. Therefore, you have to replace /external/folder/ptools with the path where you want to put the ptools-local folder (which will contain the PGDB created by Pathway-Tools).

Like for the Dockerfile, Pathway-Tools installer is hardcoded in the recipe so if you use another version, you have to modify the recipe. And the Pathway Tools installer and Oog.jar file must be stored in the same folder than the Singularity recipe.

To create a container named m2m.sif:

sudo singularity build m2m.sif Singularity

If you have issue with disk space in the temporary folder used by Singularity, it is possible to specify another temporary folder with SINGULARITY_TMPDIR, such as:

sudo SINGULARITY_TMPDIR=/another/tmp/folder singularity build m2m.sif Singularity

Warning, this command will fail if folder another/tmp/folder does not exist.

To use Pathway-Tools, a .ncbirc file is required in the home directory, containing the path to Blast:

.ncbirc:

[ncbi]\nData=/usr/bin/data

Dealing with Pathway Tools ptools local folder. You might need an external ptools-local folder when working on a cluster. A solution is to create the ptools-local in a local folder then move it inside the Singularity container. Eventually, you have to move it outside the Singularity container after it has been built.

First, enter the Singularity container and mount the external folder:

singularity run -B /external/folder:/external/folder m2m.sif

Then move the ptools-local folder from the Singularity folder to the folder in your local environment.

cp -r /opt/ptools-local /external/folder

This will move the ptools-local folder (with permissions) from Singularity container to the local machine.

In this way, PGDBs can be stored in the folder outside your container.

Finally, you can launch jobs with the Singularity container by giving a sh file containg m2m commands.

m2m.sh:

m2m workflow -g genomes_dir -s seeds.sbml -o output_dir -c cpu_number

So you can encapsulate it in a sh script:

my_script.sh:

#!/bin/bash

# Don't forget to source the Singularity environment if needed.
. /local/env/envsingularity.sh

singularity exec m2m.sif bash m2m.sh

This file can now be launched on a cluster, for example with SLURM [Yo2003]:

sbatch --cpus-per-task=4 --mem=8G my_script.sh

With some versions of Singularity (superior to 3.6) running singularity exec m2m.sif bash /cluster/myspace/m2m.sh will show the following error message:

/bin/bash: /cluster/myspace/m2m.sh: No such file or directory

This error comes from modifications in Singularity linked to security issue. Especially the paths accessible to a container have been reduced. To fix this the -B option can be used to give access to Singularity to a specific path, for example:

singularity exec -B /cluster/myspace/m2m:/cluster/myspace/m2m m2m.sif bash /cluster/myspace/m2m.sh

The first path after -B option corresponds to the local/cluster path and the second path corresponds to the path inside the Singularity container.

Singularity without Pathway Tools

A Singularity without Pathway Tools container is available publicly at Singularity-Hub. As there is no Pathway Tools in this container, you can not use m2m recon and m2m workflow commands.

You can download the container with the command:

singularity pull shub://ArnaudBelcour/metage2metabo-metacom_singularity

With this container, you can call m2m commands like m2m metacom:

singularity exec metage2metabo-metacom_singularity_latest.sif m2m metacom ...

[Ku2017]

Kurtzer GM, Sochat V, Bauer MW (2017) Singularity: Scientific containers for mobility of compute. PLOS ONE 12(5): e0177459.

[Yo2003]

Yoo, Andy B., Jette, Morris A., Grondona, Mark (2003). SLURM: Simple Linux Utility for Resource Management. Job Scheduling Strategies for Parallel Processing. Lecture Notes in Computer Science. 2862. p. 44.