Metadata-Version: 2.4
Name: phagemine
Version: 1.3.1
Summary: Evidence-first phage annotation and discovery mining
Author: Nnaemeka Emmanuel Nnadi
License: MIT License
        
        Copyright (c) 2026 PhageMine contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/emmannaemeka/PhageMine
Project-URL: Repository, https://github.com/emmannaemeka/PhageMine
Project-URL: Issues, https://github.com/emmannaemeka/PhageMine/issues
Project-URL: Changelog, https://github.com/emmannaemeka/PhageMine/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/emmannaemeka/PhageMine/blob/main/docs/installation.md
Keywords: bacteriophage,phage,genome annotation,comparative genomics,bioinformatics,viral genomics,PHANOTATE,PHROGs,INPHARED
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython<2,>=1.85
Requires-Dist: psutil<8,>=5
Requires-Dist: matplotlib<4,>=3.7
Requires-Dist: pyhmmer<0.13,>=0.10
Requires-Dist: pyrodigal==3.7.1
Requires-Dist: pyrodigal-gv==0.3.2
Requires-Dist: pyrodigal-rv==0.1.0
Provides-Extra: gui
Requires-Dist: streamlit<2,>=1.49; extra == "gui"
Provides-Extra: test
Requires-Dist: biopython<2,>=1.85; extra == "test"
Requires-Dist: build<2,>=1; extra == "test"
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: tomli; python_version < "3.11" and extra == "test"
Dynamic: license-file

# PhageMine: Bacteriophage Genome Annotation and Comparative Genomics

[![CI](https://github.com/emmannaemeka/PhageMine/actions/workflows/ci.yml/badge.svg)](https://github.com/emmannaemeka/PhageMine/actions/workflows/ci.yml)
[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg)](https://bioconda.github.io/recipes/phagemine/README.html)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22794629.svg)](https://doi.org/10.5281/zenodo.22794629)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**PhageMine** is an open-source bioinformatics pipeline for bacteriophage genome
annotation, functional evidence integration and comparative genomics. It combines
phage-focused gene prediction with protein sequence and profile searches, links
functional assignments to their supporting evidence, and produces annotated
sequences, evidence tables and an HTML report.

PhageMine uses PHANOTATE for protein-coding gene prediction; PHROGs, VOGDB, Pfam
and Swiss-Prot for functional evidence; and INPHARED references for comparative
genomic context. It is designed for researchers working in phage genomics,
bacteriophage genome annotation, viral genomics and related bioinformatics
workflows.

## What it does

- Predicts protein-coding genes with PHANOTATE.
- Uses PHROGs, VOGDB, Pfam and Swiss-Prot to assess protein function.
- Reports supporting evidence, conflicting assignments and unknown functions.
- Processes individual genomes or genome collections.
- Groups related proteins into families and compares genomes with INPHARED references.
- Exports GFF3, protein FASTA and GenBank preparation files.

## Install

The current stable release is [v1.3.1](https://github.com/emmannaemeka/PhageMine/releases/tag/v1.3.1).
Python 3.10 or later is required.

Install from Bioconda, which brings the external analysis tools with it:

```bash
conda create --name phagemine --channel conda-forge --channel bioconda phagemine
conda activate phagemine
phagemine doctor
```

Or from PyPI, with the external tools installed separately:

```bash
pip install phagemine
```

To install from source instead:

```bash
git clone --branch v1.3.1 --depth 1 https://github.com/emmannaemeka/PhageMine.git
cd PhageMine
conda env create --file environment.yml
conda activate phagemine
python -m pip install .
phagemine doctor
```

Install the databases before running functional annotation:

```bash
phagemine databases install --all
```

This installs PHROGs, Swiss-Prot, Pfam and VOGDB, plus PMFDB and INPHARED
comparative references. Prepared databases require additional disk space beyond
the download sizes.

See the [installation guide](docs/installation.md) for platform requirements
and troubleshooting.

## Annotate a genome

Supply a single-genome nucleotide FASTA file:

```bash
phagemine run genome.fasta --output results/genome --threads 8
```

Open `results/genome/report.html` to browse the results. The output directory
also contains `annotation.tsv`, `genes.gff3`, `proteins.faa` and supporting
evidence files.

To check the installation with the bundled example:

```bash
phagemine run examples/demo_phage.fasta --output results/example
```

Installed databases are detected automatically. Without them, the example
checks gene prediction and report generation; functional evidence is unavailable.

Run `phagemine --help` for all commands and `phagemine run --help` for annotation
options.

## Reading the results

Product names describe the function supported by the available evidence.
Proteins without a supported function remain hypothetical or are identified as
conserved proteins of unknown function. Gene symbols, protein products and
locus identifiers are reported separately.

PhageMine is research software. Functional predictions require review,
and confidence labels describe evidence strength rather than calibrated
probabilities. See the [limitations](docs/limitations.md) for interpretation.

## Citation and support

Citation information is available in [CITATION.cff](CITATION.cff) and the
[archived release](https://doi.org/10.5281/zenodo.22794629).

Report bugs or request features through
[GitHub Issues](https://github.com/emmannaemeka/PhageMine/issues).
PhageMine is distributed under the [MIT licence](LICENSE).
