| 1 |
% Generated by roxygen2: do not edit by hand |
| 2 |
% Please edit documentation in R/rma-mv.R |
| 3 |
\name{impute_covariance_matrix} |
| 4 |
\alias{impute_covariance_matrix} |
| 5 |
\title{Impute a block-diagonal covariance matrix} |
| 6 |
\usage{ |
| 7 |
impute_covariance_matrix( |
| 8 |
vi, |
| 9 |
cluster, |
| 10 |
r, |
| 11 |
ti, |
| 12 |
ar1, |
| 13 |
smooth_vi = FALSE, |
| 14 |
subgroup = NULL, |
| 15 |
return_list = identical(as.factor(cluster), sort(as.factor(cluster))), |
| 16 |
check_PD = TRUE |
| 17 |
) |
| 18 |
} |
| 19 |
\arguments{ |
| 20 |
\item{vi}{Vector of variances} |
| 21 |
|
| 22 |
\item{cluster}{Vector indicating which effects belong to the same cluster. |
| 23 |
Effects with the same value of `cluster` will be treated as correlated.} |
| 24 |
|
| 25 |
\item{r}{Vector or numeric value of assumed constant correlation(s) between |
| 26 |
effect size estimates from each study.} |
| 27 |
|
| 28 |
\item{ti}{Vector of time-points describing temporal spacing of effects, for |
| 29 |
use with auto-regressive correlation structures.} |
| 30 |
|
| 31 |
\item{ar1}{Vector or numeric value of assumed AR(1) auto-correlation(s) |
| 32 |
between effect size estimates from each study. If specified, then \code{ti} |
| 33 |
argument must be specified.} |
| 34 |
|
| 35 |
\item{smooth_vi}{Logical indicating whether to smooth the marginal variances |
| 36 |
by taking the average \code{vi} within each cluster. Defaults to |
| 37 |
\code{FALSE}.} |
| 38 |
|
| 39 |
\item{subgroup}{Vector of category labels describing sub-groups of effects. |
| 40 |
If non-null, effects that share the same category label and the same |
| 41 |
cluster will be treated as correlated, but effects with different category |
| 42 |
labels will be treated as uncorrelated, even if they come from the same |
| 43 |
cluster.} |
| 44 |
|
| 45 |
\item{return_list}{Optional logical indicating whether to return a list of |
| 46 |
matrices (with one entry per block) or the full variance-covariance matrix.} |
| 47 |
|
| 48 |
\item{check_PD}{Optional logical indicating whether to check whether each |
| 49 |
covariance matrix is positive definite. If \code{TRUE} (the default), the |
| 50 |
function will display a warning if any covariance matrix is not positive |
| 51 |
definite.} |
| 52 |
} |
| 53 |
\value{ |
| 54 |
If \code{cluster} is appropriately sorted, then a list of matrices, |
| 55 |
with one entry per cluster, will be returned by default. If \code{cluster} |
| 56 |
is out of order, then the full variance-covariance matrix will be returned |
| 57 |
by default. The output structure can be controlled with the optional |
| 58 |
\code{return_list} argument. |
| 59 |
} |
| 60 |
\description{ |
| 61 |
`r lifecycle::badge("superseded")` |
| 62 |
|
| 63 |
This function is superseded by the \code{\link[metafor]{vcalc}} provided by |
| 64 |
the \code{metafor} package. Compared to \code{impute_covariance_matrix}, |
| 65 |
\code{\link[metafor]{vcalc}} provides many further features, includes a |
| 66 |
\code{data} argument, and uses syntax that is consistent with other |
| 67 |
functions in \code{metafor}. |
| 68 |
|
| 69 |
\code{impute_covariance_matrix} calculates a block-diagonal covariance |
| 70 |
matrix, given the marginal variances, the block structure, and an assumed |
| 71 |
correlation structure. Can be used to create compound-symmetric structures, |
| 72 |
AR(1) auto-correlated structures, or combinations thereof. |
| 73 |
} |
| 74 |
\details{ |
| 75 |
A block-diagonal variance-covariance matrix (possibly represented as |
| 76 |
a list of matrices) with a specified structure. The structure depends on |
| 77 |
whether the \code{r} argument, \code{ar1} argument, or both arguments are |
| 78 |
specified. Let \eqn{v_{ij}}{v-ij} denote the specified variance for effect |
| 79 |
\eqn{i}{i} in cluster \eqn{j}{j} and \eqn{C_{hij}}{C-hij} be the covariance |
| 80 |
between effects \eqn{h}{h} and \eqn{i}{i} in cluster |
| 81 |
\eqn{j}{j}. |
| 82 |
\itemize{ |
| 83 |
\item{If only \code{r} is specified, each block of the variance-covariance |
| 84 |
matrix will have a constant (compound symmetric) correlation, so that |
| 85 |
\deqn{C_{hij} = r_j \sqrt{v_{hj} v_{ij},}}{C-hij = r-j * sqrt(v-hj v-ij),} |
| 86 |
where \eqn{r_j}{r-j} is the specified correlation |
| 87 |
for cluster \eqn{j}{j}. If only a single value is given in \code{r}, then |
| 88 |
it will be used for every cluster.} |
| 89 |
\item{If only \code{ar1} is specified, each block of the variance-covariance matrix will have an |
| 90 |
AR(1) auto-correlation structure, so that |
| 91 |
\deqn{C_{hij} = \phi_j^{|t_{hj}- t_{ij}|} \sqrt{v_{hj} v_{ij},}}{C-hij = (ar1-j)^|t-hj - t-ij| * sqrt(v-hj v-ij),} |
| 92 |
where \eqn{\phi_j}{ar1-j} is the specified auto-correlation |
| 93 |
for cluster \eqn{j}{j} and \eqn{t_{hj}}{t-hj} and \eqn{t_{ij}}{t-ij} |
| 94 |
are specified time-points corresponding to effects \eqn{h}{h} and |
| 95 |
\eqn{i}{i} in cluster \eqn{j}{j}. If only a single value is given in |
| 96 |
\code{ar1}, then it will be used for every cluster.} |
| 97 |
\item{If both \code{r} and \code{ar1} are specified, each block of the variance-covariance matrix will have combination of compound symmetric and an AR(1) |
| 98 |
auto-correlation structures, so that |
| 99 |
\deqn{C_{hij} = \left[r_j + (1 - r_j)\phi_j^{|t_{hj} - t_{ij}|}\right] \sqrt{v_{hj} v_{ij},}}{C-hij = [r-j + (1 - r-j)(ar1-j)^|t-hj - t-ij|] * sqrt(v-hj v-ij),} |
| 100 |
where \eqn{r_j}{r-j} is the specified constant correlation for cluster |
| 101 |
\eqn{j}{j}, \eqn{\phi_j}{ar1-j} is the specified auto-correlation for |
| 102 |
cluster \eqn{j}{j} and \eqn{t_{hj}}{t-hj} and \eqn{t_{ij}}{t-ij} are |
| 103 |
specified time-points corresponding to effects \eqn{h}{h} and |
| 104 |
\eqn{i}{i} in cluster \eqn{j}{j}. If only single values are given in |
| 105 |
\code{r} or \code{ar1}, they will be used for every cluster.} |
| 106 |
} |
| 107 |
If \code{smooth_vi = TRUE}, then all of the variances within cluster |
| 108 |
\eqn{j}{j} will be set equal to the average variance of cluster |
| 109 |
\eqn{j}{j}, i.e., \deqn{v'_{ij} = \frac{1}{n_j} \sum_{i=1}^{n_j} |
| 110 |
v_{ij}}{v-ij' = (v-1j + ... + v-nj,j) / n-j} for |
| 111 |
\eqn{i=1,...,n_j}{i=1,...,n-j} and \eqn{j=1,...,k}{j=1,...,k}. |
| 112 |
} |
| 113 |
\examples{ |
| 114 |
|
| 115 |
if (requireNamespace("metafor", quietly = TRUE)) { |
| 116 |
|
| 117 |
library(metafor) |
| 118 |
|
| 119 |
# Constant correlation |
| 120 |
data(SATcoaching) |
| 121 |
V_list <- impute_covariance_matrix(vi = SATcoaching$V, cluster = SATcoaching$study, r = 0.66) |
| 122 |
MVFE <- rma.mv(d ~ 0 + test, V = V_list, data = SATcoaching) |
| 123 |
conf_int(MVFE, vcov = "CR2", cluster = SATcoaching$study) |
| 124 |
|
| 125 |
} |
| 126 |
|
| 127 |
} |