Relaxed Molecular Clock Explorer
The Relaxed Molecular Clock Explorer provides an interactive environment for exploring the behaviour of the project's relaxed molecular clock simulation.
Built on top of the Relaxed Molecular Clock Engine, the explorer allows simulation parameters to be adjusted interactively before generating a new evolutionary history with a single click. The resulting phylogenetic tree is displayed immediately, allowing the effects of lineage-specific mutation rates to be explored visually.
Like the Strict Molecular Clock Explorer, this application complements the existing command-line interface rather than replacing it. Both interfaces use the same underlying simulation engine and produce identical evolutionary models.
The explorer currently provides:
- Interactive adjustment of simulation parameters
- Generation of relaxed molecular clock simulations
- Interactive visualisation of the resulting phylogenetic tree
- Branch-level genetic distance and observed substitution counts
- Simulation summary statistics
- Export of FASTA, Newick and JSON outputs
- Dark theme consistent with the Field Notes visual style
The command-line interface remains the recommended approach for automated generation of datasets, while the explorer is intended for experimentation and learning.
The explorer exposes the principal simulation parameters through an interactive sidebar.
Current parameters include:
| Parameter | Description |
|---|---|
| Tree depth | Number of branching levels in the simulated phylogeny. |
| Branch duration | Evolutionary time represented by each branch. |
| Duration jitter | Optional variation in branch durations. Zero maintains a perfectly ultrametric time tree |
| Parameter | Description |
|---|---|
| Sequence length | Length of the simulated DNA sequence for every taxon |
| Parameter | Description |
|---|---|
| Root rate | Initial mutation rate assigned to the root lineage. |
| Rate sigma | Controls the magnitude of lineage-specific rate variation. Larger values produce greater divergence between descendant lineages |
| Minimum rate | Lower bound on permitted lineage mutation rates. |
| Maximum rate | Upper bound on permitted lineage mutation rates. |
| Parameter | Description |
|---|---|
| Newick branch lengths | Controls whether exported branch lengths represent elapsed time or accumulated genetic change |
| Parameter | Description |
|---|---|
| Allow back mutation | Determines whether nucleotides may mutate back to previously occupied states during sequence evolution |
| Parameter | Description |
|---|---|
| Random seed | Controls the pseudo-random simulation. Using the same configuration and seed reproduces the same evolutionary history |
After modifying one or more parameters, selecting Generate runs a new simulation using the updated configuration.
The primary output of the explorer is an interactive visualisation of the generated phylogenetic tree.
The displayed tree represents the true evolutionary history produced by the simulation. It is not inferred from sequence data, but instead represents the known ground truth generated by the simulator.
Unlike the strict molecular clock model, individual branches may accumulate different amounts of genetic change despite representing the same elapsed evolutionary time.
Each branch displays:
- Accumulated genetic change
- Observed substitutions generated during sequence evolution
These annotations make it easy to compare neighbouring lineages and observe the effects of lineage-specific mutation rates throughout the tree.
Following each simulation the explorer displays a summary including:
- Number of taxa
- Sequence length
- Total observed mutations
- Random seed
- Mean lineage mutation rate
- Minimum lineage mutation rate
- Maximum lineage mutation rate
- Expected substitutions
These statistics provide a concise overview of the generated simulation and help illustrate how evolutionary rates vary across the phylogeny.
The explorer is built directly on the project's Relaxed Molecular Clock Engine.
The existing command-line interface remains fully supported and continues to provide reproducible generation of FASTA, Newick and JSON outputs suitable for downstream analysis.
The explorer is intended as an additional way of interacting with the simulator rather than an alternative implementation.
To run the explorer, first create a virtual environment. From the root of the project:
python -m venv venv
. venv/bin/activate
pip install --upgrade pip
pip install -e .These commands are correct for macOS/Linux but may need modification for Windows.
Once the environment has been created and activated, run the explorer as follows:
streamlit run src/relaxedclock/explorer.py