ess {bayesmeta}  R Documentation 
Effective sample size (ESS)
Description
This function computes the effective sample size (ESS) of a posterior predictive distribution.
Usage
ess(object, ...)
## S3 method for class 'bayesmeta'
ess(object, uisd, method=c("elir", "vr", "pr", "mtm.pt"), ...)
Arguments
object 
a 
uisd 
the unit infomation standard deviation
(a single numerical value, or a 
method 
a character string specifying the method to be used for
ESS computation. By default, the expected localinformationratio
ESS ( 
... 
additional arguments 
Details
The information conveyed by a prior distribution may often be
quantified in terms of an effective sample size
(ESS). Metaanalyses are commonly utilized to summarize
“historical” information in order to inform a future study,
leading to a metaanalyticpredictive (MAP) prior (Schmidli et
al., 2014). In the context of the normalnormal hierarchical model
(NNHM), the MAP prior results as the (posterior) predictive
distribution for a “new” study mean
\theta_{k+1}
. This function computes the ESS for the
posterior predictive distribution based on a bayesmeta
object.
Within the NNHM, the notion of an effective sample size requires the
specification of a unit information standard deviation (UISD)
(Roever et al., 2020); see also the ‘uisd()
’
function's help page. The UISD \sigma_\mathrm{u}
here
determines the Fisher information for one information unit,
effectively assuming that a study's sample size n_i
and
standard error \sigma_i
are related simply as
\sigma_i=\frac{\sigma_\mathrm{u}}{\sqrt{n_i}},
i.e., the squared standard error is inversely proportional to the
sample size. For the (possibly hypothetical) case of a sample size of
n_i=1
, the standard error then is equal to the UISD
\sigma_\mathrm{u}
.
Specifying the UISD as a constant is often an approximation,
sometimes it is also possible to specify the UISD as a function of the
parameter (\mu
). For example, in case the outcome in
the metaanalyses are logodds, then the UISD varies with the (log)
odds and is given by 2\,\mathrm{cosh}(\mu/2)
(see also the example below).
The ESS may be computed or approximated in several ways. Possible choices here are:

"elir"
: the expected localinformationratio (ELIR) method (the default), 
"vr"
: the variance ratio (VR) method, 
"pr"
: the precision ratio (PR) method, 
"mtm.pt"
: the MoritaThallMueller / PennelloThompson (MTM.PM) method.
For more details on these see also Neuenschwander et al. (2020).
Value
The effective sample size (ESS).
Author(s)
Christian Roever christian.roever@med.unigoettingen.de
References
B. Neuenschwander, S. Weber, H. Schmidli, A. O'Hagan. Predictively consistent prior effective sample sizes. Biometrics, 76(2):578587, 2020. doi:10.1111/biom.13252.
H. Schmidli, S. Gsteiger, S. Roychoudhury, A. O'Hagan, D. Spiegelhalter, B. Neuenschwander. Robust metaanalyticpredictive priors in clinical trials with historical control information. Biometrics, 70(4):10231032, 2014. doi:10.1111/biom.12242.
C. Roever, R. Bender, S. Dias, C.H. Schmid, H. Schmidli, S. Sturtz, S. Weber, T. Friede. On weakly informative prior distributions for the heterogeneity parameter in Bayesian randomeffects metaanalysis. Research Synthesis Methods, 12(4):448474, 2021. doi:10.1002/jrsm.1475.
See Also
Examples
# load data set:
data("BaetenEtAl2013")
print(BaetenEtAl2013)
## Not run:
# compute effect sizes (logarithmic odds) from the count data:
as < escalc(xi=events, ni=total, slab=study,
measure="PLO", data=BaetenEtAl2013)
# estimate the unit information standard deviation (UISD):
uisd(as, individual=TRUE)
uisd(as) # = 2.35
# perform metaanalysis
# (using uniform priors for effect and heterogeneity):
bm < bayesmeta(as)
# show forest plot:
forestplot(bm, zero=NA, xlab="logodds")
# compute ESS_ELIR (based on fixed UISD):
ess(bm, uisd=2.35) # = 45.7 patients
# compute ESS_ELIR based on UISD as a function of the logodds:
uisdLogOdds < function(logodds)
{
return(2 * cosh(logodds / 2))
}
# Note: in the present example, probabilities are
# at approximately 0.25, corresponding to odds of 1:3.
uisdLogOdds(log(1/3))
# The UISD value of 2.31 roughly matches the above empirical figure.
ess(bm, uisd=uisdLogOdds) # = 43.4 patients
## End(Not run)