QGmvicc: Intra - Class Correlation coefficients (ICC) on the observed...
In QGglmm: Estimate Quantitative Genetics Parameters from Generalised Linear Mixed Models

Description Usage Arguments Details Value Author(s) See Also Examples

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.

1 2	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)

`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.

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.

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.

Pierre de Villemereuil & Michael B. Morrissey

QGmvparams, QGlink.funcs, QGmvmean, QGvcov, QGmvpsi

## 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!

[1] "Computing observed mean..."
[1] "Computing phenotypic variance-covariance matrix..."
[1] "Computing component variance-covariance matrix..."
$mean.obs
[1] 0.5001402 1.0002915

$vcv.P.obs
              [,1]          [,2]
[1,]  0.2500978661 -0.0001412643
[2,] -0.0001412643  3.9990107718

$vcv.comp.obs
              [,1]          [,2]
[1,]  0.0158363202 -0.0002085139
[2,] -0.0002085139  0.9997578095