Combating Phage Genomes

---

phu - Phage Utilities

phu (phage utilities) or phutilities, is a modular toolkit for viral genomics workflows. It provides command-line tools to handle common steps in phage bioinformatics pipelines—wrapping complex utilities behind a consistent and intuitive interface.

Installation

You can install phu using mamba or conda from the bioconda channel:

mamba create -n phu bioconda::phu

Usage

As a command-line tool, phu follows a modular structure. You can access different functionalities through subcommands. The general syntax is:

phu <command> [options]

Commands

• screen: Screen contigs for specific protein families using HMMER on predicted coding sequences.
• jack: Iteratively screen contigs from one or more seed proteins with jackhmmer and combine seeds hits.
• cluster: Cluster viral sequences into species or other operational taxonomic units (OTUs).
• simplify-taxa: Simplify vContact taxonomy prediction columns into compact lineage codes.

Database Management

A special command group, dbs, is available to manage local databases used by phu. Each database can define its own preparation logic while sharing a common user interface. Built-in backends currently include pfam and kofam.

• dbs: Manage local databases (list, status, prepare, refresh, remove) for pfam and kofam.

For screening pass/fail and threshold rules, see screen thresholds and decision logic.

Cache Handling

phu caches predicted proteins for both screen and jack so repeated runs can reuse the same translated proteins when the prediction inputs have not changed. Search settings such as HMM files, seed markers, combine mode, and output folder do not affect the cache.

The cache is rebuilt when you change the contig input, --mode, --ttable, or the protein-length filter. For phu screen, that is --min-protein-len-aa. For phu jack, both --min-gene-len and --min-protein-len-aa participate in the cache key.

To remove previously cached predictions, run phu --clean-cache.

See the full cache guide in Cache Handling.

Contributing

We welcome contributions to phu! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Make your changes and commit them.
4. Submit a pull request describing your changes.

Developers

You can also install the development version of phu directly from GitHub:

git clone https://github.com/camilogarciabotero/phu.git
cd phu
pip install -e .

phu is also available on PyPI:

pip install phu

References

This program uses several key tools and libraries, make sure to acknowledge them when using phu:

• vclust: A high-performance clustering tool for viral sequences:

Zielezinski A, Gudyś A, Barylski J, Siminski K, Rozwalak P, Dutilh BE, Deorowicz S. Ultrafast and accurate sequence alignment and clustering of viral genomes. Nat Methods. https://doi.org/10.1038/s41592-025-02701-7

• seqkit: A toolkit for FASTA/Q file manipulation.

Wei Shen*, Botond Sipos, and Liuyang Zhao. 2024. SeqKit2: A Swiss Army Knife for Sequence and Alignment Processing. iMeta e191. doi:10.1002/imt2.191.

• Prodigal: A gene prediction tool for prokaryotic genomes.

Hyatt, D., Chen, G. L., LoCascio, P. F., Land, M. L., Larimer, F. W., & Hauser, L. J. (2010). Prodigal: prokaryotic gene recognition and translation initiation site identification. BMC bioinformatics, 11(1), 119. https://doi.org/10.1186/1471-2105-11-119

• pyrodigal: A tool for gene prediction in prokaryotic genomes.

Larralde, M., (2022). Pyrodigal: Python bindings and interface to Prodigal, an efficient method for gene prediction in prokaryotes. Journal of Open Source Software, 7(72), 4296, https://doi.org/10.21105/joss.04296

• HMMER: A suite of tools for sequence analysis using profile hidden Markov models.

Eddy, S. R. (2011). Accelerated Profile HMM Searches. PLoS Computational Biology, 7(10), e1002195. https://doi.org/10.1371/journal.pcbi.1002195

• pyHMMER: Python bindings for HMMER.

Larralde, M., & Zeller, G. (2023). PyHMMER: a Python library binding to HMMER for efficient sequence analysis. Bioinformatics, 39(5). https://doi.org/10.1093/bioinformatics/btad214

• Pfams: A comprehensive collection of protein families and domains based on hidden Markov models.

Pfam: The protein families database in 2021: J. Mistry, S. Chuguransky, L. Williams, M. Qureshi, G.A. Salazar, E.L.L. Sonnhammer, S.C.E. Tosatto, L. Paladin, S. Raj, L.J. Richardson, R.D. Finn, A. Bateman, Nucleic Acids Research (2021) doi: 10.1093/nar/gkaa913

• KOFamKOALA: KEGG ortholog assignment based on profile HMM and adaptive score threshold.

Aramaki T., Blanc-Mathieu R., Endo H., Ohkubo K., Kanehisa M., Goto S., Ogata H. KofamKOALA: KEGG ortholog assignment based on profile HMM and adaptive score threshold. Bioinformatics. 2019 Nov 19. pii: btz859. doi: 10.1093/bioinformatics/btz859.