Home
A Python toolkit for simulating sequence evolution, exploring molecular clock models and implementing phylogenetic reconstruction algorithms from first principles.
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 measuring genetic distance, interactive explorers for investigating molecular clock models, and implementations of phylogenetic reconstruction algorithms.
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 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.
Three distance calculations are currently supported:
- 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
Together these provide a progression from simple sequence comparison to the first model-based estimate 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 future phylogenetic reconstruction methods, beginning with UPGMA.
The project includes interactive Streamlit applications built directly on top of both simulation engines.
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.