Library for the Development and Use of Phylogenetic Network Methods
Time-reversible nucleotide substitution models (GTR, JC, K80, F81, HKY, K81, SYM, TN93).
Class of exception that gets raised when there is an error in the formulation of a substitution model, whether it be inputs that don't adhere to requirements or there is an issue in computation.
General superclass for time reversable substitution models. Implements Eigenvalue decomposition for computing e^(Q*t). Special case subclasses attempt to improve on the time complexity of the matrix exponential operation. This is the Generalized Time Reversible (GTR) model.
Create a GTR substitution model object with the required/needed parameters.
| Parameter | Type | Description |
|---|---|---|
| base_freqs | list[float] | An array of floats of 'states' length. Must sum to 1. |
| transitions | list[float] | An array of floats that is ('states'^2 - 'states') / 2 long. |
| states | int, optional | Number of possible data states. Defaults to 4 (For DNA, {A, C, G, T}). |
SubstitutionModelError: If the base frequency or transition arrays are malformed.Get the Q matrix.
Change this model's free parameters and recompute the Q matrix. Accepted names are listed in this class's ``HYPERPARAMS``; anything else raises, since a silently ignored name would leave the caller believing a change took effect.
| Parameter | Type | Description |
|---|---|---|
| params | dict[str, Any] | A mapping from parameter names to their values. For the GTR superclass the names are "states" (int), "base frequencies" (list[float]) and "transitions" (list[float]). |
SubstitutionModelError: If a parameter name is not one this model accepts, or if the resulting values are malformed/invalid.Gets the base frequency and transition arrays.
Get the number of states for this substitution model.
Populate the normalized Q matrix with the correct values. Based on (7), Tavaré's GTR parameterization. Off-diagonal entries are ``Q[i][j] = r_ij * pi_j``, where ``r_ij`` is the symmetric exchangeability for the pair {i, j}. Multiplying by the *destination* frequency is what makes Q time reversible, i.e. ``pi_i * Q[i][j] == pi_j * Q[j][i]``, with pi as its stationary distribution. Diagonal entries are set so that rows sum to 0, and the whole matrix is then scaled so the expected number of substitutions per unit time is 1 (``-sum_i pi_i Q_ii == 1``), which makes t directly interpretable as branch length in substitutions per site.
SubstitutionModelError: If the resulting matrix is degenerate (a non-positive overall substitution rate).Compute the matrix exponential e^(Q*t) and store the result. The eigendecomposition of Q is cached, so repeated calls with different values of t only cost a rescaling and one matrix product.
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). The Jukes Cantor model is the simplest of all time reversible models, in which all parameters (transitions, base frequencies) are assumed to be equal. JC has no free parameters, so :meth:`set_hyperparams` rejects everything. A closed form for the matrix exponential, e^(Q*t), exists.
No arguments need to be provided, as the JC Q matrix is fixed.
Compute the matrix exponential e^(Q*t) and store the result. For JC, a closed form solution for e^(Q*t) exists and we do not need to perform any exponentiation. With all rates and frequencies equal, the normalized Q has off-diagonals 1/3 and diagonal -1, giving P(no change) = 1/4 + 3/4 e^(-4t/3) P(change) = 1/4 - 1/4 e^(-4t/3)
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Kimura 2 parameter model from (1). Also known as K80 or K2P. Parameterized by ``kappa``, the transition/transversion rate ratio. This is the standard parameterization: because Q is normalized to unit mean rate, only the *ratio* of the two rates is identifiable, so kappa is the model's single free parameter. It is also how BEAST, MrBayes, RAxML, PAML and PhyloNet expose K80/HKY, and how this library's own sequence-likelihood engine takes HKY85. ``kappa == 1`` gives Jukes-Cantor, and empirical DNA estimates usually fall in the 2-10 range. Kimura's original notation writes the rate matrix with a transition rate alpha and a transversion rate beta, where ``kappa = alpha / beta``. Both are available as read-only properties holding the normalized rates, whi...
Normalized transition rate (A<->G, C<->T), in Kimura's notation. Equals ``Q[A][G]``, and satisfies ``alpha / beta == kappa`` and ``alpha + 2 * beta == 1``.
Normalized transversion rate, in Kimura's notation. Equals ``Q[A][C]``, and satisfies ``alpha + 2 * beta == 1``.
Initialize a K80 model from a transition/transversion rate ratio.
| Parameter | Type | Description |
|---|---|---|
| kappa | float | Transition/transversion rate ratio. ``kappa == 1`` is Jukes-Cantor. If you have separate transition and transversion rates alpha and beta, pass ``alpha / beta``. |
SubstitutionModelError: If kappa is not positive and finite.Compute the matrix exponential e^(Q*t) and store the result. For K2P, a closed form solution for e^(Q*t) exists and we do not need to perform any exponentiation. K80 is HKY with uniform base frequencies, so this defers to the shared Tamura-Nei kernel with a single transition rate. In terms of the normalized rates alpha (transition) and beta (transversion), where alpha + 2 beta = 1, that kernel reduces to the familiar Kimura 2-parameter equations: P(no change) = 1/4 + 1/4 e^(-4 beta t) + 1/2 e^(-2 (alpha + beta) t) P(transition) = 1/4 + 1/4 e^(-4 beta t) - 1/2 e^(-2 (alpha + beta) t) P(transversion) = 1/4 - 1/4 e^(-4 beta t)
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Formulated by Felsenstein in 1981, this substitution model assumes that all base frequencies are free, but all transition probabilities are equal. A closed form for the matrix (Q) exponential exists.
Initialize the F81 model with a list of base frequencies of length 4. Transition probabilities will all be the same.
| Parameter | Type | Description |
|---|---|---|
| bases | list[float] | a list of 4 base frequency values. |
SubstitutionModelError: If the base frequencies given do not sum to 1 or if the list does not have exactly 4 elements.Compute the matrix exponential e^(Q*t) and store the result. For F81, a closed form solution for e^(Q*t) exists and we do not need to perform any exponentiation. Because every exchangeability is equal, Q collapses to ``u * (1 pi^T - I)``, whose exponential is P(t) = e^(-u t) I + (1 - e^(-u t)) 1 pi^T i.e. ``P[i][j] = pi_j + (delta_ij - pi_j) e^(-u t)``, with ``u = 1 / (1 - sum_i pi_i^2)`` fixing the expected substitution rate at 1. Setting pi = 1/4 recovers the Jukes-Cantor equations with u = 4/3.
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Developed by Hasegawa et al. (3). Free base frequencies plus a single transition/transversion rate ratio, ``kappa``: all four transversions share one rate and both transitions share another. HKY sits between F81 (``kappa == 1``) and TN93 (which frees the purine and pyrimidine ratios from each other), and reduces to K80 when the base frequencies are uniform.
Initialize the HKY model with 4 base frequencies that sum to 1 and a transition/transversion rate ratio.
| Parameter | Type | Description |
|---|---|---|
| base_freqs | list[float] | Array of 4 values that sum to 1, in |
| A | C, G, T order. | |
| kappa | float | Transition/transversion rate ratio. ``kappa == 1`` gives F81. |
SubstitutionModelError: If the base frequencies are malformed or kappa is not positive and finite.Compute the matrix exponential e^(Q*t) and store the result. HKY is the special case of TN93 in which the purine and pyrimidine transition rates are equal, so the Tamura-Nei closed form applies and no exponentiation is needed.
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Developed by Tamura and Nei in 1993 (4). Like HKY, but the purine transition A<->G and the pyrimidine transition C<->T get separate transition/transversion ratios instead of sharing one. Base frequencies are free. This is the most general model in the module that still has a closed-form matrix exponential; HKY (``kappa_r == kappa_y``), K80 and F81 are all special cases of it.
Initialize with 4 base frequencies that sum to 1 and the two transition/transversion rate ratios.
| Parameter | Type | Description |
|---|---|---|
| base_freqs | list[float] | A list of 4 base frequencies, in |
| A | C, G, T order. | |
| kappa_r | float | Purine (R = A/G) transition/transversion ratio, governing A<->G. |
| kappa_y | float | Pyrimidine (Y = C/T) transition/transversion ratio, governing C<->T. |
SubstitutionModelError: If the base frequencies are malformed or either ratio is not positive and finite.Compute the matrix exponential e^(Q*t) and store the result. TN93 admits a closed form (see :func:`_tn93_p_matrix`), so no exponentiation is needed.
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Developed by Kimura in 1981 (5). Also known as K3ST or K3P. Base frequencies are equal, and the six substitution types collapse into three rate classes: alpha -- transitions, A<->G and C<->T beta -- transversions, A<->C and G<->T gamma -- transversions, A<->T and C<->G K80 is the special case ``beta == gamma``. The rates are scale free, since normalizing Q discards their overall magnitude and keeps only their ratios; they are stored exactly as given, so ``alpha``, ``beta`` and ``gamma`` read back the values passed in. Use :meth:`getQ` for the normalized rates.
Initialize with the three K3ST rate classes. Only the ratios between the three matter, so ``K81(1, 5, 2)`` and ``K81(2, 10, 4)`` are the same model.
| Parameter | Type | Description |
|---|---|---|
| alpha | float | Transition rate, shared by A<->G and C<->T. |
| beta | float | Transversion rate, shared by A<->C and G<->T. |
| gamma | float | Transversion rate, shared by A<->T and C<->G. |
SubstitutionModelError: If any rate is not positive and finite.Compute the matrix exponential e^(Q*t) and store the result. K81 has three rate classes over uniform base frequencies, which the characters of the Klein four-group diagonalize exactly, so a closed form exists and no exponentiation is needed. See :func:`_k3st_p_matrix`.
| Parameter | Type | Description |
|---|---|---|
| t | float | Generally going to be a positive number for phylogenetic applications. Represents time, in coalescent units or any other unit. Negative values are clamped to 0. |
For DNA only (4 states, 6 transitions). Developed by Zharkikh in 1994 (6), this model assumes that all base frequencies are equal, and all six exchangeabilities are free. Because nothing constrains the six rates, SYM has no closed form for ``e^(Q*t)`` and inherits :meth:`GTR.expt`. Uniform base frequencies do make Q symmetric, so that cached eigendecomposition is exact and cheap.
Initialize with a list of 6 free transition probabilities. Base frequencies are all equal.
| Parameter | Type | Description |
|---|---|---|
| transitions | list[float] | A list of 6 transition rates, in |
| AC | AG, AT, CG, CT, GT order. |
SubstitutionModelError: if the transitions array is not of length 6.