Debian Codegraph @

man/impute_covariance_matrix.Rd

raw
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 }