model_properties: Mutation model properties

In magnusdv/pedmut: Mutation Models for Pedigree Likelihood Computations

Mutation model properties

Description

Functions that check various properties of a mutation model, including stationarity, reversibility and lumpability.

Usage

isStationary(mutmat, afreq = NULL)

isReversible(mutmat, afreq = NULL)

isBounded(mutmat, afreq = NULL)

isLumpable(mutmat, lump)

alwaysLumpable(mutmat)

Arguments

mutmat	A mutationMatrix() or a mutationModel().
afreq	A vector with allele frequencies, of the same length as the size of mutmat.
lump	A character vector containing a nonempty set of allele labels.

Details

The function isBounded() checks that a mutation model is bounded by the allele frequencies, i.e., that mutmat[i,j] <= afreq[j] whenever i is not equal to j.

Lumpability is a property of a mutation model that allows aggregating alleles into groups, or lumps, without changing the overall mutation process. The functions isLumpable() and alwaysLumpable() checks lumpability using the row-sum criterion given by Kemeny & Snell (1976). Note that lumping may be possible even if the model is not generally lumpable; see lumpMutSpecial() for details.

For each of these functions, if mutmat is a mutationModel object, i.e., with male and female components, the output is TRUE if and only if both components satisfy the property in question.

Value

Each of these functions returns TRUE of FALSE.

References

Kemeny & Snell (1976). Finite Markov Chains. Springer.

Examples

# "proportional" models are stationary and reversible
afr = c(0.2, 0.3, 0.5)
m_prop = mutationMatrix(model = "prop", alleles = 1:3, afreq = afr, rate = 0.1)
stopifnot(isStationary(m_prop, afr), isReversible(m_prop, afr))

# "equal" model is stationary and reversible only when freqs are equal
m_eq = mutationMatrix(model = "eq", alleles = 1:3, rate = 0.1)
stopifnot(isStationary(m_eq, rep(1/3, 3)), isReversible(m_eq, rep(1/3, 3)))
stopifnot(!isStationary(m_eq, afr), !isReversible(m_eq, afr))

# "equal" and "proportional" models allow allele lumping
stopifnot(isLumpable(m_eq, lump = 1:2))
stopifnot(isLumpable(m_prop, lump = 1:2))

# In fact lumpable for any allele subset
stopifnot(alwaysLumpable(m_eq), alwaysLumpable(m_prop))

magnusdv/pedmut documentation built on June 8, 2025, 4:26 a.m.