mutationMatrix: Mutation matrix

In magnusdv/pedmut: Mutation Models for Pedigree Likelihood Computations

Mutation matrix

Description

Construct mutation matrices for pedigree likelihood computations.

Usage

mutationMatrix(
  model = c("custom", "dawid", "equal", "proportional", "random", "onestep", "stepwise",
    "trivial"),
  matrix = NULL,
  alleles = NULL,
  afreq = NULL,
  rate = NULL,
  seed = NULL,
  rate2 = NULL,
  range = NULL,
  transform = NULL,
  validate = TRUE
)

validateMutationMatrix(mutmat, alleles = NULL)

Arguments

model	A string: either "custom", "dawid", "equal", "proportional", "random", "onestep", "stepwise" or "trivial".
matrix	When model is "custom", this must be a square matrix with nonnegative real entries and row sums equal to 1.
alleles	A character vector (or coercible to character) with allele labels. Required in all models, except "custom" if matrix has dimnames.
afreq	A numeric vector of allele frequencies. Required in model "proportional".
rate	A number between 0 and 1. Required in models "equal", "proportional", "stepwise" and "onestep".
seed	A single number. Optional parameter in the "random" model, passed on to set.seed().
rate2	A number between 0 and 1. The mutation rate between integer alleles and microvariants. Required in the "stepwise" model.
range	A positive number. The relative probability of mutating n+1 steps versus mutating n steps. Required in the "stepwise" and "dawid" models. Must be in the interval (0,1) for the "dawid" model.
transform	Either NULL (default) or one of the strings "MH", "BA", "PR", "PM". See Details.
validate	A logical (default: TRUE) indicating whether to validate custom models.
mutmat	An object of class mutationMatrix.

Details

Descriptions of the models:

• custom: Allows any mutation matrix to be provided by the user, in the matrix parameter.

• dawid: A reversible model for integer-valued markers, proposed by Dawid et al. (2002).

• equal: All mutations equally likely; probability 1-rate of no mutation.

• proportional: Mutation probabilities are proportional to the target allele frequencies.

• random: This produces a matrix of random numbers, where each row is normalised so that it sums to 1. If rate (and afreq) is provided, the mutation matrix is conditional on the overall mutation rate.

• onestep: A mutation model for markers with integer alleles, allowing mutations only to the nearest neighbours in the allelic ladder. For example, 10 may mutate to either 9 or 11, unless 10 is the lowest allele, in which case 11 is the only option. This model is not applicable to loci with non-integer microvariants.

• stepwise: A common model in forensic genetics, allowing different mutation rates between integer alleles (like 9) and non-integer microvariants (like 9.3). Mutation rates also depend on step size, as controlled by the range parameter.

• trivial: The identity matrix, implying that no mutations are possible.

If transform is non-NULL, the indicated transformation is applied to the matrix before returning. Currently, there are 4 available options:

• MH, BA, PR: See makeReversible()

• PM: See makeStationary()

Value

An object of class mutationMatrix, essentially a square numeric matrix with various attributes. The matrix has entries in ⁠[0, 1]⁠ and all rows sum to 1. Both row names and column names are the allele labels.

Examples

mutationMatrix("equal", alleles = 1:3, rate = 0.05)

mutationMatrix("random", afreq = c(a=0.3, b=0.7), rate = 0.05, seed = 1)

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