Version 1.5.0

• Fix Graphviz error attempting to export the reconstructed and calibrated tree images from the containerised version of the explorers

Version 1.4.0

This release completes the project’s educational workflow by introducing simple molecular clock calibration, allowing reconstructed phylogenetic trees to be converted into approximate divergence times using a single calibration point.

Building on the existing simulation, distance estimation and tree reconstruction tools, the project now demonstrates the complete sequence from simulated DNA evolution to an approximately dated phylogenetic tree. The implementation is intentionally simple, illustrating the fundamental principles of molecular clock calibration without the complexity of full Bayesian divergence dating methods.

Highlights

• Implemented a reusable tree calibration module
• Added a command-line tool for calibrating reconstructed phylogenetic trees
• Introduced support for single-point calibration using the estimated age of a specified most recent common ancestor (MRCA)
• Export calibrated trees with branch lengths expressed in millions of years
• Export calibration metadata describing the applied scaling factor
• Added tree calibration to both Molecular Clock Explorers
• Updated documentation and workflow diagrams to reflect the complete phylogenetic analysis pipeline

Educational Notes

Phylogenetic reconstruction algorithms estimate relative evolutionary change, not absolute geological time. Tree calibration uses an external estimate of divergence time to convert relative branch lengths into approximate dates.

This implementation assumes a single global molecular clock and a single calibration point, providing a transparent demonstration of the calibration process while avoiding the complexity of modern Bayesian molecular dating software.

With the addition of tree calibration, the project now supports the complete educational workflow:

• Molecular clock simulation
• DNA sequence evolution
• Evolutionary distance estimation
• Phylogenetic tree reconstruction
• Molecular clock calibration

Version 1.3.0

This release improves the usability and accessibility of the Molecular Clock Simulation project by introducing Docker support for both interactive explorers alongside a range of workflow and download enhancements.

The Strict and Relaxed Molecular Clock Explorers can now be run directly from Docker images without cloning or building the project locally, providing a simple way to explore molecular clock simulation, evolutionary distance estimation and phylogenetic reconstruction.

The release also expands the reconstruction workflow by allowing reconstructed trees to be exported in both Newick and PNG formats, while improving the Downloads tab through additional validation, clearer default filenames and general usability refinements.

Highlights

• Published Docker images for both the Strict and Relaxed Molecular Clock Explorers
• Added download of reconstructed phylogenetic trees as both Newick and PNG
• Improved validation and usability throughout the Downloads tab
• Added sensible default filenames for generated outputs
• Refactored common explorer code to improve maintainability and reduce duplication
• Updated the project documentation

Educational Notes

The addition of Docker images makes the interactive explorers accessible without requiring a local Python development environment, allowing users to experiment with molecular clock simulation and phylogenetic reconstruction using a single Docker command.

Enhanced export capabilities also make it easier to compare reconstructed trees with the known simulated histories and to incorporate figures and Newick trees into reports, presentations and further analysis.

Version 1.2.0

This release adds Neighbor Joining as the project’s second phylogenetic reconstruction algorithm, making it possible to compare a reconstruction method that assumes a strict molecular clock with one that does not require equal evolutionary rates across all lineages.

Highlights

• Implemented a reusable Neighbor Joining reconstruction module
• Added deterministic Q-matrix construction, branch length calculation and distance matrix updates
• Extended the reconstruction command with --method upgma and --method nj
• Added Neighbor Joining to the Reconstruction workspace in both Molecular Clock Explorers
• Added support for unrooted Neighbor Joining trees throughout the reconstruction, Newick export and explorer visualisations
• Added automated tests covering Q-matrix calculation, branch length calculation, distance matrix updates, deterministic tie handling, Newick export and CLI integration

Educational Notes

UPGMA and Neighbor Joining both reconstruct phylogenetic trees from the same evolutionary distance matrix, but they make different assumptions about how evolution proceeds.

UPGMA assumes a constant molecular clock and therefore reconstructs rooted ultrametric trees. Neighbor Joining does not assume equal evolutionary rates and instead reconstructs unrooted trees whose branch lengths can vary between lineages.

Together, the two algorithms allow the project to demonstrate how different evolutionary assumptions influence the reconstruction of phylogenetic trees from identical sequence data.

Version 1.1.0

This release integrates phylogenetic tree reconstruction directly into the project’s interactive explorers, completing the end-to-end educational workflow from molecular clock simulation through evolutionary distance estimation to phylogenetic inference.

Both the Strict and Relaxed Molecular Clock Explorers now provide dedicated Simulation, Distance and Reconstruction workspaces. Users can generate evolutionary histories, analyse pairwise sequence distances using multiple substitution models, reconstruct phylogenetic trees from the resulting distance matrices and compare inferred trees with the known simulated histories, all within a single interactive interface.

The explorers have also been refined with a more streamlined workflow. Analysis controls have been moved to the sidebar, navigation between workspaces is now automatic, and additional export options allow distance matrices to be downloaded for use in external software.

Highlights

• Added integrated phylogenetic tree reconstruction to both explorers.
• Introduced dedicated Simulation, Distance and Reconstruction workspaces.
• Added reconstruction of phylogenetic trees directly from calculated distance matrices.
• Added distance matrix export to the Downloads tab.
• Moved distance analysis controls into the sidebar for a more consistent interface.
• Automatically switch to the appropriate workspace after simulation or analysis actions.
• Updated the project Wiki and README to document the expanded explorer workflow.

Educational Workflow

The explorers now provide a complete interactive molecular phylogenetics workflow:

1. Simulate evolutionary history
2. Generate DNA sequences
3. Estimate evolutionary distances
4. Apply substitution model corrections
5. Reconstruct a phylogenetic tree
6. Compare the reconstructed tree with the known simulation

This workflow allows users to explore not only how molecular clock simulations generate sequence data, but also how those sequences are analysed to infer evolutionary relationships, making the assumptions and limitations of distance-based phylogenetic reconstruction easier to understand.

Version 1.0.0

Version 1.0.0 marks the first complete release of the Molecular Clock Simulation toolkit.

The project now provides an end-to-end educational workflow covering molecular clock simulation, sequence evolution, evolutionary distance estimation, substitution models and distance-based phylogenetic reconstruction. Interactive explorers, command-line tools and comprehensive documentation allow users to explore the assumptions and behaviour of both strict and relaxed molecular clocks, while comparing reconstructed phylogenetic trees with their known simulated histories.

This release introduces UPGMA (Unweighted Pair Group Method with Arithmetic Mean), the project’s first phylogenetic tree reconstruction algorithm.

Building on the previously implemented distance matrix calculator and substitution models, the project can now reconstruct rooted phylogenetic trees directly from estimated evolutionary distances. This completes the next stage of the molecular clock pipeline, linking simulated sequence evolution to phylogenetic inference.

Highlights

• Implemented the UPGMA tree reconstruction algorithm
• Added a reusable phylogenetic reconstruction module
• Added a command-line interface for reconstructing trees from distance matrices
• Generated rooted trees in standard Newick format with calculated branch lengths
• Implemented deterministic clustering to ensure reproducible output when distance ties occur
• Added graphical true vs. reconstructed tree comparison tool
• Added automated tests covering clustering behaviour, distance averaging, branch length calculation and ultrametric tree reconstruction

Documentation

• Added a comprehensive wiki page describing the UPGMA algorithm, including:
  • The complete reconstruction workflow from molecular clock simulation to tree comparison
  • The arithmetic mean used during cluster construction
  • Why UPGMA always produces ultrametric trees
  • Examples demonstrating successful reconstruction from strict molecular clock simulations
  • Examples illustrating the limitations of UPGMA when applied to relaxed molecular clock simulations

Educational Notes

UPGMA is the first phylogenetic reconstruction algorithm implemented in the project and provides an accessible introduction to distance-based tree reconstruction.

Because UPGMA assumes a strict molecular clock, it performs well when reconstructing trees generated by the project’s strict clock simulator. Applying the same algorithm to relaxed-clock simulations demonstrates one of the fundamental assumptions—and limitations—of UPGMA: while it always reconstructs an ultrametric tree, differing evolutionary rates between lineages can lead to reconstructed topologies that differ from the true simulated history.

Version 0.11.0

Interactive Distance Analysis

This release introduces a comprehensive Distance Analysis view to both the Strict and Relaxed Molecular Clock Explorers.

Until now the explorers have focused on simulating molecular evolution and visualising the resulting phylogenetic trees. This release adds the complementary perspective: analysing the simulated sequences using a range of evolutionary distance models, bridging the gap between sequence simulation and phylogenetic tree reconstruction.

The new Distance Analysis tab provides an interactive environment for exploring how observed sequence differences are transformed into estimates of evolutionary distance.

Highlights

Pairwise sequence comparison

Select any two taxa from the current simulation and inspect their relationship in detail, including:

• Sequence length
• Number of differing sites
• Hamming distance
• Proportional (p-) distance
• Model-corrected evolutionary distance
• Transition and transversion counts
• Transition/transversion ratio
• Observed nucleotide frequencies (where applicable)

Multiple substitution models

Distance calculations can now be performed using any of the substitution models currently implemented by the project:

• Hamming Distance
• Proportional Distance
• JC69
• K80
• F81
• HKY85

This makes it easy to explore how increasingly sophisticated biological assumptions influence estimated evolutionary distance.

Distance correction visualisation

A new Distance Correction panel illustrates the effect of the selected substitution model by comparing:

• Observed p-distance
• Corrected evolutionary distance
• Model correction
• Estimated hidden substitutions

This helps demonstrate one of the central ideas of molecular evolution: observed sequence differences typically underestimate the total number of substitutions that have occurred because multiple mutations can accumulate at the same nucleotide position over evolutionary time.

Interactive distance matrix

The complete pairwise distance matrix is now presented as an interactive heatmap, allowing relationships between taxa to be explored visually.

The underlying numeric matrix remains available for inspection via an expandable table.

Educational model summaries

Each substitution model now includes a concise explanation describing:

• The biological assumptions introduced by the model;
• Why the correction is required; and
• How it extends earlier substitution models.

These summaries reinforce the educational focus of the project by connecting the mathematics with the underlying biology.

Why this release matters

Distance matrices are the foundation of many phylogenetic reconstruction algorithms. By making the distance calculation process interactive and visual, this release provides an important bridge between simulated sequence evolution and the phylogenetic tree-building algorithms that will follow in future releases.

Rather than treating substitution models as opaque mathematical formulae, the Distance Analysis view aims to show why each model exists and how it changes our estimate of evolutionary distance.

As the project progresses towards implementing UPGMA and other tree reconstruction algorithms, the Distance Analysis tab provides the conceptual link between sequence simulation and phylogenetic inference.

Version 0.10.0

Configurable Nucleotide Exchangeabilities

This release completes the planned evolution of the molecular clock simulation engines by introducing configurable nucleotide exchangeability rates.

Previous releases progressively introduced increasingly realistic biological assumptions:

• Transition/transversion bias (K80)
• Unequal equilibrium nucleotide frequencies (F81)
• The combination of both (HKY85)

This release generalises the mutation model further by allowing each reversible nucleotide pair to have its own substitution weight.

For example:

"exchangeability_rates": {
  "A_C": 1.0,
  "A_G": 3.0,
  "A_T": 0.8,
  "C_G": 0.8,
  "C_T": 3.0,
  "G_T": 1.0
}

When a mutation occurs, the destination nucleotide is now selected using:

exchangeability(source, target) × equilibrium_frequency(target)

This provides a more flexible and biologically realistic mutation model while remaining conceptually straightforward.

Importantly, this release deliberately stops short of implementing the full General Time Reversible (GTR) substitution model. Although GTR uses the same biological concepts of exchangeability and equilibrium nucleotide frequencies, it also introduces continuous-time Markov modelling, matrix exponentials and numerical optimisation to estimate evolutionary distances.

As the primary goal of the Molecular Clock Simulator is educational, this project focuses on understanding and simulating the biological assumptions underlying molecular evolution rather than the mathematical techniques used for phylogenetic inference.

Version 0.9.0

Hasegawa–Kishino–Yano (HKY85) Substitution Model

This release extends the Molecular Clock Simulator with support for the Hasegawa-Kishino-Yano 1985 (HKY85) nucleotide substitution model in the distance matrix calculator.

HKY85 combines the two biological refinements introduced by the previous substitution-model releases. Like F81, it uses empirical nucleotide frequencies estimated from each pairwise sequence comparison. Like K80, it distinguishes transitions from transversions when correcting observed sequence divergence.

What's New

• Added the HKY85 evolutionary distance model to the distance matrix calculator
• Added --distance-type hky85 as a supported command-line option
• Added unit coverage for identity, transition-only, balanced-frequency, saturated-input, matrix, and CLI behaviours
• Updated the Distance Matrix Calculator wiki page and Wiki Home page to include HKY85

Why this Matters

HKY85 marks the next step in the project's substitution-model progression by combining unequal base frequencies with transition/transversion bias in a single corrected distance estimate.

This provides a more realistic model-based distance option while preserving the project's incremental educational structure from observed differences through JC69, K80, F81, and now HKY85.

Version 0.8.0

F81 Substitution Model

This release extends the Molecular Clock Simulator with support for the Felsenstein 1981 (F81) nucleotide substitution model and introduces configurable equilibrium nucleotide frequencies into the simulation engines.

F81 builds on the earlier Jukes–Cantor (JC69) model by relaxing the assumption that all four nucleotides occur with equal frequency. Instead, the model allows arbitrary equilibrium frequencies for A, C, G and T while continuing to treat all substitution types as occurring at the same underlying rate.

To complement the new distance model, both the strict and relaxed molecular clock simulators now generate mutations using configurable equilibrium nucleotide frequencies. Rather than selecting replacement nucleotides uniformly, mutations are biased towards the configured long-term nucleotide composition. This allows simulated sequences to converge naturally towards realistic AT- or GC-rich compositions over evolutionary time, while preserving the existing transition/transversion behaviour introduced in the previous release.

What’s New

• Added the Felsenstein 1981 (F81) evolutionary distance model to the distance matrix calculator.
• Introduced configurable equilibrium nucleotide frequencies to the biology module.
• Updated the strict molecular clock simulator to generate mutations using equilibrium nucleotide frequencies.
• Updated the relaxed molecular clock simulator to generate mutations using equilibrium nucleotide frequencies.
• Kept mutation behaviour encapsulated within the shared biology module, requiring no architectural changes to the simulation engines.

Why this Matters

This release brings the simulation and inference components of the project into closer alignment. The distance calculator can now estimate evolutionary distances under the F81 model, while the simulation engines evolve sequences under the same biological assumption of unequal equilibrium nucleotide frequencies.

It also establishes the biological framework needed for more sophisticated substitution models, including HKY85, TN93 and GTR, which combine unequal base frequencies with increasingly realistic substitution rate models.

As with previous releases, the implementation has been developed incrementally to introduce one major evolutionary concept at a time, making both the codebase and the underlying biology easier to understand and extend.