Strict Molecular Clock Explorer
The Strict Molecular Clock Explorer provides an interactive environment for exploring the behaviour of the project's strict molecular clock simulation.
Built on top of the strict clock simulation 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, making it easy to experiment with different parameter combinations and develop an intuition for how the simulation behaves.
The explorer 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 strict molecular clock simulations
- Interactive visualisation of the resulting phylogenetic tree
- Simulation summary statistics
- Dark theme consistent with the Field Notes visual style
The command-line interface remains the recommended approach for automated generation of FASTA and Newick outputs, 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 |
|---|---|
| Number of taxa | Number of extant taxa to simulate. |
| Sequence length | Length of each simulated DNA sequence. |
| Mutation rate | Probability of mutation during sequence evolution. |
| Random seed | Seed controlling the pseudo-random simulation. Identical seeds produce identical simulations. |
| Branching model | Strategy used to construct the phylogenetic topology (for example balanced or random). |
| Root age | Age assigned to the root of the simulated phylogeny. |
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 rather is the ground truth against which future phylogenetic reconstruction algorithms can be compared.
Under the strict molecular clock model:
- All extant taxa terminate at the same evolutionary time.
- Branch lengths represent elapsed evolutionary time.
- Internal nodes represent simulated divergence events.
Different branching models may produce markedly different topologies while remaining fully ultrametric.
Following each simulation the explorer displays a summary including:
- Number of taxa
- Sequence length
- Total simulated mutations
- Random seed
This information provides a concise overview of the generated simulation and allows runs to be reproduced simply by reusing the same parameter set and random seed.
The explorer is built directly on the project's simulation library.
The existing command-line interface remains fully supported and continues to provide generation of FASTA and Newick files 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/strictclock/explorer.py