-
Notifications
You must be signed in to change notification settings - Fork 0
Distance Matrix Calculator
The Distance Matrix Calculator generates pairwise genetic distance matrices from aligned DNA sequences contained in a FASTA file.
It is intended as a simple educational implementation that provides the first analytical step used by many phylogenetic reconstruction algorithms, including UPGMA.
The calculator currently supports three commonly used distance measures:
- Hamming distance
- Proportional distance (p-distance)
- Jukes–Cantor corrected evolutionary distance (JC69)
Together these provide a progression from simple sequence comparison through to the first model-based estimate of evolutionary divergence.
Results are written in both JSON and CSV formats for use by downstream tools or for inspection in spreadsheet software.
Unlike the molecular clock simulators, the Distance Matrix Calculator performs no evolutionary simulation. Instead, it analyses existing sequence data to quantify the genetic differences between every pair of taxa.
The calculator begins by reading an aligned FASTA file supplied on the command line. Each FASTA record becomes a taxon within the analysis.
The current implementation assumes that all sequences:
- Are aligned
- Are the same length
- Contain comparable nucleotide positions
If these conditions are not satisfied, the calculator reports an error.
Every sequence is compared with every other sequence. For each pair of taxa, the calculator examines every nucleotide position in turn.
Each position is classified as either identical or different and the total number of differing positions forms the basis of the selected distance measure.
Because genetic distance is symmetric, the calculator computes only one comparison for each pair and mirrors the result across the distance matrix.
The distance between a sequence and itself is always zero.
The Hamming distance is the simplest supported metric. It is defined as the number of nucleotide positions at which two aligned sequences differ.
For example:
Sequence A: ACTGAC
Sequence B: ACTAAC
Only one nucleotide differs, giving a Hamming distance of 1.
Hamming distance is an absolute measure of sequence difference and is most useful when all sequences are the same length.
The proportional distance (often called p-distance) normalises the Hamming distance by sequence length. It is calculated as:
proportional_distance = differing_positions / sequence_length
For example, if two sequences differ at 12 positions within a sequence of length 500:
p-distance = 12 / 500 = 0.024
This represents a 2.4% observed sequence divergence.
Unlike Hamming distance, proportional distance produces values between 0 and 1, making comparisons easier across datasets with different sequence lengths.
The proportional distance is also the simplest estimate of evolutionary divergence and is commonly used as the starting point for introductory phylogenetic algorithms.
The Jukes–Cantor (1969) model extends the proportional distance by accounting for substitutions that are no longer directly observable.
Over long periods of evolutionary time, a nucleotide position may mutate more than once. Simply counting the observed differences therefore underestimates the true number of substitution events that have occurred.
The Jukes–Cantor model assumes:
- Equal frequencies of the four nucleotides
- Equal probability of every possible nucleotide substitution
- A constant substitution rate across all sites
Using these assumptions, the corrected evolutionary distance is calculated as:
d = -3/4 × ln(1 - 4p/3)
where:
- p is the proportional distance
- d is the estimated substitutions per site
For small values of p, the corrected distance is very similar to the proportional distance.
As sequence divergence increases, however, the Jukes–Cantor correction becomes progressively larger because it compensates for substitutions that are hidden by multiple mutation events at the same nucleotide position.
The Jukes–Cantor model is only defined when:
p < 0.75
As the observed proportion of differing sites approaches 75%, sequence information becomes saturated and it is no longer possible to estimate evolutionary distance reliably using this model.
When saturation is reached, the calculator reports an infinite evolutionary distance.
The distances calculated directly from a sequence alignment (such as Hamming or proportional distance) represent the observed differences between sequences, not necessarily the true amount of evolutionary change. Over time, a single nucleotide position may undergo multiple substitutions. For example, a site might change from A → G → A, leaving no observable difference despite two mutations having occurred, or A → G → T, where two substitutions are observed as a single difference. As sequences diverge, these “hidden” substitutions become increasingly common, causing simple observed distances to underestimate the true evolutionary distance.
Substitution models address this by applying a mathematical model of sequence evolution to the observed distances. Each model makes a different set of biological assumptions—for example, that all substitutions are equally likely (JC69), that transitions occur more frequently than transversions (K80), or that nucleotide frequencies differ (HKY85 and GTR). These assumptions lead to equations that estimate the expected number of substitutions per site, producing a distance matrix that more closely reflects the underlying evolutionary history. This corrected distance matrix can then be used as the input to phylogenetic reconstruction algorithms such as UPGMA or Neighbour Joining.
The calculated distances are stored in a square matrix with rows and columns representing taxa. Each cell contains the genetic distance between the corresponding pair of sequences.
For example:
| Taxon A | Taxon B | Taxon C | |
|---|---|---|---|
| Taxon A | 0 | 2 | 5 |
| Taxon B | 2 | 0 | 4 |
| Taxon C | 5 | 4 | 0 |
The diagonal always contains zero because every sequence is identical to itself.
The matrix is symmetric because the distance from A to B is identical to the distance from B to A.
The calculator writes the completed distance matrix in two formats.
| Format | Description |
|---|---|
| CSV | Tabular representation suitable for spreadsheets and external tools |
| JSON | Structured representation suitable for downstream Python modules |
Providing both formats allows the matrix to be inspected manually while remaining easy to consume programmatically.
The Distance Matrix Calculator deliberately focuses on clarity rather than biological complexity.
The supported distance measures form a natural progression:
- Hamming distance measures the absolute number of differing nucleotide positions
- Proportional distance normalises this by sequence length to estimate observed divergence
- Jukes–Cantor applies a simple evolutionary model to estimate the true number of substitutions per site
The calculator is implemented as a reusable Python module with a lightweight command-line interface, allowing the same distance calculations to be reused directly by future phylogenetic reconstruction algorithms such as UPGMA.
Future releases may introduce more sophisticated substitution models, including Kimura 2-Parameter (K80), HKY85 and General Time Reversible (GTR).
First create and activate a virtual environment:
python -m venv venv
. venv/bin/activate
pip install --upgrade pip
pip install -e .These commands are correct for macOS/Linux but may require modification for Windows.
The calculator can then be run as follows:
python -m distancematrix --input "/path/to/sequences.fasta" --output "/path/to/output/folder"Optionally, the --distance-type argument selects the distance calculation to perform.
Supported values are:
| Distance Type | Description |
|---|---|
| hamming | Counts the number of differing nucleotide positions |
| proportional | Reports the proportion of differing positions |
| jc69 | Applies the Jukes–Cantor substitution correction |
If omitted, hamming is used by default.