Home
A Python toolkit for simulating sequence evolution, estimating evolutionary distances, reconstructing phylogenetic trees and exploring molecular clock calibration from first principles.
The project combines reusable simulation engines, analytical tools and interactive explorers to provide a complete educational workflow from molecular clock simulation through sequence analysis and phylogenetic reconstruction to molecular clock calibration.
Molecular clocks use DNA sequence variation to estimate evolutionary relationships and divergence times between species.
This project explores the computational foundations of molecular clock analysis by building the core algorithms from first principles. It includes simulation engines for generating synthetic evolutionary datasets, analytical tools for estimating evolutionary distances, implementations of distance-based phylogenetic reconstruction algorithms, simple molecular clock calibration, and interactive explorers that integrate the complete workflow.
The repository combines reusable simulation engines, command-line interfaces for generating synthetic datasets, and interactive explorers for experimenting with both strict and relaxed molecular clock models.
The project is intended both as an educational resource and as a computational laboratory for investigating phylogenetic algorithms.
The interactive explorers guide users through the complete workflow of distance-based molecular phylogenetics, beginning with simulation of an evolutionary history and progressing through evolutionary distance estimation, phylogenetic reconstruction and simple molecular clock calibration. When working with simulated datasets, reconstructed trees can also be compared directly with the known evolutionary history.
Each stage produces intermediate outputs that can be inspected, visualised and exported, allowing every step of the analysis pipeline to be explored independently.
The core simulator implements a strict molecular clock capable of generating complete synthetic evolutionary datasets.
Features include:
- Random ancestral DNA sequence generation
- Rooted phylogenetic tree generation
- Balanced and random branching models
- Ultrametric tree calibration
- DNA sequence evolution along each branch
- Complete evolutionary history tracking
- Export of simulated datasets in FASTA, Newick and JSON formats
These datasets provide known ground truth against which future phylogenetic reconstruction algorithms can be evaluated.
A second simulation engine implements a simple autocorrelated relaxed molecular clock.
Unlike the strict clock model, individual lineages evolve at different mutation rates while preserving a complete known evolutionary history.
Features include:
- Independent relaxed clock simulation engine
- Lineage-specific mutation rates
- Autocorrelated rate inheritance
- Time and genetic distance tracking
- Export in FASTA, Newick and JSON formats
- Complete mutation and lineage-rate history
The relaxed clock engine complements the existing strict clock simulator, providing synthetic datasets for investigating the effects of rate variation on downstream phylogenetic analysis.
The project includes a reusable distance matrix calculator for analysing aligned DNA sequences.
The calculator computes pairwise genetic distances between every sequence in a FASTA file and produces symmetric distance matrices suitable for downstream phylogenetic reconstruction.
Six distance calculations are currently supported:
| Calculation | Characteristics |
|---|---|
| Hamming distance | Counts the number of differing nucleotide positions |
| Proportional distance (p-distance) | Reports the proportion of differing positions |
| Jukes–Cantor (JC69) | Applies a substitution correction to estimate the true evolutionary distance while accounting for multiple mutations at the same site |
| Kimura two-parameter (K80) | Distinguishes transitions from transversions when correcting observed divergence |
| Felsenstein 1981 (F81) | Allows unequal nucleotide frequencies when estimating corrected evolutionary distance |
| Hasegawa-Kishino-Yano (HKY85) | Combines unequal nucleotide frequencies with transition/transversion bias |
Together these provide a progression from simple sequence comparison to increasingly flexible model-based estimates of evolutionary divergence.
Matrices are exported in both CSV and JSON formats, allowing them to be inspected directly or consumed programmatically by subsequent algorithms.
The calculator is implemented as a reusable Python module with a lightweight command-line interface and forms the foundation for the project’s phylogenetic reconstruction and calibration tools.
The project includes reusable implementations of two classic distance-based phylogenetic reconstruction algorithms.
- UPGMA reconstructs rooted phylogenetic trees under the assumption of a constant molecular clock
- Neighbor Joining reconstructs unrooted trees without assuming equal evolutionary rates across all lineages
Both algorithms operate directly on the estimated distance matrices produced by the distance calculator and export reconstructed phylogenies in standard Newick format for visualisation, comparison and downstream calibration.
Tree reconstruction algorithms estimate relative evolutionary change rather than absolute geological time. The project includes a simple educational tree calibration module that converts reconstructed branch lengths into approximate divergence times using a single calibration point.
Users specify two taxa and the estimated age of their most recent common ancestor. The reconstructed tree is then scaled using a single global molecular clock, producing a calibrated phylogeny with branch lengths expressed in millions of years together with calibration metadata describing the applied scaling factor.
Although greatly simplified compared with modern Bayesian molecular dating software, the implementation demonstrates the central idea behind molecular clock calibration and completes the educational workflow from simulated sequence evolution to approximately dated phylogenetic trees.
The project includes interactive Streamlit applications built directly on top of both the strict and relaxed molecular clock simulation engines.
Both explorers provide a complete interactive workflow for investigating molecular phylogenetics, allowing simulated datasets to be analysed immediately after generation.
Each explorer includes:
- Interactive molecular clock simulation
- Visualisation of the simulated phylogenetic tree
- FASTA and Newick inspection
- Pairwise sequence comparison
- Multiple evolutionary distance calculations
- Interactive distance matrix heat-map
- Distance correction analysis
- UPGMA and Neighbor Joining phylogenetic tree reconstruction
- Side-by-side comparison of simulated and reconstructed trees
- Simple reconstructed tree calibration using a user-defined calibration point
- Export of simulation and analysis results
The Strict Molecular Clock Explorer demonstrates evolution under a constant mutation rate, while the Relaxed Molecular Clock Explorer introduces lineage-specific rate variation and illustrates the consequences for downstream phylogenetic reconstruction.
Together the explorers provide a complete educational environment for understanding how simulated DNA sequences are transformed into evolutionary distance estimates, reconstructed phylogenetic trees and, ultimately, approximate divergence times through molecular clock calibration.
The Strict Molecular Clock Explorer provides an interactive interface for experimenting with the strict molecular clock model.
Simulation parameters can be adjusted before generating a new evolutionary history and visualising the resulting ultrametric phylogenetic tree.
The explorer provides an intuitive way to investigate how sequence length, mutation rate and tree topology influence the simulated dataset.
The Relaxed Molecular Clock Explorer extends the same interface to the relaxed molecular clock model.
In addition to the standard simulation controls, it introduces lineage-specific mutation rates and allows the effects of evolutionary rate variation to be explored interactively.
The explorer visualises branch-specific genetic change, observed substitutions and simulation summary statistics, providing an intuitive way to investigate how relaxed molecular clocks differ from the strict clock model.
Both explorers are built on the underlying command-line simulation engines, which remain fully supported for reproducible dataset generation and downstream analysis.