{"id":50415179,"url":"https://github.com/biostochastics/codontopo","last_synced_at":"2026-05-31T05:30:22.811Z","repository":{"id":353868496,"uuid":"1210234405","full_name":"biostochastics/codontopo","owner":"biostochastics","description":"Codon Geometry Validation \u0026 Prediction Engine — algebraic structure of genetic codes in GF(2)^6","archived":false,"fork":false,"pushed_at":"2026-04-26T01:04:13.000Z","size":20971,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T01:21:17.557Z","etag":null,"topics":["codon-optimization","genetics","genome","graph","topology"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biostochastics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T08:02:13.000Z","updated_at":"2026-04-26T01:04:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/biostochastics/codontopo","commit_stats":null,"previous_names":["biostochastics/codontopo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/biostochastics/codontopo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biostochastics%2Fcodontopo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biostochastics%2Fcodontopo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biostochastics%2Fcodontopo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biostochastics%2Fcodontopo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biostochastics","download_url":"https://codeload.github.com/biostochastics/codontopo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biostochastics%2Fcodontopo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33720897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codon-optimization","genetics","genome","graph","topology"],"created_at":"2026-05-31T05:30:22.249Z","updated_at":"2026-05-31T05:30:22.803Z","avatar_url":"https://github.com/biostochastics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  # CODON-TOPO\n\n  **Codon Geometry Validation \u0026 Prediction Engine**\n\n  [![Version](https://img.shields.io/badge/version-0.4.0-blue)]()\n  [![Tests](https://img.shields.io/badge/tests-432%20passing-success)]()\n  [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A596%25-brightgreen)]()\n  [![Python](https://img.shields.io/badge/python-3.11%2B-yellow)]()\n  [![License: CC BY-NC 4.0](https://img.shields.io/badge/license-CC%20BY--NC%204.0-lightgrey)](LICENSE)\n\n\u003c/div\u003e\n\n---\n\n## What is CODON-TOPO?\n\nCODON-TOPO validates the algebraic structure of genetic codes when encoded as 6-bit binary vectors in GF(2)^6. It provides a complete, reproducible pipeline for the analyses described in:\n\n\u003e **Robust error-minimization in the genetic code across physicochemical metrics and variant codes: a graph-theoretic analysis in GF(2)^6**\n\u003e Paul Clayworth \u0026 Sergey Kornilov (2026). Manuscript prepared for submission to the *Journal of Theoretical Biology*; PDF compiles from `output/manuscript.typ` (Elsevier-Harvard reference style). Highlights, CRediT statement, generative-AI-use declaration, and ethical statement are included in the manuscript end-matter.\n\n### Key Findings\n\n| Status | Count | Highlights |\n|--------|-------|------------|\n| **Supported** | 4 | Cross-metric coloring optimality (4 metrics, p ≤ 0.006); per-table preservation (**26 of 27** NCBI tables, mean quantile 1.4%; standard-code-proximity audit confirms variant tables are independently optimal); ρ-robustness across the full Hamming graph H(3,4) = K₄ □ K₄ □ K₄; topology-avoidance depletion under both Q₆ (encoding-dependent) and **encoding-independent H(3,4)** adjacency (RR 0.28–0.33, permutation p ≤ 10⁻⁴, robust to clade exclusion and to both new-disconnection and Δβ₀\u003e0 definitions) |\n| **Suggestive** | 1 | tRNA enrichment for reassigned amino acid (worst-case MIS Stouffer p = 0.045 across 24 pairings; 18 tRNAscan-SE–verified genomes); the 4-pairing topology-breaking-restricted subset alone is underpowered (Stouffer p = 0.43) |\n| **Exploratory** | 4 | Bit-position bias (deduplicated p = 0.075); mechanism boundary conditions (3-tier: gene duplication / stem shortening / anticodon modification); Atchley F3/Serine convergence; disconnection catalogue (Thr / Leu / Ala / Ser; Trp Table 32 = filtration-only exception) |\n| **Rejected** | 3 | Serine min-distance-4 invariant (encoding-dependent); PSL(2,7); holomorphic embedding |\n| **Falsified** | 1 | KRAS-Fano clinical prediction (p = 1.0 on n = 1,670 MSK-IMPACT mutations) |\n| **Tautological** | 2 | Two-fold bit-5 filtration (encoding-dependent); four-fold prefix filtration |\n\n**Notation:** The full single-nucleotide mutation graph is consistently written as **H(3,4) = K₄ □ K₄ □ K₄** (the Hamming graph; 64 vertices, regular degree 9, 288 undirected edges) rather than the ambiguous K₄³. Q₆ is a 192-edge subgraph of H(3,4); the remaining 96 within-nucleotide diagonal edges complete H(3,4). CLI flags retain the legacy `k43` spelling (e.g. `topology-avoidance-k43`) for backward compatibility.\n\n**Encoding sensitivity (24 base-to-bit bijection sweep):** The Q₆ topology-avoidance result is encoding-dependent — 8 of 24 bijections give a Q₆ candidate-landscape rate near 36% (rather than 73% under the default encoding) and no statistically significant depletion. The H(3,4) result is encoding-independent and **is reported as the primary topology-avoidance test**; Q₆ is now framed as a coordinate-dependent decomposition. Q₆ remains useful for the ρ-sweep (continuous interpolation between Q₆ and H(3,4)).\n\n**Conditional logit (M3 phys+topo) under both topology encodings:** Decisively favored over single-feature models. Under encoding-dependent Q₆ topology: ΔAICc(M1→M3) = 108.2, ΔAICc(M2→M3) = 89.1. Under encoding-independent H(3,4) topology (verifying that the result is not an artifact of the Q₆ encoding): ΔAICc(M1→M3_H(3,4)) = **91.3**, ΔAICc(M2_H(3,4)→M3_H(3,4)) = **95.1** — both decisive (\u003e10) and similar in magnitude to the Q₆ counterparts. Adding the tRNA-distance proxy (M4) does not improve fit (LR = 0.12, p = 0.73). Spearman ρ between Δ_phys and Δ_topo across the 1,280-move candidate landscape = 0.15 (largely independent predictors). Conditional-logit clade-exclusion sensitivity (per Sengupta et al. 2007, refitting M1-M4 with each major clade dropped) and posterior-predictive validation (observed 0.076 vs simulated 0.077; pp p = 0.60) confirm robustness.\n\n**Restricted-candidate sensitivity:** Refitting M1-M4 on candidate sets restricted to biologically plausible moves (target AA already accessible at Hamming distance ≤ d) shows the qualitative claim \"topology adds value beyond physicochemistry\" survives at every threshold tested. Under the primary d=2 filter (≈727 candidates per choice set), ΔAICc(M1→M3) = 60 and ΔAICc(M2→M3) = 77, both well above the conventional ΔAICc\u003e10 reference. Under the most stringent d=1 filter (≈275 candidates), ΔAICc(M1→M3) shrinks to 14 but stays above 10; ΔAICc(M2→M3) stays at 73. The unrestricted ΔAICc magnitudes are upper bounds; the d=2 filter gives a more biologically-calibrated effect size.\n\n**Methodological caveats explicitly disclosed in Limitations:**\n- Survivorship bias: cross-sectional NCBI data cannot distinguish \"selection against attempting topology-breaking moves\" from \"selection against the lineages that attempted them\"\n- Independence-of-irrelevant-alternatives (IIA) assumption in conditional logit (used as explanatory rather than predictive tool)\n- Family-wise multiple-comparison correction within prespecified analysis families (no spurious global-Bonferroni claim)\n- Tables 1/11 and 27/28 share identical sense-codon mappings (27 NCBI tables = 25 distinct sense-codon colorings)\n- Per-table block-preserving null is partly dominated by near-standard permutations for variants with few reassignments — addressed by standard-code-proximity audit (Supplement)\n\nRun `codon-topo claims` for the full hierarchy with p-values and justifications.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python**: 3.11+\n- **Package manager**: [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- **Optional**: R 4.5+ with `ggplot2`, `ggpubr`, `viridis`, `patchwork` for publication figures\n- **Optional**: tRNAscan-SE 2.0.12 for tRNA gene verification\n\n### Installation\n\n```bash\ngit clone https://github.com/biostochastics/codontopo.git\ncd codontopo\n\n# With uv (recommended)\nuv sync --all-extras\nuv run codon-topo --help\n\n# With pip\npip install -e \".[dev]\"\ncodon-topo --help\n```\n\n### Run the Full Pipeline\n\n```bash\n# Run everything and generate manuscript_stats.json\ncodon-topo all --output-dir=./output --seed=135325\n\n# Individual analyses\ncodon-topo coloring --n=10000          # Coloring optimality Monte Carlo\ncodon-topo metric-sensitivity          # Cross-metric (Grantham, Miyata, PR, KD)\ncodon-topo rho-sweep                   # Rho robustness (Q6 -\u003e K4^3)\ncodon-topo per-table                   # All 27 NCBI translation tables\ncodon-topo topology-avoidance          # Topology avoidance (Q6)\ncodon-topo topology-avoidance-k43      # Topology avoidance (K4^3, encoding-independent)\ncodon-topo condlogit                   # Conditional logit models (M1-M4)\ncodon-topo condlogit-restricted        # Restricted-candidate sensitivity (delta_trna\u003c=1,2,3)\ncodon-topo trna                        # tRNA enrichment test\ncodon-topo mis-analysis                # Maximal independent set analysis\ncodon-topo phylo-sensitivity           # Clade-exclusion robustness\ncodon-topo claims                      # View claim hierarchy\n```\n\n### Run the CodonSafe Cross-Study Reanalysis\n\n```bash\n# Requires raw data in data/codonsafe/ (see DATA_MANIFEST.md)\npip install -e \".[codonsafe]\"\ncodon-topo codonsafe\n```\n\n### Run the Test Suite\n\n```bash\npython3.11 -m pytest tests/ -q                    # all tests\npython3.11 -m pytest tests/ --cov=codon_topo      # with coverage\npython3.11 -m pytest tests/test_regression.py -v   # regression suite (105 tests)\n```\n\n\u003e **Note**: Use `python3.11 -m pytest` if your system default Python differs from where dev dependencies are installed.\n\n### Generate Publication Figures\n\n```bash\nRscript src/codon_topo/visualization/R/strengthened_figures.R\n```\n\n---\n\n## Reproducibility\n\nThe core design principle: **a user who clones this repo should be able to regenerate every number in the manuscript.**\n\n```bash\n# Full reproducibility from scratch\ngit clone https://github.com/biostochastics/codontopo.git\ncd codontopo\nuv sync --all-extras\nuv run codon-topo all --output-dir=./output --seed=135325\n# -\u003e generates output/manuscript_stats.json\n# -\u003e manuscript.typ reads all inline statistics from this JSON\n```\n\nThe `manuscript_stats.json` file contains every statistic cited in the paper. The Typst manuscript (`output/manuscript.typ`) reads this file and renders all inline numbers dynamically:\n\n```typst\n#let stats = json(\"manuscript_stats.json\")\n// All tables and inline stats reference stats.* fields\n```\n\nRandom seed: **135325** (all Monte Carlo analyses).\n\n---\n\n## Architecture\n\n```\ncodon-topo all\n    |\n    +-- Filtration (WS1) .................. Two-fold/four-fold degeneracy checks\n    +-- Disconnections (WS1) .............. Persistent homology catalogue\n    +-- Coloring Optimality (WS1) ......... Block-preserving Monte Carlo\n    |     +-- Multi-metric sensitivity .... Grantham, Miyata, PR, KD\n    |     +-- Rho robustness sweep ........ Q6 -\u003e H(3,4) interpolation\n    |     +-- Per-table optimality ........ 27 NCBI tables + BH-FDR\n    |     +-- Per-table proximity audit ... dH-conditional vs unconditional quantile\n    |     +-- Score decomposition ......... By nucleotide position\n    +-- Reassignment Analysis (WS2) ....... Database, Hamming paths, bit bias\n    +-- Topology Avoidance (WS6) .......... Q6 + H(3,4), 2x2 definitions audit,\n    |                                       24-encoding sweep, denominator sensitivity\n    +-- tRNA Evidence (WS1) ............... Fisher-Stouffer + MIS enumeration\n    |                                       + topology-breaking subset (n=4)\n    +-- Phylogenetic Sensitivity (WS6) .... Clade-exclusion robustness\n    +-- Conditional Logit (WS6) ........... M1-M4 (Q6) + M2k43, M3k43 (H(3,4))\n    |     +-- Encoding robustness ......... Q6 vs H(3,4) ΔAICc comparison\n    |     +-- Clade-exclusion sensitivity . 7 clade regimes per Sengupta et al. 2007\n    |     +-- Restricted-candidate sens. .. delta_trna\u003c=1,2,3 biological-plausibility filter\n    |     +-- Posterior predictive ........ Observed vs simulated topology rate\n    +-- Depth Calibration (WS3) ........... Epsilon-age correlation\n    +-- KRAS-Fano (WS4) .................. cBioPortal enrichment (negative)\n    +-- Claims + Catalogue (WS5) .......... 15 claims, evidence grading\n    |\n    +-\u003e output/manuscript_stats.json ...... Consolidated stats for Typst\n    +-\u003e output/*.json ..................... Per-analysis detailed results\n```\n\n### Package Structure\n\n| Component | Path | Role |\n|-----------|------|------|\n| CLI | `src/codon_topo/cli.py` | Click-based CLI with 18 subcommands |\n| Encoding | `src/codon_topo/core/encoding.py` | GF(2)^6, Hamming distance, all 24 encodings |\n| Genetic codes | `src/codon_topo/core/genetic_codes.py` | All 27 NCBI translation tables (codes 1-6, 9-16, 21-33) |\n| Filtration | `src/codon_topo/core/filtration.py` | Two-fold (bit-5) and four-fold (prefix) checks |\n| Homology | `src/codon_topo/core/homology.py` | Connected components, disconnection catalogue |\n| Embedding | `src/codon_topo/core/embedding.py` | Root-of-unity map GF(2)^6 -\u003e C^3 |\n| Fano | `src/codon_topo/core/fano.py` | XOR triple computation |\n| Coloring optimality | `src/codon_topo/analysis/coloring_optimality.py` | Monte Carlo, rho sweep, per-table, multi-metric |\n| Null models | `src/codon_topo/analysis/null_models.py` | Models A/B/C/C_extended |\n| Reassignment DB | `src/codon_topo/analysis/reassignment_db.py` | Database, Hamming paths, bit-position bias |\n| Topology avoidance | `src/codon_topo/analysis/synbio_feasibility.py` | Q6 + K4^3 tests, phylogenetic sensitivity |\n| Evolutionary simulation | `src/codon_topo/analysis/evolutionary_simulation.py` | Conditional logit M1-M4, order-averaging |\n| tRNA evidence | `src/codon_topo/analysis/trna_evidence.py` | Fisher-Stouffer, MIS via Bron-Kerbosch |\n| CodonSafe | `src/codon_topo/analysis/codonsafe/` | Cross-study reanalysis of 8 recoding datasets |\n| Statistical utils | `src/codon_topo/analysis/statistical_utils.py` | Beta CIs, risk ratios, quantile CIs |\n| Visualization | `src/codon_topo/visualization/` | CSV export + R ggplot2 scripts |\n| Claims | `src/codon_topo/reports/claim_hierarchy.py` | Single source of truth for 15 claims |\n| Catalogue | `src/codon_topo/reports/catalogue.py` | Evidence grading across workstreams |\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `codon-topo all` | Run everything, generate `manuscript_stats.json` |\n| `codon-topo filtration` | Two-fold/four-fold filtration checks |\n| `codon-topo disconnections` | Disconnection catalogue (persistent homology) |\n| `codon-topo coloring` | Hypercube coloring Monte Carlo |\n| `codon-topo metric-sensitivity` | Cross-metric sensitivity (4 metrics) |\n| `codon-topo rho-sweep` | Rho robustness (Q6 -\u003e K4^3) |\n| `codon-topo per-table` | Per-table optimality (27 NCBI tables) |\n| `codon-topo decompose` | Score decomposition by nucleotide position |\n| `codon-topo topology-avoidance` | Topology avoidance test (Q6) |\n| `codon-topo topology-avoidance-k43` | Topology avoidance test (K4^3) |\n| `codon-topo condlogit` | Conditional logit model comparison (M1-M4) |\n| `codon-topo condlogit-restricted` | Restricted-candidate-set sensitivity (delta_trna ≤ d) |\n| `codon-topo phylo-sensitivity` | Clade-exclusion sensitivity analysis |\n| `codon-topo trna` | tRNA enrichment test |\n| `codon-topo mis-analysis` | Maximal independent set enumeration |\n| `codon-topo bit-bias` | Bit-position bias test |\n| `codon-topo kras` | KRAS-Fano enrichment test (negative) |\n| `codon-topo codonsafe` | CodonSafe cross-study reanalysis |\n| `codon-topo claims` | View claim hierarchy |\n\nAll subcommands support `--json` for machine-readable output. Interactive mode uses rich tables.\n\n---\n\n## Workstreams\n\n| WS | Name | CLI commands | Status |\n|----|------|-------------|--------|\n| **WS1** | Core Replication | `filtration`, `disconnections`, `coloring`, `metric-sensitivity`, `rho-sweep`, `per-table`, `decompose` | Complete |\n| **WS2** | Reassignment Directionality | `bit-bias` | Complete |\n| **WS3** | Evolutionary Depth | _(in `all`)_ | Complete |\n| **WS4** | KRAS/COSMIC | `kras` | Complete (negative) |\n| **WS5** | Prediction Catalogue | `claims` | Complete |\n| **WS6** | Topology \u0026 Synbio | `topology-avoidance`, `topology-avoidance-k43`, `condlogit`, `phylo-sensitivity`, `codonsafe` | Complete |\n\n---\n\n## Null Models\n\n| Model | What it tests | CLI |\n|-------|---------------|-----|\n| **Freeland-Hurst** | Is the coloring optimal? Block-preserving shuffle | `coloring` |\n| **Class-size** | Weaker null (degeneracy-only, no block contiguity) | `coloring --null=class_size` |\n| **Model C** | Is the encoding special? All 24 base-to-bit mappings | `disconnections --extended` |\n| **Table-preserving permutation** | Does evolution avoid topology disruption? | `topology-avoidance` |\n| **Conditional logit** | Is topology an independent predictor? | `condlogit` |\n\n---\n\n## Technology Stack\n\n- **Python 3.11+**, NumPy, SciPy for core computation\n- **click + rich** for CLI\n- **pytest + hypothesis** for property-based testing (432 tests, \u003e=96% coverage)\n- **ggplot2 + ggpubr** (R) for publication figures (300 DPI, colorblind-friendly viridis)\n- **Typst** for manuscript typesetting (reads `manuscript_stats.json` for dynamic stats)\n- **tRNAscan-SE 2.0.12** + Infernal 1.1.4 for tRNA verification (18 genomes across 5 variant codes + 3 standard-code controls)\n- **Biopython** for GenBank parsing (CodonSafe reanalysis)\n\n---\n\n## Usage Examples\n\n```python\nfrom codon_topo import (\n    codon_to_vector, hamming_distance, STANDARD, get_code,\n    analyze_filtration, disconnection_catalogue, embed_codon,\n    is_fano_line, fano_partner, monte_carlo_null,\n    CLAIM_HIERARCHY, supported_claims,\n)\n\n# Encode a codon as a 6-bit vector\ncodon_to_vector('GGU')  # (1, 1, 1, 1, 0, 1)\n\n# Check the KRAS Fano line (XOR = 0)\nis_fano_line('GGU', 'GUU', 'CAC')  # True\n\n# Run the coloring optimality Monte Carlo\nresult = monte_carlo_null(n_samples=10000, seed=135325)\n# {'quantile_of_observed': 0.6, 'p_value_conservative': 0.006, ...}\n\n# Query the claim hierarchy\nfor claim in supported_claims():\n    print(claim.id, claim.evidence_p_value)\n```\n\n---\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [`CLAUDE.md`](CLAUDE.md) | AI/contributor guidance |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Module dependency graph |\n| [`data/codonsafe/DATA_MANIFEST.md`](data/codonsafe/DATA_MANIFEST.md) | Raw data provenance for cross-study reanalysis |\n\n---\n\n## License\n\nReleased under the [Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)](LICENSE) license. You may share and adapt this work with attribution, but commercial use requires a separate license — contact the authors.\n\nTo cite, see [`CITATION.cff`](CITATION.cff) or the bibliography entry generated by GitHub's \"Cite this repository\" button.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Quick Start](#quick-start)** \u0026bull;\n**[CLI Reference](#cli-reference)** \u0026bull;\n**[Reproducibility](#reproducibility)** \u0026bull;\n**[Architecture](#architecture)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiostochastics%2Fcodontopo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiostochastics%2Fcodontopo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiostochastics%2Fcodontopo/lists"}