Debian Codegraph @

man/pattern_covariance_matrix.Rd

raw
1 % Generated by roxygen2: do not edit by hand
2 % Please edit documentation in R/rma-mv.R
3 \name{pattern_covariance_matrix}
4 \alias{pattern_covariance_matrix}
5 \title{Impute a patterned block-diagonal covariance matrix}
6 \usage{
7 pattern_covariance_matrix(
8 vi,
9 cluster,
10 pattern_level,
11 r_pattern,
12 r,
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{pattern_level}{Vector of categories for each effect size, used to
26 determine which entry of the pattern matrix will be used to impute a
27 correlation.}
28
29 \item{r_pattern}{Patterned correlation matrix with row and column names
30 corresponding to the levels of \code{pattern}.}
31
32 \item{r}{Vector or numeric value of assumed constant correlation(s) between
33 effect size estimates from each study.}
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{pattern_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{pattern_covariance_matrix} calculates a
70 block-diagonal covariance matrix, given the marginal variances, the block
71 structure, and an assumed correlation structure defined by a patterned
72 correlation matrix.
73 }
74 \details{
75 A block-diagonal variance-covariance matrix (possibly represented as
76 a list of matrices) with a specified correlation structure, defined by a
77 patterned correlation matrix. Let \eqn{v_{ij}}{v-ij} denote the specified
78 variance for effect \eqn{i}{i} in cluster \eqn{j}{j} and
79 \eqn{C_{hij}}{C-hij} be the covariance between effects \eqn{h}{h} and
80 \eqn{i}{i} in cluster \eqn{j}{j}. Let \eqn{p_{ij}}{p-ij} be the level
81 of the pattern variable for effect \eqn{i}{i} in cluster \eqn{j}{j},
82 taking a value in \eqn{1,...,C}{1,...,C}. A patterned correlation matrix
83 is defined as a set of correlations between pairs of effects taking each
84 possible combination of patterns. Formally, let \eqn{r_{cd}}{r-cd} be the
85 correlation between effects in categories \eqn{c}{c} and \eqn{d}{d},
86 respectively, where \eqn{r_{cd} = r_{dc}}{r-cd = r-dc}. Then the
87 covariance between effects \eqn{h}{h} and \eqn{i}{i} in cluster
88 \eqn{j}{j} is taken to be \deqn{C_{hij} = \sqrt{v_{hj} v_{ij}} \times
89 r_{p_{hj} p_{ij}}.}{C-hij = sqrt(v-hj v-ij) * r[p-hj, p-ij].}
90
91 Correlations between effect sizes within the same category are defined by the diagonal
92 values of the pattern matrix, which may take values less than one.
93
94 Combinations of pattern levels that do not occur in the patterned correlation matrix will be set equal to \code{r}.
95
96 If \code{smooth_vi = TRUE}, then all of the variances within cluster
97 \eqn{j}{j} will be set equal to the average variance of cluster
98 \eqn{j}{j}, i.e., \deqn{v'_{ij} = \frac{1}{n_j} \sum_{i=1}^{n_j}
99 v_{ij}}{v-ij' = (v-1j + ... + v-nj,j) / n-j} for
100 \eqn{i=1,...,n_j}{i=1,...,n-j} and \eqn{j=1,...,k}{j=1,...,k}.
101 }
102 \examples{
103
104 pkgs_available <-
105 requireNamespace("metafor", quietly = TRUE) &
106 requireNamespace("robumeta", quietly = TRUE)
107
108 if (pkgs_available) {
109 library(metafor)
110
111 data(oswald2013, package = "robumeta")
112 dat <- escalc(data = oswald2013, measure = "ZCOR", ri = R, ni = N)
113 subset_ids <- unique(dat$Study)[1:20]
114 dat <- subset(dat, Study \%in\% subset_ids)
115
116 # make a patterned correlation matrix
117
118 p_levels <- levels(dat$Crit.Cat)
119 r_pattern <- 0.7^as.matrix(dist(1:length(p_levels)))
120 diag(r_pattern) <- seq(0.75, 0.95, length.out = 6)
121 rownames(r_pattern) <- colnames(r_pattern) <- p_levels
122
123 # impute the covariance matrix using patterned correlations
124 V_list <- pattern_covariance_matrix(vi = dat$vi,
125 cluster = dat$Study,
126 pattern_level = dat$Crit.Cat,
127 r_pattern = r_pattern,
128 smooth_vi = TRUE)
129
130 # fit a model using imputed covariance matrix
131
132 MVFE <- rma.mv(yi ~ 0 + Crit.Cat, V = V_list,
133 random = ~ Crit.Cat | Study,
134 data = dat)
135
136 conf_int(MVFE, vcov = "CR2")
137
138 }
139
140 }