-
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 two commonly used distance measures:
- Hamming distance
- Proportional distance (p-distance)
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 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.
Only two simple distance measures are currently implemented, both of which are widely used in introductory phylogenetics.
The calculator is designed as a reusable Python module with a lightweight command-line interface, allowing the same implementation to be used directly by future tree-building algorithms such as UPGMA.
Future releases may introduce more sophisticated evolutionary distance models, including substitution-corrected distances.
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 can be used to specify the distance calculation. Accepted values are "hamming" and "proportional" and "hamming" is the default if not specified.