chronaeon 0.1.0__tar.gz

chronaeon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei L. Kosakovsky Pond and HyphAeon 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.

chronaeon-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: chronaeon
+Version: 0.1.0
+Summary: ChronAeon: Ultra-Fast Molecular Clock Dating, Phylodynamics, and Genomic Surveillance
+Author-email: "Sergei L. Kosakovsky Pond" <spond@temple.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/veg/HyphAeon
+Project-URL: Bug Tracker, https://github.com/veg/HyphAeon/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hyphaeon-core>=0.1.0
+Requires-Dist: biopython>=1.80
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: tn93>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ChronAeon
+
+**The Velocity of Time** — Ultra-fast molecular clock dating, phylodynamics, and genomic surveillance.
+
+ChronAeon operates along the **TAXON / LINEAGE** axis of the HyphAeon foundation model, providing sub-second execution for tree-free continuous manifold dating, attention-derived covariance, and planetary-scale genomic screening.
+
+## Target Audience
+
+Public health agencies (CDC, WHO, UKHSA), outbreak epidemiologists, hospital infection control teams.
+
+## Installation
+
+ChronAeon requires Python ≥ 3.8 and PyTorch ≥ 2.0. At runtime it auto-selects
+the best available device (CUDA → Apple MPS → CPU), so no manual configuration
+is needed regardless of which install path you choose.
+
+```bash
+pip install chronaeon
+```
+
+| Method | Command | Torch | GPU? |
+| :--- | :--- | :--- | :--- |
+| **pip** (default) | `pip install chronaeon` | CUDA-bundled wheel (~550 MB) | NVIDIA GPU if driver matches; else CPU |
+| **pip** (CPU-only) | `pip install torch --index-url https://download.pytorch.org/whl/cpu` then `pip install chronaeon` | CPU-only wheel (~200 MB) | CPU |
+| **Bioconda** | `conda install -c bioconda chronaeon` | CPU-only `pytorch` from conda-forge | CPU only |
+| **NVIDIA Jetson** | See [issue #31](https://github.com/veg/HyphAeon/issues/31) | JetPack-native wheel (cp38 only) | Jetson GPU |
+
+You can always install a specific PyTorch build before installing ChronAeon if
+none of the above defaults suit your system (e.g. a particular CUDA version,
+a custom wheel, or a CPU-only build on a server without GPU).
+
+> [!NOTE]
+> **Model weights** are downloaded automatically from [Hugging Face](https://huggingface.co/datamonkey/hyphaeon)
+> on first use (cached in `~/.cache/hyphaeon/`). No authentication or token is
+> required. Use `--model-variant viral` to select the viral-tuned variant, or
+> `--weights /path/to/checkpoint` to use a local file.
+
+## CLI Subcommands
+
+| Command | Aliases | Description |
+| :--- | :--- | :--- |
+| `chronaeon date` | `dating`, `clock`, `mrca` | Molecular clock calibration, tMRCA dating |
+| `chronaeon autoclock` | `deconvolve`, `multiclock` | Hierarchical multi-clock deconvolution |
+| `chronaeon triage` | `radar`, `sieve`, `qc`, `qc-stream`, `stream-qc`, `chronaeon-sieve` | Streaming genomic QC triage / outbreak radar |
+| `chronaeon phylogeo` | `geo`, `spatial`, `dispersal` | Discrete phylogeography |
+| `chronaeon dynamics` | `r0`, `rt`, `growth`, `phylodynamics` | Phylodynamic R₀/Rₜ estimation |
+| `chronaeon sketch` | `cluster`, `bin`, `centrifuge` | MinHash sketching & binning |
+| `chronaeon align` | `thread`, `codon-align` | Reference-guided codon alignment |
+
+## Key Capabilities
+
+- **tMRCA Dating** — Continuous sequence manifold dating using attention-derived covariance (`compute_neural_covariance_kernel`)
+- **AutoClock** — Hierarchical multi-clock deconvolution for complex evolutionary scenarios
+- **Triage/Radar** — Stream 100k genomes in minutes, detect emerging clades, flag anomalous spillover branches
+- **Phylogeography** — Continuous spatial dispersal reconstruction
+- **Phylodynamics** — R₀/Rₜ growth rate estimation from heterochronous sequences
+
+## The Radar & Microscope Flywheel
+
+ChronAeon is the **Radar**: rapidly screens genomes, detects emerging clades, and infers origin dates. HyphAeon is the **Microscope**: dissects *why* flagged clades emerged — identifying positive selection bursts and epistatic rewiring. Together they form a collaborative flywheel for genomic surveillance and deep evolutionary analysis.
+
+## Reproducible Benchmark Examples
+
+### Example 1: Heterochronous Molecular Clock Calibration & MRCA Dating
+
+Replicating the landmark study of **Bette Korber et al. (Science 2000)** dating the origin of HIV-1 group M to ~1931:
+
+```bash
+# Full Heterochronous Dating: Centered OLS + Attention PGLS + Latent Manifold Collapse
+chronaeon date \
+  -a chronaeon/examples/korber_env_gp160.fasta \
+  --root-taxon CONSENSUS \
+  --no-tree \
+  --method all \
+  -o chronaeon/examples/korber_dating_results.json \
+  -c chronaeon/examples/korber_dating_taxa.csv \
+  --plot-path chronaeon/examples/korber_clock_diagnostic.png
+```
+
+#### Output Summary:
+```text
+=========================================================================================================
+Method / Estimator                   Estimated t_MRCA     95% Confidence Interval    Rate (μ / year)    R^2   
+---------------------------------------------------------------------------------------------------------
+1. Standard OLS (TempEst RTT)        1930.82            [1866.5, 1945.8]              0.001874      0.472
+2. HyphAeon Attention PGLS           1927.57            [1916.4, 1938.7]              0.001875      0.518
+3. Latent Manifold Collapse          1975.96            [Non-Parametric Coalescent]    0.017032 [Var/yr] 0.429
+---------------------------------------------------------------------------------------------------------
+
+[*] Flagged Temporal Outliers (|Z| >= 2.5):
+    • Z59ZR.ZHU: Sampling Date=1959.5, Predicted Date=1933.4 (Discrepancy: -26.09 yr, Z=-5.40)
+```
+
+* **Accurate Ancestor Dating**: Recovers $t_{\text{MRCA}} = 1930.8$ (OLS) and $1927.6$ (Attention PGLS), closely reproducing Korber et al.'s supercomputer maximum-likelihood estimate of **1931.4 [1914.5, 1944.0]** and Thorne's MCMC relaxed clock (**1922–1929 [1889–1952]**) in seconds.
+* **Resolving Pseudoreplication**: Cross-taxa attention covariance $\boldsymbol{\Sigma} = \mathbf{A}_{\text{fused}} + \lambda\mathbf{I}$ whitens shared phylogenetic history, preventing false statistical precision without requiring tree inference.
+* **Historical Validation**: Accurately isolates the 1959 Léopoldville archival isolate `Z59ZR.ZHU` as a temporal outlier relative to the contemporary 1983–1997 cohort.
+* **Comprehensive Guide**: See [`DATING_GUIDE.md`](DATING_GUIDE.md) for full mathematical formulation, intra-host clinical applications (e.g. CD4+ T cell latent reservoir integration timing in CAP286), and CLI documentation.
+
+---
+
+### Example 2: Discrete Phylogeography & Spatial Transmission Networks
+
+Replicating the landmark discrete phylogeography study of **Philippe Lemey et al. (PLoS Comput Biol 2009)** reconstructing the epicentral origin and dispersal corridors of Avian Influenza A (H5N1) across 7 Chinese provinces:
+
+```bash
+# Run the built-in worked example with a single command
+chronaeon phylogeo --example --no-neural
+```
+
+Or execute directly on custom alignments and metadata:
+```bash
+chronaeon phylogeo \
+  -a chronaeon/examples/H5N1_HA_geo.fasta \
+  -g chronaeon/examples/H5N1_HA_metadata.csv \
+  -t chronaeon/examples/H5N1_HA.nwk \
+  --no-neural \
+  --n-perms 1000 \
+  --min-bf 3.0 \
+  --geojson chronaeon/examples/H5N1_HA_geo.geojson \
+  -o chronaeon/examples/H5N1_HA_geo_results.json \
+  -c chronaeon/examples/H5N1_HA_routes.csv \
+  --plot-path chronaeon/examples/H5N1_HA_geo_diagnostic.png
+```
+
+#### Output Summary:
+```text
+=========================================================================================================
+Rank   Geographic Region        Posterior P(Root)      Isolates     Role / Dynamics         
+---------------------------------------------------------------------------------------------------------
+1      Guangdong                  1.0000                15         Source / Exporter    ★ EPICENTER
+2      Fujian                     0.0000                 8         Source / Exporter   
+3      Guangxi                    0.0000                27         Source / Exporter   
+4      Hebei                      0.0000                 3         Sink / Importer     
+5      Henan                      0.0000                 8         Source / Exporter   
+6      HongKong                   0.0000                28         Sink / Importer     
+7      Hunan                      0.0000                 9         Sink / Importer     
+---------------------------------------------------------------------------------------------------------
+
+[*] Statistically Supported Transmission Routes (BF >= 3.0 or FDR <= 0.10):
+Source           Target (Sink)    Flux         Z-Score    p-value    FDR q      Bayes Factor   Support         
+---------------------------------------------------------------------------------------------------------
+Guangdong        Fujian            0.36515       3.63     0.0060    0.2517      247.5     Decisive (BF >= 100)
+Henan            Hebei             0.20412       3.92     0.0559    1.0000       43.0     Strong (10 <= BF < 100)
+Guangdong        Guangxi           0.24845       1.33     0.1578    1.0000       13.4     Strong (10 <= BF < 100)
+Fujian           Hebei             0.20412       1.69     0.1948    1.0000       10.4     Strong (10 <= BF < 100)
+Henan            Hunan             0.11785       0.76     0.3986    1.0000        3.8     Substantial (3 <= BF < 10)
+Fujian           Henan             0.12500       0.67     0.4226    1.0000        3.4     Substantial (3 <= BF < 10)
+Guangdong        HongKong          0.14639       0.40     0.4426    1.0000        3.2     Substantial (3 <= BF < 10)
+```
+
+#### Key Innovations over BEAST (Lemey et al. 2009):
+* **Ultra-Fast Speed (< 1 Second vs. Hours)**: Replaces tens of millions of MCMC iterations over $2^{K(K-1)/2}$ graph configurations with closed-form ancestral state reconstruction and vectorized matrix permutations.
+* **Naturally Asymmetric Directed Migration**: Unlike BEAST's reversible rate matrix ($\mathbf{\Lambda} = \mu \mathbf{S} \mathbf{P}$, which enforces $s_{jk} = s_{kj}$), ChronAeon measures true directional transmission ($M_{jk} \ne M_{kj}$), capturing directional source-sink dynamics.
+* **Vectorized Permutation BSSVS**: Generates exact empirical Bayes Factors ($\text{BF} \ge 3.0$) and Benjamini-Hochberg FDR $q$-values from 1,000 null permutations in $< 0.1$ seconds.
+* **Spatial PGLS Epicenter**: Infers the continuous geographic epicenter coordinates ($28.10^\circ\text{N}, 111.83^\circ\text{E}$) with analytical 95% geographic confidence radii.
+* **Modern Web GIS Export**: Generates standard GeoJSON feature collections (`.geojson`) compatible with Kepler.gl and Nextstrain/Auspice.
+
+---
+
+### Example 3: Phylodynamic R₀/Rₜ Estimation from Pandemic H1N1
+
+Replicating the landmark phylodynamics study of **Fraser et al. (Science 2009)** estimating the early growth rate and basic reproduction number (R₀) of the 2009 H1N1 pandemic:
+
+```bash
+# Run the built-in worked example with a single command
+chronaeon dynamics --example
+```
+
+Or execute directly on custom alignments and metadata:
+```bash
+chronaeon dynamics \
+  -a chronaeon/examples/H1N1_2009_pandemic.fasta \
+  -t chronaeon/examples/H1N1_2009_pandemic.nwk \
+  --pathogen h1n1 \
+  --plot \
+  --plot-path chronaeon/examples/H1N1_2009_r0_diagnostic.png \
+  -o chronaeon/examples/H1N1_2009_r0_results.json \
+  -c chronaeon/examples/H1N1_2009_rt_skyline.csv
+```
+
+#### Key Features:
+* **Ultra-Fast Growth Rate Estimation**: Recovers epidemic growth rate ($r$) and basic reproduction number ($R_0$) in seconds from heterochronous sequence data, without MCMC.
+* **Dynamic R(t) Skyline**: Sliding-window estimation of time-varying reproduction numbers ($R_t$) across the epidemic timeline, capturing waves and interventions.
+* **Pathogen Presets**: Built-in generation intervals for common pathogens (`h1n1`, `ebola`, `sars-cov-2`, `measles`, `hiv_early`), or specify custom generation time and SD for gamma renewal models.
+* **SEIR Renewal Model**: Optional latent period support for more realistic epidemic modeling.
+
+---
+
+### Example 4: Bayesian Warm-Start Bridge for BEAST MCMC (`--export-beast`)
+
+ChronAeon functions as an upstream prior generator for full Bayesian MCMC engines (BEAST 1.x and BEAST X v10.5.0), eliminating the multi-million iteration burn-in penalty caused by arbitrary default priors (e.g. initial $\mu = 1.0$ and uncalibrated demographic starting trees):
+
+```bash
+# 1. Run ChronAeon dating and export pre-populated BEAST XML in a single command:
+chronaeon date \
+  -a alignment.fasta \
+  -d dates.csv \
+  --export-beast beast_warmstart.xml \
+  --beast-clock relaxed \
+  --beast-chain-length 10000000
+
+# 2. Run BEAST with immediate Step-0 convergence:
+beast -overwrite beast_warmstart.xml
+```
+
+#### What ChronAeon Calibrates Inside the BEAST XML:
+* **Substitution Rate ($\mu$)**: Sets initial `clock.rate` or `ucld.mean` directly to ChronAeon's empirical $\hat{\mu}$ (e.g. $2.0 \times 10^{-4}$), avoiding the 4-orders-of-magnitude likelihood chasm of cold-start runs.
+* **Informative Rate Prior**: Embeds a data-driven `logNormalPrior` centered at $\ln(\hat{\mu})$ with variance proportional to the Fieller analytical standard error.
+* **Root Height ($t_{\mathrm{MRCA}}$)**: Calibrates `treeModel.rootHeight` prior with a `normalPrior` centered at $t_{\max} - \hat{t}_{\mathrm{MRCA}}$ with standard deviation matching the 95% Fieller / Jackknife interval.
+* **Coalescent Demography**: Initializes `constant.popSize` to $H / 2$, ensuring the starting coalescent tree matches the empirical time horizon.
+* **AutoClock Multi-Clock Partitioning**: When used with `chronaeon autoclock --export-beast`, automatically emits partitioned taxon sets (`<taxa id="community_k">`) with lineage-specific local clock rates.
+
+---
+
+## Documentation
+
+- [Dating Guide](DATING_GUIDE.md)
+- [AutoClock Guide](AUTOCLOCK_GUIDE.md)
+- [MRCA Dating Report](MRCA_DATING_REPORT.md)

chronaeon-0.1.0/README.md

@@ -0,0 +1,219 @@
+# ChronAeon
+
+**The Velocity of Time** — Ultra-fast molecular clock dating, phylodynamics, and genomic surveillance.
+
+ChronAeon operates along the **TAXON / LINEAGE** axis of the HyphAeon foundation model, providing sub-second execution for tree-free continuous manifold dating, attention-derived covariance, and planetary-scale genomic screening.
+
+## Target Audience
+
+Public health agencies (CDC, WHO, UKHSA), outbreak epidemiologists, hospital infection control teams.
+
+## Installation
+
+ChronAeon requires Python ≥ 3.8 and PyTorch ≥ 2.0. At runtime it auto-selects
+the best available device (CUDA → Apple MPS → CPU), so no manual configuration
+is needed regardless of which install path you choose.
+
+```bash
+pip install chronaeon
+```
+
+| Method | Command | Torch | GPU? |
+| :--- | :--- | :--- | :--- |
+| **pip** (default) | `pip install chronaeon` | CUDA-bundled wheel (~550 MB) | NVIDIA GPU if driver matches; else CPU |
+| **pip** (CPU-only) | `pip install torch --index-url https://download.pytorch.org/whl/cpu` then `pip install chronaeon` | CPU-only wheel (~200 MB) | CPU |
+| **Bioconda** | `conda install -c bioconda chronaeon` | CPU-only `pytorch` from conda-forge | CPU only |
+| **NVIDIA Jetson** | See [issue #31](https://github.com/veg/HyphAeon/issues/31) | JetPack-native wheel (cp38 only) | Jetson GPU |
+
+You can always install a specific PyTorch build before installing ChronAeon if
+none of the above defaults suit your system (e.g. a particular CUDA version,
+a custom wheel, or a CPU-only build on a server without GPU).
+
+> [!NOTE]
+> **Model weights** are downloaded automatically from [Hugging Face](https://huggingface.co/datamonkey/hyphaeon)
+> on first use (cached in `~/.cache/hyphaeon/`). No authentication or token is
+> required. Use `--model-variant viral` to select the viral-tuned variant, or
+> `--weights /path/to/checkpoint` to use a local file.
+
+## CLI Subcommands
+
+| Command | Aliases | Description |
+| :--- | :--- | :--- |
+| `chronaeon date` | `dating`, `clock`, `mrca` | Molecular clock calibration, tMRCA dating |
+| `chronaeon autoclock` | `deconvolve`, `multiclock` | Hierarchical multi-clock deconvolution |
+| `chronaeon triage` | `radar`, `sieve`, `qc`, `qc-stream`, `stream-qc`, `chronaeon-sieve` | Streaming genomic QC triage / outbreak radar |
+| `chronaeon phylogeo` | `geo`, `spatial`, `dispersal` | Discrete phylogeography |
+| `chronaeon dynamics` | `r0`, `rt`, `growth`, `phylodynamics` | Phylodynamic R₀/Rₜ estimation |
+| `chronaeon sketch` | `cluster`, `bin`, `centrifuge` | MinHash sketching & binning |
+| `chronaeon align` | `thread`, `codon-align` | Reference-guided codon alignment |
+
+## Key Capabilities
+
+- **tMRCA Dating** — Continuous sequence manifold dating using attention-derived covariance (`compute_neural_covariance_kernel`)
+- **AutoClock** — Hierarchical multi-clock deconvolution for complex evolutionary scenarios
+- **Triage/Radar** — Stream 100k genomes in minutes, detect emerging clades, flag anomalous spillover branches
+- **Phylogeography** — Continuous spatial dispersal reconstruction
+- **Phylodynamics** — R₀/Rₜ growth rate estimation from heterochronous sequences
+
+## The Radar & Microscope Flywheel
+
+ChronAeon is the **Radar**: rapidly screens genomes, detects emerging clades, and infers origin dates. HyphAeon is the **Microscope**: dissects *why* flagged clades emerged — identifying positive selection bursts and epistatic rewiring. Together they form a collaborative flywheel for genomic surveillance and deep evolutionary analysis.
+
+## Reproducible Benchmark Examples
+
+### Example 1: Heterochronous Molecular Clock Calibration & MRCA Dating
+
+Replicating the landmark study of **Bette Korber et al. (Science 2000)** dating the origin of HIV-1 group M to ~1931:
+
+```bash
+# Full Heterochronous Dating: Centered OLS + Attention PGLS + Latent Manifold Collapse
+chronaeon date \
+  -a chronaeon/examples/korber_env_gp160.fasta \
+  --root-taxon CONSENSUS \
+  --no-tree \
+  --method all \
+  -o chronaeon/examples/korber_dating_results.json \
+  -c chronaeon/examples/korber_dating_taxa.csv \
+  --plot-path chronaeon/examples/korber_clock_diagnostic.png
+```
+
+#### Output Summary:
+```text
+=========================================================================================================
+Method / Estimator                   Estimated t_MRCA     95% Confidence Interval    Rate (μ / year)    R^2   
+---------------------------------------------------------------------------------------------------------
+1. Standard OLS (TempEst RTT)        1930.82            [1866.5, 1945.8]              0.001874      0.472
+2. HyphAeon Attention PGLS           1927.57            [1916.4, 1938.7]              0.001875      0.518
+3. Latent Manifold Collapse          1975.96            [Non-Parametric Coalescent]    0.017032 [Var/yr] 0.429
+---------------------------------------------------------------------------------------------------------
+
+[*] Flagged Temporal Outliers (|Z| >= 2.5):
+    • Z59ZR.ZHU: Sampling Date=1959.5, Predicted Date=1933.4 (Discrepancy: -26.09 yr, Z=-5.40)
+```
+
+* **Accurate Ancestor Dating**: Recovers $t_{\text{MRCA}} = 1930.8$ (OLS) and $1927.6$ (Attention PGLS), closely reproducing Korber et al.'s supercomputer maximum-likelihood estimate of **1931.4 [1914.5, 1944.0]** and Thorne's MCMC relaxed clock (**1922–1929 [1889–1952]**) in seconds.
+* **Resolving Pseudoreplication**: Cross-taxa attention covariance $\boldsymbol{\Sigma} = \mathbf{A}_{\text{fused}} + \lambda\mathbf{I}$ whitens shared phylogenetic history, preventing false statistical precision without requiring tree inference.
+* **Historical Validation**: Accurately isolates the 1959 Léopoldville archival isolate `Z59ZR.ZHU` as a temporal outlier relative to the contemporary 1983–1997 cohort.
+* **Comprehensive Guide**: See [`DATING_GUIDE.md`](DATING_GUIDE.md) for full mathematical formulation, intra-host clinical applications (e.g. CD4+ T cell latent reservoir integration timing in CAP286), and CLI documentation.
+
+---
+
+### Example 2: Discrete Phylogeography & Spatial Transmission Networks
+
+Replicating the landmark discrete phylogeography study of **Philippe Lemey et al. (PLoS Comput Biol 2009)** reconstructing the epicentral origin and dispersal corridors of Avian Influenza A (H5N1) across 7 Chinese provinces:
+
+```bash
+# Run the built-in worked example with a single command
+chronaeon phylogeo --example --no-neural
+```
+
+Or execute directly on custom alignments and metadata:
+```bash
+chronaeon phylogeo \
+  -a chronaeon/examples/H5N1_HA_geo.fasta \
+  -g chronaeon/examples/H5N1_HA_metadata.csv \
+  -t chronaeon/examples/H5N1_HA.nwk \
+  --no-neural \
+  --n-perms 1000 \
+  --min-bf 3.0 \
+  --geojson chronaeon/examples/H5N1_HA_geo.geojson \
+  -o chronaeon/examples/H5N1_HA_geo_results.json \
+  -c chronaeon/examples/H5N1_HA_routes.csv \
+  --plot-path chronaeon/examples/H5N1_HA_geo_diagnostic.png
+```
+
+#### Output Summary:
+```text
+=========================================================================================================
+Rank   Geographic Region        Posterior P(Root)      Isolates     Role / Dynamics         
+---------------------------------------------------------------------------------------------------------
+1      Guangdong                  1.0000                15         Source / Exporter    ★ EPICENTER
+2      Fujian                     0.0000                 8         Source / Exporter   
+3      Guangxi                    0.0000                27         Source / Exporter   
+4      Hebei                      0.0000                 3         Sink / Importer     
+5      Henan                      0.0000                 8         Source / Exporter   
+6      HongKong                   0.0000                28         Sink / Importer     
+7      Hunan                      0.0000                 9         Sink / Importer     
+---------------------------------------------------------------------------------------------------------
+
+[*] Statistically Supported Transmission Routes (BF >= 3.0 or FDR <= 0.10):
+Source           Target (Sink)    Flux         Z-Score    p-value    FDR q      Bayes Factor   Support         
+---------------------------------------------------------------------------------------------------------
+Guangdong        Fujian            0.36515       3.63     0.0060    0.2517      247.5     Decisive (BF >= 100)
+Henan            Hebei             0.20412       3.92     0.0559    1.0000       43.0     Strong (10 <= BF < 100)
+Guangdong        Guangxi           0.24845       1.33     0.1578    1.0000       13.4     Strong (10 <= BF < 100)
+Fujian           Hebei             0.20412       1.69     0.1948    1.0000       10.4     Strong (10 <= BF < 100)
+Henan            Hunan             0.11785       0.76     0.3986    1.0000        3.8     Substantial (3 <= BF < 10)
+Fujian           Henan             0.12500       0.67     0.4226    1.0000        3.4     Substantial (3 <= BF < 10)
+Guangdong        HongKong          0.14639       0.40     0.4426    1.0000        3.2     Substantial (3 <= BF < 10)
+```
+
+#### Key Innovations over BEAST (Lemey et al. 2009):
+* **Ultra-Fast Speed (< 1 Second vs. Hours)**: Replaces tens of millions of MCMC iterations over $2^{K(K-1)/2}$ graph configurations with closed-form ancestral state reconstruction and vectorized matrix permutations.
+* **Naturally Asymmetric Directed Migration**: Unlike BEAST's reversible rate matrix ($\mathbf{\Lambda} = \mu \mathbf{S} \mathbf{P}$, which enforces $s_{jk} = s_{kj}$), ChronAeon measures true directional transmission ($M_{jk} \ne M_{kj}$), capturing directional source-sink dynamics.
+* **Vectorized Permutation BSSVS**: Generates exact empirical Bayes Factors ($\text{BF} \ge 3.0$) and Benjamini-Hochberg FDR $q$-values from 1,000 null permutations in $< 0.1$ seconds.
+* **Spatial PGLS Epicenter**: Infers the continuous geographic epicenter coordinates ($28.10^\circ\text{N}, 111.83^\circ\text{E}$) with analytical 95% geographic confidence radii.
+* **Modern Web GIS Export**: Generates standard GeoJSON feature collections (`.geojson`) compatible with Kepler.gl and Nextstrain/Auspice.
+
+---
+
+### Example 3: Phylodynamic R₀/Rₜ Estimation from Pandemic H1N1
+
+Replicating the landmark phylodynamics study of **Fraser et al. (Science 2009)** estimating the early growth rate and basic reproduction number (R₀) of the 2009 H1N1 pandemic:
+
+```bash
+# Run the built-in worked example with a single command
+chronaeon dynamics --example
+```
+
+Or execute directly on custom alignments and metadata:
+```bash
+chronaeon dynamics \
+  -a chronaeon/examples/H1N1_2009_pandemic.fasta \
+  -t chronaeon/examples/H1N1_2009_pandemic.nwk \
+  --pathogen h1n1 \
+  --plot \
+  --plot-path chronaeon/examples/H1N1_2009_r0_diagnostic.png \
+  -o chronaeon/examples/H1N1_2009_r0_results.json \
+  -c chronaeon/examples/H1N1_2009_rt_skyline.csv
+```
+
+#### Key Features:
+* **Ultra-Fast Growth Rate Estimation**: Recovers epidemic growth rate ($r$) and basic reproduction number ($R_0$) in seconds from heterochronous sequence data, without MCMC.
+* **Dynamic R(t) Skyline**: Sliding-window estimation of time-varying reproduction numbers ($R_t$) across the epidemic timeline, capturing waves and interventions.
+* **Pathogen Presets**: Built-in generation intervals for common pathogens (`h1n1`, `ebola`, `sars-cov-2`, `measles`, `hiv_early`), or specify custom generation time and SD for gamma renewal models.
+* **SEIR Renewal Model**: Optional latent period support for more realistic epidemic modeling.
+
+---
+
+### Example 4: Bayesian Warm-Start Bridge for BEAST MCMC (`--export-beast`)
+
+ChronAeon functions as an upstream prior generator for full Bayesian MCMC engines (BEAST 1.x and BEAST X v10.5.0), eliminating the multi-million iteration burn-in penalty caused by arbitrary default priors (e.g. initial $\mu = 1.0$ and uncalibrated demographic starting trees):
+
+```bash
+# 1. Run ChronAeon dating and export pre-populated BEAST XML in a single command:
+chronaeon date \
+  -a alignment.fasta \
+  -d dates.csv \
+  --export-beast beast_warmstart.xml \
+  --beast-clock relaxed \
+  --beast-chain-length 10000000
+
+# 2. Run BEAST with immediate Step-0 convergence:
+beast -overwrite beast_warmstart.xml
+```
+
+#### What ChronAeon Calibrates Inside the BEAST XML:
+* **Substitution Rate ($\mu$)**: Sets initial `clock.rate` or `ucld.mean` directly to ChronAeon's empirical $\hat{\mu}$ (e.g. $2.0 \times 10^{-4}$), avoiding the 4-orders-of-magnitude likelihood chasm of cold-start runs.
+* **Informative Rate Prior**: Embeds a data-driven `logNormalPrior` centered at $\ln(\hat{\mu})$ with variance proportional to the Fieller analytical standard error.
+* **Root Height ($t_{\mathrm{MRCA}}$)**: Calibrates `treeModel.rootHeight` prior with a `normalPrior` centered at $t_{\max} - \hat{t}_{\mathrm{MRCA}}$ with standard deviation matching the 95% Fieller / Jackknife interval.
+* **Coalescent Demography**: Initializes `constant.popSize` to $H / 2$, ensuring the starting coalescent tree matches the empirical time horizon.
+* **AutoClock Multi-Clock Partitioning**: When used with `chronaeon autoclock --export-beast`, automatically emits partitioned taxon sets (`<taxa id="community_k">`) with lineage-specific local clock rates.
+
+---
+
+## Documentation
+
+- [Dating Guide](DATING_GUIDE.md)
+- [AutoClock Guide](AUTOCLOCK_GUIDE.md)
+- [MRCA Dating Report](MRCA_DATING_REPORT.md)

chronaeon-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chronaeon"
+version = "0.1.0"
+authors = [
+  { name="Sergei L. Kosakovsky Pond", email="spond@temple.edu" },
+]
+description = "ChronAeon: Ultra-Fast Molecular Clock Dating, Phylodynamics, and Genomic Surveillance"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "hyphaeon-core>=0.1.0",
+    "biopython>=1.80",
+    "numpy>=1.22.0",
+    "scipy>=1.9.0",
+    "pandas>=1.5.0",
+    "scikit-learn>=1.0",
+    "matplotlib>=3.5",
+    "tn93>=1.2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+chronaeon = "chronaeon.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+"Homepage" = "https://github.com/veg/HyphAeon"
+"Bug Tracker" = "https://github.com/veg/HyphAeon/issues"

chronaeon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chronaeon-0.1.0/src/chronaeon/__init__.py

@@ -0,0 +1,65 @@
+"""
+ChronAeon: Ultra-Fast Molecular Clock Dating, Phylodynamics, and Genomic Surveillance.
+"""
+
+from .dating import (
+    run_mrca_dating,
+    run_ols_dating,
+    run_pgls_dating,
+    run_restricted_spline_clock_dating,
+    run_powerlaw_clock_dating,
+    verify_coding_alignment,
+    parse_sample_dates,
+    generate_consensus_sequence,
+    generate_time_decay_consensus_sequence,
+)
+from .geo import (
+    run_phylogeography_analysis,
+    estimate_spatial_pgls_epicenter,
+    parse_geo_metadata,
+)
+from .r0 import (
+    run_r0_analysis,
+    compute_reproduction_numbers,
+    plot_r0_diagnostics,
+    PATHOGEN_PRESETS,
+)
+from .autoclock import (
+    AutoClockDeconvolution,
+    run_autoclock_deconvolution,
+    HierarchicalAutoClock,
+    run_hierarchical_autoclock,
+    fit_clock,
+    recursive_spectral_autoclock,
+    classify_community,
+    classify_leaf_community,
+)
+from .triage import ChronAeonSieve
+from .sketch import (
+    CanonicalMinHashSketcher,
+    AlignmentFreeBinner,
+    AlignmentFreeCentrifuge,
+)
+from .alignment import (
+    ReferenceCodonAligner,
+    ReferenceGuidedCodonThreader,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "run_mrca_dating", "run_ols_dating", "run_pgls_dating",
+    "run_restricted_spline_clock_dating", "run_powerlaw_clock_dating",
+    "verify_coding_alignment", "parse_sample_dates",
+    "generate_consensus_sequence", "generate_time_decay_consensus_sequence",
+    "run_phylogeography_analysis", "estimate_spatial_pgls_epicenter",
+    "parse_geo_metadata",
+    "run_r0_analysis", "compute_reproduction_numbers",
+    "plot_r0_diagnostics", "PATHOGEN_PRESETS",
+    "AutoClockDeconvolution", "run_autoclock_deconvolution",
+    "HierarchicalAutoClock", "run_hierarchical_autoclock",
+    "fit_clock", "recursive_spectral_autoclock",
+    "classify_community", "classify_leaf_community",
+    "ChronAeonSieve",
+    "CanonicalMinHashSketcher", "AlignmentFreeBinner", "AlignmentFreeCentrifuge",
+    "ReferenceCodonAligner", "ReferenceGuidedCodonThreader",
+]