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