cov_trait {simtrait}

The model covariance matrix of the trait

Description

This function returns the expected covariance matrix of trait vectors simulated via sim_trait() and sim_trait_mvn(). Below there are n individuals.

Usage

cov_trait(kinship, herit, sigma_sq = 1, labs = NULL, labs_sigma_sq = NULL)

Arguments

kinship

The n-by-n kinship matrix of the individuals. These values should be scaled such that an outbred individual has 1/2 self-kinship, the parent-child relationship is 1/4, etc (which is half the values sometimes defined for kinship).

herit

The desired heritability (proportion of trait variance due to genetics).

sigma_sq

The desired parametric variance factor of the trait (scalar, default 1). Corresponds to the variance of an outbred individual.

labs

Optional labels assigning individuals to groups, to simulate group effects. If vector, length must be number of individuals. If matrix, individuals must be along rows, and levels along columns (for multiple levels of group effects). The levels are not required to be nested (as the name may falsely imply). Values can be numeric or strings, simply assigning the same values to individuals in the same group. If this is non-NULL, then labs_sigma_sq must also be given!

labs_sigma_sq

Optional vector of group effect variance proportions, one value for each level given in labs (a scalar if labs is a vector, otherwise its length should be the number of columns of labs). Ignored unless labs is also given. As these are variance proportions, each value must be non-negative and sum(labs_sigma_sq) + herit <= 1 is required so residual variance is non-negative.

Value

The n-by-n trait covariance matrix, which under no environment effects equals sigma_sq * ( herit * 2 * kinship + sigma_sq_residual * I ), where I is the n-by-n identity matrix and sigma_sq_residual = 1 - herit. If there are labels, covariance will include the specified block diagonal effects and sigma_sq_residual = 1 - herit - sum(labs_sigma_sq).

See Also

sim_trait(), sim_trait_mvn()

Examples

# create a dummy kinship matrix
kinship <- matrix(
    data = c(
        0.6, 0.1, 0.0,
        0.1, 0.6, 0.1,
        0.0, 0.1, 0.6
    ),
    nrow = 3,
    byrow = TRUE
)
# covariance of simulated traits
V <- cov_trait(kinship = kinship, herit = 0.8)