pedmut (version 0.8.0)

mutationMatrix: 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
)
validateMutationMatrix(mutmat, alleles = NULL)

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 colnames and rownames are the allele labels.

Arguments

model

A string: either "custom", "dawid", "equal", "proportional", "random", "stepwise" or "onestep".

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 the name of a transformation to be applied to the mutation model. See makeReversible().

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, the available options are 3 different transformations to reversibility, basically performed with the call makeReversible(m, method = transform, adjust = TRUE)

Examples

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

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