GenBank Feature Parser & Annotation Engine

A Biopython-powered genome-annotation query engine, validation suite, and CLI toolset (gbparse) for parsing, validating, analyzing, and mining GenBank flatfiles (.gbff, .gbk, .gb, .txt).

---

Key Capabilities & Biological Semantics

• Standard-Compliant Core: Built on Biopython (Bio.SeqIO) with a typed dataclass model (GenBankDocument, GenBankRecord, GenBankFeature).
• Faithful Biological Locations: Preserves FeatureLocation and CompoundLocation (join/order), calculating biological feature length (len(location)) and extracting biological coding sequences via SeqFeature.extract().
• GFF3 Export: Correctly computes CDS translation phase ($0, 1, 2$) across multi-exon/joined segments in 5' $\rightarrow$ 3' transcription order, emits complete ##sequence-region extents, and handles ordinary features without artificial parent splits.
• QC & Semantic Validation: Verifies translation integrity against genetic codes (transl_table) and codon_start offsets, with structured severity findings (ERROR, WARNING, INFO) and pseudogene tolerance.
• Unified CLI: Provides gbparse subcommands for feature search, valid local sub-region extraction, annotation diffing, genetic-code-aware codon usage, annotation-based candidate phylogenetic markers, CRISPR/Cas annotation scanning, and declarative discovery.
• MEOR Evidence Engine: Scans 48 curated markers across 9 hydrocarbon-degradation, biosurfactant, and bio-emulsifier categories; evaluates 7 genome-level pathway models; and reports same-contig, known-strand candidate clusters with at most N intervening bases.
• Mobilome Evidence Engine: Inventories every parsed record and retains field-level mobilome evidence, replicon declarations, cautious component hypotheses, catalog provenance, and explicit external-analysis handoffs in text, JSON, or normalized TSV.

---

Installation & Setup

Requires Python 3.10+, biopython>=1.80, and pyyaml>=6.0.

# Clone the repository
git clone https://github.com/WhyAdr/genbank-parser.git
cd genbank-parser

# Install in editable mode
pip install -e .

# Or install with test dependencies
pip install -e .[test]

# Optional static neighborhood visualization
pip install -e .[viz]

---

Unified CLI (gbparse) Usage

# 1. Structural & biological validation
gbparse validate input.gbff [--json]

# 2. Record metadata and contig summary
gbparse summary input.gbff

# 3. Export tab-delimited annotation TSV
gbparse extract input.gbff annotations.tsv

# 4. Search features by gene, product, KO, EC, Pfam, or regex
gbparse search input.gbff --gene ladA --format tsv

# 5. Single-locus qualifier deep-dive
gbparse locus input.gbff LOCUS_TAG

# 6. View genomic neighborhood window (+/- N genes, circular-aware)
gbparse neighborhood input.gbff LOCUS_TAG 5

# Emit schema-versioned data and an independent dna_features_viewer figure
gbparse neighborhood input.gbff LOCUS_TAG 5 \
  --format json --output neighborhood.json \
  --visualize --viz-output neighborhood.svg

# 7. Extract genomic sub-region with valid local coordinates
gbparse region input.gbff --locus LOCUS_TAG --flank-genes 5 --output region.gbk

# 8. Export protein FASTA from translations
gbparse fasta input.gbff proteins.faa

# 9. Extract genome FASTA (.fna) and CDS nucleotide slices (.ffn)
gbparse sequence input.gbff --fna genome.fna --ffn cds.ffn

# 10. Calculate codon usage, RSCU, and positional GC
gbparse codon input.gbff --output codon_usage.tsv

# 11. Functional profiling (COG distribution & pathway completeness)
gbparse functional input.gbff --format tsv

# 12. Scan annotation-supported mobilome islands
gbparse discover input.gbff --ruleset mobilome --cluster-gap 5000 --format text

# 13. Multi-genome comparative presence/absence matrix
gbparse compare ./genomes/ --targets "ladA,ssuD,K20938" --output matrix.tsv

# 14. Compare two annotation versions of the same genome
gbparse diff old.gbff new.gbff --format text

# 15. Extract annotation-based candidate phylogenetic markers
gbparse phylo input.gbff --markers all --min-length 50 --output-dir ./markers/

# 16. Scan CRISPR/Cas annotations and spatial proximity
gbparse crispr input.gbff --window 15000

# 17. Convert GenBank to standard GFF3
gbparse gff input.gbff output.gff3 --include-fasta

# 18. Parse Bakta multi-isolate summary tables
gbparse batch-summary ./isolates/ --csv summary.csv

# 19. Scan MEOR and petroleum-microbiology genomic potential
gbparse meor input.gbff --min-weight 2 --format json --output meor.json

# 20. Build a replicon-centric mobilome evidence report
gbparse mobilome input.gbff --format json --min-evidence 2 --output mobilome.json

MEOR confidence and interpretation

gbparse meor uses the following evidence tiers (MEOR catalog 1.1):

• Weight 3: active structured KEGG KO, fully specified structured EC number, or matching gene symbol.
• Weight 2: specific product-annotation regex.
• Weight 1: free-text note match, including KO or EC identifiers found only in /note.

Wildcard ECs are contextual catalog metadata and never produce Weight-3 evidence.

Marker hits indicate annotation-supported genomic encoding potential. They do not prove transcription, enzyme activity, hydrocarbon turnover, biosurfactant production, or field-scale enhanced oil recovery. See the MEOR marker and scientific provenance reference for the curated catalog and its limits.

Mobilome evidence and interpretation

gbparse discover --ruleset mobilome remains the compact annotation-island scanner. gbparse mobilome is different: it inventories chromosomes, declared plasmids, and unresolved records; keeps each matching field/value/pattern; and emits a schema-versioned, replicon-centric report.

gbparse mobilome input.gbff --format text
gbparse mobilome input.gbff --include plasmid --min-evidence 2 --format tsv --output mobilome.tsv
gbparse mobilome input.gbff --database-dir ./reviewed-mobilome-catalog --format json

--include changes detailed presentation only: every parsed record remains in inventory and cross-record scanning. --min-evidence changes eligibility for configured hypotheses but retains lower-tier observations in JSON and TSV. The report treats generic Rep, pXO-numbered, phage-related, AMR-like, and virulence-associated annotations as bounded observations or candidates. It does not establish replication mechanism, plasmid ancestry, phenotype, transfer, co-transfer, expression, antimicrobial resistance, virulence, or phagemid identity. See the mobilome evidence reference for catalog sources, thresholds, and external-tool handoffs.

Neighborhood visualization

Visualization is optional: the core package does not install Matplotlib or a plotting backend. Install genbank-parser[viz] to enable static SVG, PNG, and PDF output. The default figure is a linear-unwrapped feature track, so neighborhoods crossing a circular origin remain continuous. Labels use /gene, then /locus_tag, then a shortened /product; the target CDS is highlighted without using color to encode strand.

dna_features_viewer is the supported single-neighborhood backend in this release. Comparative multi-genome synteny and a possible pyGenomeViz backend are intentionally deferred until explicit alignment or orthology evidence can support links between tracks.

Optional context overlays reuse canonical analysis logic:

gbparse neighborhood input.gbff LOCUS_TAG 8 \
  --visualize --viz-output locus-context.svg \
  --include-feature-types CDS,tRNA,rRNA,ncRNA,tmRNA,mobile_element \
  --color-by ruleset --ruleset mobilome \
  --show-operons --operon-gap 150

Ruleset colors mean only that an existing annotation matched a declared mobilome or xenobiotics term; the legend deliberately labels these as annotation-rule match. Operon links mean same-contig, adjacent, known-common-strand CDSs within the requested intervening-base threshold. Neither overlay demonstrates expression, horizontal transfer, operon co-transcription, or phenotype.

---

Python API Usage

from genbank_parser import read_genbank, extract_xrefs

# Load full document
doc = read_genbank("input.gbff")

# Iterate contigs/records
for rec in doc.records:
    print(f"Contig: {rec.id} ({rec.length:,} bp, topology: {rec.topology}, GC: {rec.gc_content:.1f}%)")
    
# Find a specific locus and extract biological sequence
match = doc.find_locus("ABC_00123")
if match:
    rec, feat = match
    print(feat.gene, feat.product, feat.length)
    nt_seq = feat.extract(rec.seq)
    xrefs = extract_xrefs(feat)
    print("KEGG KOs:", xrefs["kegg_kos"])

MEOR analysis is also available as a data-returning Python API:

from genbank_parser.meor import analyze_meor

report = analyze_meor("input.gbff", min_weight=2, max_gap=200)
print(report.total_hits, report.pathways)

Mobilome analysis is available from its intentionally separate public subpackage:

from genbank_parser.mobilome import analyze_mobilome

report = analyze_mobilome("input.gbff", include="all", min_evidence=2)
print(report.inventory, report.cross_record_hypotheses)

---

Testing & Verification

Run the full pytest test suite:

pytest -v

---

License

MIT License