Phables: from fragmented assemblies to high-quality bacteriophage genomes

Phables is a tool developed to resolve bacteriophage genomes using assembly graphs of viral metagenomic data. It models phage-like components in the viral metagenomic assembly as flow networks, models as a minimum flow decomposition problem and resolves genomic paths corresponding to flow paths determined. Phables uses the Minimum Flow Decomposition via Integer Linear Programming implementation to obtain the flow paths.

For detailed instructions on installation and usage, please refer to the documentation hosted at Read the Docs.

Phables is available on Bioconda at https://anaconda.org/bioconda/phables and on PyPI at https://pypi.org/project/phables/. Feel free to pick your package manager, but we recommend that you use conda.

NEW: Phables is now available as a Docker container from Docker hub. Click here for more details.

Setting up Phables

Option 1: Installing Phables using conda (recommended)

You can install Phables from Bioconda at https://anaconda.org/bioconda/phables. Make sure you have conda installed.

```bash

create conda environment and install phables

conda create -n phables -c conda-forge -c anaconda -c bioconda phables

activate environment

conda activate phables ```

Now you can go to Setting up Gurobi to configure Gurobi.

Option 2: Installing Phables using pip

You can install Phables from PyPI at https://pypi.org/project/phables/. Make sure you have pip and mamba installed.

bash pip install phables

Now you can go to Setting up Gurobi to configure Gurobi.

Setting up Gurobi

The MFD implementation uses the linear programming solver Gurobi. The phables conda environment and pip setup does not include Gurobi. You have to install Gurobi using one of the following commands depending on your package manager.

```bash

conda

conda install -c gurobi gurobi

pip

pip install gurobipy ```

To handle large models without any model size limitations, once you have installed Gurobi, you have to activate the (academic) license and add the key using the following command. You only have to do this once.

bash grbgetkey <KEY>

You can refer to further instructions at https://www.gurobi.com/academia/academic-program-and-licenses/.

Test the installation

After setting up, run the following command to print out the Phables help message.

bash phables --help

Quick Start Guide

Phables is powered by Snaketool which packs in all the setup, testing, preprocessing and running steps into an easy-to-use pipeline.

Setup the databases

```bash

Download and setup the databases - you only have to do this once

phables install ```

Run on test data

bash phables test

Run on your own data

```bash

Run Phables using short read data

phables run --input assembly_graph.gfa --reads fastq/ --threads 8

Run Phables using long read data

phables run --input assembly_graph.gfa --reads fastq/ --threads 8 --longreads ```

Please refer to the documentation hosted at Read the Docs for further information on how to run Phables.

Issues and Questions

If you want to test (or break) Phables give it a try and report any issues and suggestions under Phables Issues.

If you come across any questions, please have a look at the Phables FAQ page. If your question is not here, feel free to post it under Phables Issues.

Contributing to Phables

Are you interested in contributing to the Phables project? If so, you can check out the contributing guidelines in CONTRIBUTING.md.

Acknowledgement

Phables uses the Gurobi implementation of MFD-ILP and code snippets from STRONG, METAMVGL, GraphBin, MetaCoAG and Hecatomb. Special thanks are owed to Ryan Wick for developing Bandage to visualise assembly graphs, which I heavily rely upon to investigate, develop and optimise my methods. The Phables logo was designed by Amber Skye.

Citation

Phables is published in Bioinformatics at DOI: 10.1093/bioinformatics/btad586.

If you use Phables in your work, please cite Phables as,

Vijini Mallawaarachchi, Michael J Roach, Przemyslaw Decewicz, Bhavya Papudeshi, Sarah K Giles, Susanna R Grigson, George Bouras, Ryan D Hesse, Laura K Inglis, Abbey L K Hutton, Elizabeth A Dinsdale, Robert A Edwards, Phables: from fragmented assemblies to high-quality bacteriophage genomes, Bioinformatics, Volume 39, Issue 10, October 2023, btad586, https://doi.org/10.1093/bioinformatics/btad586

bibtex @article{10.1093/bioinformatics/btad586, author = {Mallawaarachchi, Vijini and Roach, Michael J and Decewicz, Przemyslaw and Papudeshi, Bhavya and Giles, Sarah K and Grigson, Susanna R and Bouras, George and Hesse, Ryan D and Inglis, Laura K and Hutton, Abbey L K and Dinsdale, Elizabeth A and Edwards, Robert A}, title = "{Phables: from fragmented assemblies to high-quality bacteriophage genomes}", journal = {Bioinformatics}, volume = {39}, number = {10}, pages = {btad586}, year = {2023}, month = {09}, abstract = "{Microbial communities have a profound impact on both human health and various environments. Viruses infecting bacteria, known as bacteriophages or phages, play a key role in modulating bacterial communities within environments. High-quality phage genome sequences are essential for advancing our understanding of phage biology, enabling comparative genomics studies and developing phage-based diagnostic tools. Most available viral identification tools consider individual sequences to determine whether they are of viral origin. As a result of challenges in viral assembly, fragmentation of genomes can occur, and existing tools may recover incomplete genome fragments. Therefore, the identification and characterization of novel phage genomes remain a challenge, leading to the need of improved approaches for phage genome recovery.We introduce Phables, a new computational method to resolve phage genomes from fragmented viral metagenome assemblies. Phables identifies phage-like components in the assembly graph, models each component as a flow network, and uses graph algorithms and flow decomposition techniques to identify genomic paths. Experimental results of viral metagenomic samples obtained from different environments show that Phables recovers on average over 49\\% more high-quality phage genomes compared to existing viral identification tools. Furthermore, Phables can resolve variant phage genomes with over 99\\% average nucleotide identity, a distinction that existing tools are unable to make.Phables is available on GitHub at https://github.com/Vini2/phables.}", issn = {1367-4811}, doi = {10.1093/bioinformatics/btad586}, url = {https://doi.org/10.1093/bioinformatics/btad586}, eprint = {https://academic.oup.com/bioinformatics/article-pdf/doi/10.1093/bioinformatics/btad586/51972145/btad586.pdf}, }

Also, please cite the following tools/databases used by Phables.

• Roach MJ, Pierce-Ward NT, Suchecki R, Mallawaarachchi V, Papudeshi B, et al. Ten simple rules and a template for creating workflows-as-applications. PLOS Computational Biology 18(12) (2022): e1010705. https://doi.org/10.1371/journal.pcbi.1010705
• Terzian P, Olo Ndela E, Galiez C, Lossouarn J, Pérez Bucio RE, Mom R, Toussaint A, Petit MA, Enault F. PHROG: families of prokaryotic virus proteins clustered using remote homology. NAR Genomics and Bioinformatics, Volume 3, Issue 3, lqab067 (2021). https://doi.org/10.1093/nargab/lqab067
• Steinegger M, Söding J. MMseqs2 enables sensitive protein sequence searching for the analysis of massive data sets. Nat Biotechnol 35, 1026–1028 (2017). https://doi.org/10.1038/nbt.3988
• Li H. Minimap2: pairwise alignment for nucleotide sequences. Bioinformatics, 34:3094-3100 (2018). https://doi.org/10.1093/bioinformatics/bty191
• Li H, Handsaker B, Wysoker A, Fennell T, Ruan J, Homer N, Marth G, Abecasis G, Durbin R, 1000 Genome Project Data Processing Subgroup. The Sequence Alignment/Map format and SAMtools, Bioinformatics, Volume 25, Issue 16, Pages 2078–2079 (2009). https://doi.org/10.1093/bioinformatics/btp352
• Woodcroft BJ, Newell R, CoverM: Read coverage calculator for metagenomics (2017). https://github.com/wwood/CoverM
• Roach, M. J., Hart, B. J., Beecroft, S. J., Papudeshi, B., Inglis, L. K., Grigson, S. R., Mallawaarachchi, V., Bouras, G., & Edwards, R. A. Koverage: Read-coverage analysis for massive (meta)genomics datasets. Journal of Open Source Software, 9(94), 6235, (2024). https://doi.org/10.21105/joss.06235
• Hagberg AA, Schult DA, and Swart PJ. Exploring network structure, dynamics, and function using NetworkX. In Proceedings of the 7th Python in Science Conference (SciPy2008), Gäel Varoquaux, Travis Vaught, and Jarrod Millman (Eds), (Pasadena, CA USA), pp. 11–15 (2008).
• Gurobi Optimization. https://www.gurobi.com/.