QGmvicc {QGglmm}

Intra - Class Correlation coefficients (ICC) on the observed data scale (multivariate analysis).

Description

Function to estimate the variance-covariance matrix of a variance component on the observed scale based on estimates on the latent scale. Contrary to the univariate function, this one cannot use the analytical closed forms and yields a list of paramaters instead of a data.frame.

Usage

    QGmvicc(mu = NULL, vcv.comp, vcv.P, models, predict = NULL, rel.acc = 0.001, 
    width = 10, n.obs = NULL, theta = NULL, verbose = TRUE, mask = NULL)

Arguments

mu

Vector of latent intercepts estimated from a GLMM (ignored if predict is not NULL). (numeric)

vcv.comp

Component variance-covariance matrix (G-matrix - like). (numeric)

vcv.P

Total phenotypic variance-covariance matrix. Usually, the sum of all the estimated variance-covariance matrices. (numeric)

models

A vector containing the names of the model used or a list which elements contain the list of the functions needed (inverse-link, distribution variance and derivative of the inverse-link, as stated in the output of QGlink.funcs()). (character vector or list of lists of functions) Available model names are :

• "Gaussian" Gaussian distribution with identity link (e.g. LMM)

• "binom1.probit" Binomial with 1 trial (binary data) with a probit link

• "binomN.probit" Binomial with N tria with a probit link (require the parameter n.obs)

• "binom1.logit" Binomial with 1 trial (binary) with a logit link

• "binomN.logit" Binomial with N trial with a logit link (require the parameter n.obs)

• "Poisson.log" Poisson distribution wiht a log link

• "Poisson.sqrt" Poisson distribution with a square - root link

• "negbin.log" Negative - Binomial distribution wiht a log link (require the parameter theta)

• "negbin.sqrt" Negative - Binomial distribution with a square - root link (require the parameter theta)

rel.acc

Relative accuracy of the integral approximation. (numeric)

width

Parameter for the integral computation. The default value is 10, which should be sensible for most models. (numeric)

predict

Optional matrix of predicted values on the latent scale (each trait in each column). The latent predicted values must be computed while only accounting for the fixed effects (marginal to the random effects). (numeric)

n.obs

Number of "trials" for each "binomN" distribution. (numeric, length equal to the number of "binomN" models)

theta

Dispersion parameter for the Negative Binomial distribution. The parameter theta should be such as the variance of the distribution is mean + mean^2 / theta. (numeric, length equal to the number of "negbin" models)

verbose

Should the function be verbose? (boolean)

mask

Masking filter for removing predictions that don't exist in the population (e.g. female predictions for males for a sex - based bivariate model). Should the same dimensions as predict and values should be FALSE when the predictions should be filtered out.

Details

The function typically uses integral numerical approximation provided by the R2Cuba package to compute multivariate quantitative genetics parameters on the observed scale, from latent estimates yielded by a GLMM. It cannot use closed form solutions.

Only the most typical distribution/link function couples are implemented through the models argument. If you used an "exotic" GLMM, you can provide a list containg lists of functions corresponding to the model. The list of functions should be implemented as is the output of QGlink.funcs(), i.e. three elements: the inverse link functions named inv.link, the derivative of this function named d.inv.link and the distribution variance named var.func (see Example below).

Some distributions require extra-arguments. This is the case for "binomN", which require the number of trials N, passed with the argument n.obs. The distribution "negbin" requires a dispersion parameter theta, such as the variance of the distribution is mean + mean^2 / theta (mean/dispersion parametrisation). For now, the arguments n.obs and theta can be used for ONE distribution only.

If fixed effects (apart from the intercept) have been included in the GLMM, they can be included through the argument predict as a matrix of the marginal predicted values, i.e. predicted values excluding the random effects, for each trait (one trait per column of the matrix, see Example below).Note that computation can be extremely slow in that case.

Value

The function yields a list containing the following values:

mean.obs

Vector of phenotypic means on the observed scale.

vcv.P.obs

Phenotypic variance-covariance matrix on the observed scale.

vcv.comp.obs

Component variance-covariance (G-matrix - like, but broad - sense) on the observed scale.

Author(s)

Pierre de Villemereuil & Michael B. Morrissey

See Also

QGmvparams, QGlink.funcs, QGmvmean, QGvcov, QGmvpsi

Examples

## Example using a bivariate model (Binary trait/Gaussian trait)
# Parameters
mu <- c(0, 1)
G <- diag(c(0.5, 2))
M <- diag(c(0.2, 1))  # Maternal effect VCV matrix
P <- diag(c(1, 4))

# Broad - sense "G-matrix" on observed data scale
## Not run: QGmvicc(mu = mu, vcv.comp = G, vcv.P = P, models = c("binom1.probit", "Gaussian"))
# Maternal effect VCV matrix on observed data scale
## Not run: QGmvicc(mu = mu, vcv.comp = M, vcv.P = P, models = c("binom1.probit", "Gaussian"))
# Reminder: the results are the same here because we have no correlation between the two traits

# Defining the model "by hand" using the list
list.models = list(
  model1 = list(inv.link = function(x){pnorm(x)},
              d.inv.link = function(x){dnorm(x)},
              var.func = function(x){pnorm(x) * (1 - pnorm(x))}),
  model2 = list(inv.link = function(x){x},
              d.inv.link = function(x){1},
              var.func = function(x){0})
)
# Running the same analysis than above
QGmvicc(mu = mu, vcv.comp = M, vcv.P = P, models = list.models)

# Using predicted values
# Say we have 100  individuals
n <- 100
# Let's simulate predicted values
p <- matrix(c(runif(n), runif(n)), ncol = 2)
# Note that p has as many as columns as we have traits (i.e. two)
# Multivariate analysis with predicted values
## Not run: QGmvicc(predict = p, vcv.comp = M, vcv.P = P, models = c("binom1.probit", "Gaussian"))
# That can be a bit long to run!