GTR Module v1.0.0

The GTR module implements the Generalized Time Reversible (GTR) substitution model and its special-case subclasses (JC, K80, F81, HKY, K81, SYM, TN93) for phylogenetic analysis.

Author:: Mark Kessler
Last Edit:: 3/11/25
Source:: GTR.py

Exceptions

exception SubstitutionModelError(Exception)

Raised when there is an error in the formulation of a substitution model, whether from invalid inputs or computation issues.

GTR Class

class GTR

Generalized Time Reversible model. Superclass for all time-reversible substitution models. Implements eigenvalue decomposition for computing matrix exponential e^(Q*t).

Constructor

__init__(self, base_freqs: list[float], transitions: list[float], states: int = 4)

Create a GTR substitution model.

Parameter	Type	Description
base_freqs	list[float]	Array of state frequencies (must sum to 1)
transitions	list[float]	Array of transition rates ((states^2 - states) / 2 long)
states	int	Number of states (default 4 for DNA)

Methods

getQ(self) -> np.ndarray

Get the Q (instantaneous rate) matrix.

buildQ(self) -> np.ndarray

Populate and normalize the Q matrix.

expt(self, t: float) -> np.ndarray

Compute matrix exponential e^(Q*t) using eigenvalue decomposition.

Parameter	Type	Description
t	float	Time (typically in coalescent units)

Returns: np.ndarray - The transition probability matrix

set_hyperparams(self, params: dict) -> None

Change parameters and recompute Q. Keys: "states", "base frequencies", "transitions".

get_hyperparams(self) -> tuple

Get (base_freqs, transitions) tuple.

state_count(self) -> int

Get number of states.

Subclasses

JC (Jukes-Cantor 1969)

class JC(GTR)

Simplest model. All base frequencies and transition rates are equal.

__init__(self)

No arguments needed - Q matrix is fixed.

K80 (Kimura 1980)

class K80(GTR)

Two-parameter model. Equal base frequencies, distinct transition and transversion rates.

__init__(self, alpha: float, beta: float)

Initialize with transversion (alpha) and transition (beta) parameters. Must sum to 1. Has closed-form solution for e^(Q*t).

F81 (Felsenstein 1981)

class F81(GTR)

Free base frequencies, equal transition rates.

__init__(self, bases: list[float])

Initialize with 4 base frequencies summing to 1.

HKY (Hasegawa et al. 1985)

class HKY(GTR)

Free base frequencies. Transversions equal, transitions equal (pattern [a, b, a, a, b, a]).

__init__(self, base_freqs: list[float], transitions: list[float])

K81 (Kimura 1981)

class K81(GTR)

Equal base frequencies. Transition rates follow pattern [a, b, c, c, b, a].

__init__(self, transitions: list[float])

SYM (Zharkikh 1994)

class SYM(GTR)

Equal base frequencies, all 6 transition rates free.

__init__(self, transitions: list[float])

TN93 (Tamura and Nei 1993)

class TN93(GTR)

Free base frequencies. Two different transition parameters (pattern [a, b, a, a, c, a]).

__init__(self, base_freqs: list[float], transitions: list[float])

Model Comparison

Model	Free Base Freqs	Transition Pattern	Parameters
JC	No (0.25 each)	All equal	0
K80	No (0.25 each)	Ts = Tv	1
F81	Yes (4)	All equal	3
HKY	Yes (4)	Ts = Tv	4
K81	No (0.25 each)	[a,b,c,c,b,a]	2
SYM	No (0.25 each)	All free	5
TN93	Yes (4)	[a,b,a,a,c,a]	5
GTR	Yes (4)	All free	8

Usage Examples

from PhyNetPy.GTR import GTR, JC, K80, HKY, TN93
import numpy as np

# Jukes-Cantor (simplest)
jc = JC()
P = jc.expt(0.1)  # Transition prob matrix at t=0.1

# Kimura 2-parameter
k80 = K80(alpha=0.7, beta=0.3)
P = k80.expt(0.5)

# HKY model
freqs = [0.3, 0.2, 0.2, 0.3]  # Must sum to 1
trans = [1.0, 2.0, 1.0, 1.0, 2.0, 1.0]  # [a,b,a,a,b,a] pattern
hky = HKY(freqs, trans)

# Get the Q matrix
Q = hky.getQ()
print(Q)

# Update parameters
hky.set_hyperparams({"base frequencies": [0.25, 0.25, 0.25, 0.25]})

# Full GTR
gtr = GTR(
    base_freqs=[0.25, 0.25, 0.25, 0.25],
    transitions=[1.0, 2.0, 1.0, 1.0, 2.0, 1.0]
)
P = gtr.expt(1.0)

PhyNetPy Documentation