phagemine 1.3.1__tar.gz

phagemine-1.3.1/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.venv
+.validation
+.pytest_cache
+**/__pycache__
+**/*.pyc
+dist
+build
+*.egg-info
+evaluation
+automated_benchmark_results
+benchmark
+diagnostics
+results
+scratch*

phagemine-1.3.1/.zenodo.json

@@ -0,0 +1,21 @@
+{
+  "title": "PhageMine",
+  "version": "1.3.1",
+  "upload_type": "software",
+  "license": "MIT",
+  "creators": [
+    {
+      "name": "Nnaemeka Emmanuel Nnadi",
+      "orcid": "https://orcid.org/0000-0002-8424-4859",
+      "affiliation": "Department of Microbiology, Plateau State University, Bokkos, Plateau State, Nigeria; Centre for Phage Biology and Therapeutics LTD/GTE, Jos, Plateau State, Nigeria"
+    }
+  ],
+  "keywords": [
+    "bacteriophage",
+    "genome annotation",
+    "comparative genomics",
+    "bioinformatics",
+    "INPHARED",
+    "PHANOTATE"
+  ]
+}

phagemine-1.3.1/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+## 1.3.1 — 2026-10-07
+
+- Add the PyPI publishing workflow, refresh the Bioconda recipe, and surface
+  packaged install paths in the README. No functional changes to annotation,
+  gene calling or evidence handling.
+
+## 1.3.0 — 2026-10-04
+
+- Return a failing exit status for failed batch samples, reject empty inputs,
+  and stop Both before discovery when its annotation cohort is incomplete.
+
+- Correct GUI completion checks, Both result loading and sample protein
+  selection; expose operational Doctor checks and provider readiness.
+- Validate input types, reject duplicate uploads, support home paths, bind
+  the launcher to localhost and prepare symlink-free exports on demand.
+- Add built-wheel execution, application-level GUI and real-caller Core
+  smoke checks to CI; include installation resources in source distributions.
+- Retain the PHANOTATE pkg_resources compatibility dependency and document
+  Core-first onboarding and outstanding independent-validation gates.
+
+- Improve multi-resource product naming, suppress identifier-only labels, and
+  prioritize complete 100%-identity reviewed alignments while retaining alternatives.
+- Publish ten-genome full-system benchmarking and a sequence-bound Prokka naming
+  review; retain unresolved cases and avoid claims of accuracy superiority.
+
+- Optional tRNAscan-SE and validated noncoding-RNA GFF3 imports with feature exports.
+- Sequence-validated external GenBank annotation proposals with source/database provenance.
+- Audited manual product, gene and note review in CLI and GUI with regenerated exports.
+- Streaming reproducibility bundles, artifact consistency checks and sampled runtime profiling.
+- Correct cross-genome, negative-strand and CDS-only benchmark imports.
+- Docker build workflow and local development Bioconda recipe.
+- Core-only GUI launcher test isolation.
+
+- Offline database health/version/freshness diagnostics and per-run health reports.
+- Explicit evidence-conflict and external-label review reports, including a GUI filter.
+- Opt-in checksum-validated persistent reuse for single-genome evidence searches.
+- Curator-provenance-bearing benchmark CLI with unresolved review queues and auditable adjudication.
+- Correct tRNAscan-SE help-banner probe and modern-Python container dependency cleanup.
+
+- Accept empty zero-hit tRNAscan-SE tables only with explicit successful-scan statistics.
+
+## 1.2.0 (finalization)
+
+- Fixed IUPAC ambiguity-code handling and provider-specific sequence
+  normalization with auditable provenance and controlled provider outcomes.
+- Established PHANOTATE as the sole primary DNA caller; Pyrodigal and
+  Prodigal-gv remain available for corroboration and conflict detection only.
+- Added deterministic NO_REVIEW, LOW_PRIORITY_REVIEW,
+  MODERATE_REVIEW, and HIGH_PRIORITY_REVIEW tiers while retaining detailed
+  underlying conflict fields.
+- Added a reproducible PHANOTATE-versus-PhageMine structural benchmark.
+- Integrated validated INPHARED nearest-reference genomic context into
+  single-genome and cohort workflows, with Mash screening, optional
+  bidirectional BLASTN similarity, resource manifests, and conservative
+  taxonomy interpretation.
+
+## 1.1.0
+
+- Promote the scientifically hardened development line to the PhageMine 1.1.0
+  package release while retaining functional-fusion rules version 1.8 as an
+  independent annotation-rule version.
+
+- Refine conservative phage functional evidence fusion, including stronger
+  source agreement requirements, safer product normalization, curated phage
+  anchors, conflict handling, and explicit review states.
+
+- Prevent organism-specific or source-phage locus labels from being
+  transferred unsafely into final product names while preserving supporting
+  homolog and family evidence.
+
+- Harden mining and quality-control evidence accounting so short-ORF QC
+  records are idempotent and annotation-evidence totals remain reproducible
+  and auditable.
+
+- Run validated INPHARED nearest-reference whole-genome comparison
+  automatically in `annotate`, `run`, and batch annotation workflows when the
+  INPHARED resource is READY.
+
+- Preserve the existing cohort-level INPHARED comparison in batch discovery
+  workflows while keeping PMFDB/discovery analysis separate from ordinary
+  `annotate`.
+
+- Add an explicit INPHARED pipeline stage and report unavailable resources as
+  SKIPPED rather than silently omitting the comparison.
+
+- Make INPHARED comparative-report insertion idempotent so resumed or repeated
+  report updates do not duplicate the nearest-reference section.
+
+- Correct ordinary batch annotation to invoke the annotation workflow rather
+  than the broader single-genome `run` workflow.
+
+- Extend regression coverage for INPHARED workflow consumption, batch command
+  semantics, comparative-report idempotency, and progress reporting.
+
+## 1.0.6
+
+- Separate domain evidence notes from final product names; organism-specific
+  Pfam descriptions remain in raw evidence and cannot become phage products.
+- Label functional strength as rule-based and explicitly uncalibrated.
+- Remove the universal 70% genus rule, abstain from numerical-taxonomy
+  interpretation for partial/poorly aligned sequences, and stop describing the
+  internal BLASTN calculation as VIRIDIC output.
+- Mark hallmark results as annotation-text screening rather than independent
+  profile validation or genome-completeness estimates.
+- Add truth-set benchmark inputs and calibration-ready performance outputs.
+- Add reproducible environment metadata, declared plotting/test dependencies,
+  package metadata, and automated multi-platform checks.
+
+## 1.0.5
+
+- Isolate tests from the persistent user database registry and make registry
+  writes atomic with a recoverable backup.
+- Add `phagemine doctor --deep` to open and validate the registered PHROGs
+  MMseqs2 and PyHMMER databases, rather than inferring readiness from filenames.
+- Report MMseqs2 and PyHMMER PHROGs backend status in normal run progress.
+- Promote repeated, concordant, high-coverage annotated PHROGs profile hits
+  over a single unannotated profile and add Ijeoma-derived HNH/terminase
+  regression cases.
+- Keep functional uncertainty separate from gene-call confidence; exact
+  PHANOTATE/Prodigal coordinate and strand agreement is now reported
+  consistently and is never converted into a possible-false-ORF flag.
+- Add gene-call confidence and independent functional/gene-call review fields
+  to researcher-facing annotation tables.
+- Propagate `--threads` from `phagemine batch` into every single-genome run and
+  repair nested progress-stage reporting.
+
+## 1.0.4
+
+- Add sensitive PHROGs profile-HMM searching through PyHMMER while retaining
+  the existing MMseqs2 search.
+- Extract and register the existing `all_phrogs.h3m` from the checksum-pinned
+  Pharokka PHROGs distribution; no additional database download is required.
+- Deduplicate identical PHROG calls across MMseqs2 and PyHMMER so one
+  biological source cannot be counted twice, while recording backend
+  corroboration and search-specific statistics.
+- Add `phagemine databases attach-phrogs-hmm` for attaching an already
+  installed Pharokka `all_phrogs.h3m` to an existing PHROGs registration.
+- Extend PHROGs refresh/resume to replace older PHROGs evidence rather than
+  silently duplicating it, and allow targeted profile-HMM refreshes without
+  rerunning gene prediction or unrelated database searches.
+- Report PyHMMER and sensitive PHROGs profile-search readiness explicitly in
+  `phagemine doctor`.
+
+## 1.0.3
+
+- Replace the invalid `1 - Mash distance` pseudo-similarity with Mash-only
+  candidate screening followed by VIRIDIC-compatible bidirectional BLASTN
+  whole-genome intergenomic similarity.
+- Report query/reference aligned fractions, genome-length ratio, explicit
+  species/genus thresholds, threshold provenance, and cautious numerical-
+  taxonomy interpretations.
+- Add the completed INPHARED numerical-taxonomy table and downloads to the
+  primary `report.html` after comparative discovery finishes.
+- Add simple Prokka-style `gene`, `product`, `EC_number`, evidence-source and
+  biotechnology-relevance columns. Gene symbols and EC numbers are transferred
+  only from explicit, strong, non-conflicting evidence.
+- Normalize defensible phage terms including major capsid, Hoc-like head
+  decoration, head-scaffolding, terminase, endolysin and helicase products;
+  suppress unsupported fungal, apoptosis and bacterial-envelope labels.
+- Identify Hoc-like decoration proteins as potential capsid-display candidates
+  in a separate application note that explicitly requires experimental
+  confirmation.
+- Correct the progress denominator for runs that include PHANOTATE/Prodigal
+  reconciliation and alternative-ORF adjudication.
+- Allow Core `run` to complete without invoking MMseqs2 discovery when no
+  comparative resources are registered.
+
+## 1.0.2
+
+- Simplify the primary annotation table to protein ID, coordinates, strand,
+  length, plain-language classification, proposed function, confidence, best
+  evidence, and a review flag. Detailed evidence remains in the dedicated
+  classification and protein-detail outputs.
+- Add `annotated_proteins.faa` with the proposed product, coordinates, strand,
+  and confidence in every FASTA header.
+- Make full single-genome `run` perform PHANOTATE/Prodigal comparison and write
+  explicit gene-call confidence and review tables without silently deleting
+  caller-specific ORFs.
+- Place results in `./<input stem>_phagemine_results` when `--output` is not
+  supplied; an explicit output path continues to take precedence.
+- Add a duplicate-collapsed INPHARED summary and distinguish exact sketch
+  matches from nearest-neighbour screens while retaining the accession-level
+  audit table.
+- Extend annotation comparison imports to Pharokka, Phold, multiPhATE2, and
+  Prokka, with separate gene-model and product-name comparisons.
+- Add an explicit six-tier evidence hierarchy to the detailed classification
+  output; the hierarchy contains no structural-search dependency.
+- Add conservative hallmark-system checks and a single prioritized
+  `annotation_review.tsv` combining function conflicts, disputed gene calls,
+  and hallmark components not established by current evidence.
+- Confirm zero-distance INPHARED matches by built-in exact nucleotide,
+  reverse-complement, and rotation-equivalence checks when the reference
+  sequence is available; do not infer ANI or taxonomy from Mash.
+- Record checksummed external-tool inputs and hallmark-name comparisons in the
+  reproducible annotation benchmark output.
+- Do not infer or report phage lifestyle.
+
+## 1.0.1
+
+- Synchronize the release version with the post-1.0.0 database installer and
+  INPHARED functionality published on GitHub.
+- Make executable validation fail closed: a binary is `READY` only when its
+  version/help probe exits successfully. Dynamic-linker failures and other
+  runtime errors are now reported as `BROKEN` with their diagnostic text.
+- Make `phagemine doctor` return a non-zero process status when a required
+  production executable is missing or broken; Prodigal and table2asn remain
+  optional for the normal annotation and pre-submission workflows.
+- Distinguish an installed-but-blocked database from a database that is not
+  installed, and recommend executable repair instead of unnecessary database
+  reinstallation.
+- Load unknown future registry resource types without crashing access to all
+  existing registered databases.
+- Require Mash in the Bioconda run dependencies for whole-genome INPHARED
+  comparison.
+
+- Add `phagemine databases install pfam`, `vogdb`, `swissprot`, `phrogs`,
+  `pmfdb`, and `inphared`.
+- Add `phagemine databases install --all` with resumable downloads, published
+  checksum verification, database preparation, manifests, registration, and
+  fail-closed readiness validation.
+- Add post-install database guidance to top-level help, the Bioconda post-link
+  template, and `phagemine doctor` recommendations.
+- Build PMFDB and the whole-genome Mash resource from the checksum-pinned
+  INPHARED 7 April 2026 release, with conservative annotation semantics,
+  resource QC, provenance, automatic discovery use, and nearest-phage outputs.
+
+## 1.0.0
+
+The first stable public release. This release provides evidence-based
+single-genome annotation, batch annotation, Discovery Mode, and Both Mode;
+PHANOTATE integration; Pfam/VOGDB/Swiss-Prot/PHROGs evidence; conservative
+evidence fusion and classification; genomic context/modules; candidate
+ranking; PMF clustering and recurrence; PMFDB validation; discovery ranking;
+publication figures with source data; HTML reports; protein/CDS retrieval;
+GenBank pre-submission packaging; resume/checkpointing; and evidence reuse
+with provenance.
+
+The release does not bundle external evidence databases, PMFDB, or research
+datasets. Unknown and no-match states are not interpreted as novelty.
+
+## 1.0.0rc1 (historical)
+
+This release candidate freezes the v1.0 computational workflow. It provides
+the lightweight PhageMine Core FASTA-to-report workflow, optional evidence
+integration, PMF/PMFDB integration when explicitly requested, local GenBank
+pre-submission validation, and submission revision from an explicit correction
+file without rerunning biological analysis.
+
+The release does not bundle external evidence databases, PMFDB, or research
+datasets. See `docs/limitations.md` for interpretation and validation limits.

phagemine-1.3.1/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+title: PhageMine
+version: 1.3.1
+type: software
+message: "If you use PhageMine, please cite this release."
+authors:
+  - family-names: Nnadi
+    given-names: Nnaemeka Emmanuel
+    orcid: https://orcid.org/0000-0002-8424-4859
+    affiliation: Department of Microbiology, Plateau State University, Bokkos, Plateau State, Nigeria; Centre for Phage Biology and Therapeutics LTD/GTE, Jos, Plateau State, Nigeria
+license: MIT
+repository-code: "https://github.com/emmannaemeka/PhageMine"
+url: "https://github.com/emmannaemeka/PhageMine"
+keywords:
+  - bacteriophage
+  - genome annotation
+  - bioinformatics
+date-released: 2026-10-07

phagemine-1.3.1/Dockerfile

@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1.7
+FROM mambaorg/micromamba:2.3.2
+
+LABEL org.opencontainers.image.title="PhageMine" \
+      org.opencontainers.image.source="https://github.com/emmannaemeka/PhageMine" \
+      org.opencontainers.image.version="1.3.0.dev0"
+
+COPY --chown=$MAMBA_USER:$MAMBA_USER environment.yml /tmp/environment.yml
+# The optional CA secret is for managed environments with a trusted proxy.
+# Ordinary Docker builds use the base image's public CA store.
+RUN --mount=type=secret,id=proxy_ca \
+    if [ -f /run/secrets/proxy_ca ]; then export SSL_CERT_FILE=/run/secrets/proxy_ca PIP_CERT=/run/secrets/proxy_ca CURL_CA_BUNDLE=/run/secrets/proxy_ca CONDA_SSL_VERIFY=/run/secrets/proxy_ca; fi; \
+    micromamba install --yes --name base --file /tmp/environment.yml && \
+    micromamba clean --all --yes
+
+COPY --chown=$MAMBA_USER:$MAMBA_USER . /opt/phagemine
+WORKDIR /opt/phagemine
+ARG MAMBA_DOCKERFILE_ACTIVATE=1
+RUN --mount=type=secret,id=proxy_ca \
+    if [ -f /run/secrets/proxy_ca ]; then export PIP_CERT=/run/secrets/proxy_ca; fi; \
+    python -m pip install --no-cache-dir . && \
+    python -m pip uninstall --yes textwrap3 backports.tempfile && python -m pip check
+
+ENV PHAGEMINE_REGISTRY_PATH=/data/resources.json
+WORKDIR /data
+ENTRYPOINT ["/usr/local/bin/_entrypoint.sh", "phagemine"]
+CMD ["--help"]

phagemine-1.3.1/LICENSE

@@ -0,0 +1,21 @@
+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.

phagemine-1.3.1/MANIFEST.in

@@ -0,0 +1,9 @@
+include environment.yml CITATION.cff CHANGELOG.md RELEASE_VALIDATION.md
+include .zenodo.json
+include Dockerfile .dockerignore
+recursive-include packaging *.yaml *.sh
+recursive-include examples *.fasta *.json
+recursive-include docs *.md *.png *.svg *.pdf *.tsv *.py
+include RESEARCHER_VALIDATION.md
+include tools/smoke_installed.py
+include tools/publish_verified_release.py

phagemine-1.3.1/PKG-INFO

@@ -0,0 +1,171 @@
+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).

phagemine-1.3.1/README.md

@@ -0,0 +1,114 @@
+# 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).