# S. pneumoniae De Novo CPS Locus Discovery & Database Construction

This presentation validates `LocusPredictor`, `Clusterer`, `Loci` (`GraphBatch`), and `LocusMatcher` across a 4-stage ***Streptococcus pneumoniae* capsular polysaccharide (CPS) locus discovery and de novo database construction** pipeline.

Rather than relying on pre-trimmed reference databases or global nucleotide alignment, SeroGen extracts CPS biosynthetic operons **de novo** from unannotated sequences and whole chromosomes (including fragmented/contig-split assemblies), classifies divergent polysaccharide genes with `GeneRoleClassifier`, clusters them into functional orthogroups via hybrid Markov Clustering (`Clusterer(mode="mcl")`), and compresses the resulting `Loci` batch into an indexed de novo database and directed consensus pan-locus graph (`Loci.as_pan_graph`).

---

## Key Takeaways

- **De Novo CPS Locus Discovery Across Mechanisms (`LocusPredictor`)**: Automatically segments both Wzy-dependent (`CPS_WZY`, anchored by `wzg`/`cpsA`–`wze`/`cpsD`, `wzx`, and `wzy`) and synthase-dependent (`CPS_SYNTHASE`, e.g., Type 3 capsule) loci directly from unannotated sequences and complete RefSeq chromosomes (`100%` recall on encapsulated strains and `100%` specificity on the unencapsulated `R6` rough negative control).
- **Hybrid CNN-Rescued MCL Orthogroup Clustering (`Clusterer`)**: `Loci.cluster_genes` combines `RandstrobeIndex` strobemer seeding, `MMSEQS12` reduced-alphabet \\(12^4\\) CSR + ungapped BLOSUM62 diagonal prefiltering, SIMD-parallel Smith-Waterman-Gotoh (`PairwiseAligner`), **role-gated `GeneRoleClassifier` active-site motif rescue**, and sparse Markov Clustering (`mode="mcl"`) to group divergent glycosyltransferases (`GT`), flippases (`Wzx`), and polymerases (`Wzy`) across the sequence twilight zone.
- **Zero-Copy Pan-Locus Graph Data Structures (`Loci` / `GraphBatch`)**: Bit-packed 32-bit `GeneNode`s (`CLUSTER_ID`, `ROLE_ID`, `STRAND`, `IS_FRAMESHIFT`) and `IntergenicEdge`s (`ORIENTATION`, `GAP_BIN`) compress into a directed consensus pan-CPS CSR network via `Loci.as_pan_graph()` (visualized in 2D using `LayoutEngine`).
- **Fragmented Contig-Split Stitching & Novelty Detection**: `LocusPredictor(stitch_contig_splits=True)` achieves **100% recovery** across artificial intergenic and mid-ORF contig breaks (`MatchType.FRAGMENTED_VARIANT`), while `LocusMatcher` flags held-out novel locus architectures via `Match.is_novel` (`MatchType.GENE_VARIANT`) and falls back to the closest intra-serogroup relative.

## Run Locally

```bash
# Present as interactive slideshow
uv run --with marimo --with altair marimo run scripts/benchmark_spneumo_db.py

# Edit notebook cells
uv run --with marimo --with altair marimo edit scripts/benchmark_spneumo_db.py
```