QGglmm (version 0.8.0)

QGvar.exp: Compute the variance of expected values (i.e. the latent values after inverse-link transformation.)

Description

This function computes the variance of the expected values, i.e. the variance of the latent values after transformation through the inverse-link function. This variance, added to the distribution variance, yields to the phenotypic variance on the observed scale.

Usage

QGvar.exp(mu = NULL, var, link.inv, obs.mean = NULL, predict = NULL, width = 10)

Value

This function yields the variance of the expected values. (numeric)

Arguments

mu

Latent intercept estimated from a GLMM (ignored if predict is not NULL). (numeric of length 1)

var

Latent total phenotypic variance estimated from a GLMM. Usually, the sum of the estimated variances of the random effects, plus the "residual" variance. (numeric of length 1)

link.inv

Inverse function of the link function. (function)

obs.mean

Optional parameter giving the phenotypic mean on the observed scale. Automatically computed if not provided. (numeric)

predict

Optional vector of predicted values on the latent scale (i.e. matrix product Xb). The latent predicted values must be computed while only accounting for the fixed effects (marginal to the random effects). (numeric)

width

Parameter for the integral computation. The integral is evaluated from mu - width * sqrt(var) to mu + width * sqrt(var). The default value is 10, which should be sensible for most models. (numeric)

Author

Pierre de Villemereuil & Michael B. Morrissey

Details

The variance of the expected values is the variance that directly arise from the variance of the latent values, but after transformation through the inverse-link function. For example, using a logarithm link, this is the variance of exp(l) where l is the latent trait.

To compute the variance, the function needs the phenotypic mean on the observed scale. If this was already computed, it can be provided using the optional argument obs.mean, which will save computing time. Otherwise (default), the function will compute the mean on the observed scale before computing the variance.

This variance, when added to the distribution variance (see QGvar.dist) yields the phenotypic variance on the observed scale.

The function required for link.inv is yielded by QGlink.funcs according to a given distribution.link model (see Example below).

Contrary to QGparams, QGvar.dist never uses the closed form solutions, but always compute the integrals.

See Also

QGvar.dist, QGparams, QGpred, QGlink.funcs, QGmean, QGpsi

Examples

## Example using Poisson.log model
mu <- 1
va <- 0.2
vp <- 0.5

# The inverse-link for a logarithm link is the exponential
inv.link<- function(x){exp(x)}

# We can then calculate the variance of expected values
QGvar.exp(mu = mu, var = vp, link.inv = inv.link)

# The mean on the observed scale can be computed beforehand
y_bar <- QGmean(mu = mu, var = vp, link.inv = inv.link)
QGvar.exp(mu = mu, var = vp, obs.mean = y_bar, link.inv = inv.link)

# The QGlink.funcs gives a ready - to - use inverse-link function
funcs<- QGlink.funcs(name = "Poisson.log")

# Calculating the distribution variance
vexp <- QGvar.exp(mu = mu, var = vp, obs.mean = y_bar, link.inv = funcs$var.func)

vexp           # Same value as above

# Calculating the associated distribution variance
vdist <- QGvar.dist(mu = mu, var = vp, var.func = funcs$var.func)

# The phenotypic variance on the observed scale is then:
vexp + vdist

# This computation is automatically performed by QGparams
# but directly using the closed form solutions when available
QGparams(mu = mu, var.p = vp, var.a = va, model = "Poisson.log")
# var.obs is equal to the sum above