added 'SchmidliEtAl2017' example

DESCRIPTION

@@ -2,7 +2,7 @@ Package: bayesmeta
 Type: Package
 Title: Bayesian Random-Effects Meta-Analysis and Meta-Regression
 Version: 3.1
-Date: 2022-03-14
+Date: 2022-03-16
 Authors@R: c(person(given="Christian", family="Roever", role=c("aut","cre"), 
                     email="christian.roever@med.uni-goettingen.de",
                     comment=c(ORCID="0000-0002-6911-698X")),

data/SchmidliEtAl2017.R

+#
+#  H. Schmidli, B. Neuenschwander, T. Friede.
+#  Meta-analytic-predictive use of historical variance data
+#  for the design and analysis of clinical trials.
+#  Computational Statistics and Data Analysis, 113:100-110, 2017.
+#  https://doi.org/10.1016/j.csda.2016.08.007
+#
+
+# specify data (Table 2):
+SchmidliEtAl2017 <- cbind.data.frame("study" = c("CATT", "CLEAR-IT 2", "HARBOR",
+                                                 "IVAN", "VIEW 1", "VIEW 2"),
+                                     "N"     = c(599, 62, 550, 309, 909, 906),
+                                     "stdev" = c(12.11, 10.97, 10.94, 9.41, 10.97, 10.95),
+                                     "df"    = c(597, 60, 548, 307, 906, 903),
+                                     stringsAsFactors=FALSE)

man/SchmidliEtAl2017.Rd

+\name{SchmidliEtAl2017}
+\docType{data}
+\alias{SchmidliEtAl2017}
+\title{Historical variance example data}
+\description{Estimates of endpoint variances from six studies.}
+\usage{data("SchmidliEtAl2017")}
+\format{The data frame contains the following columns:
+  \tabular{lll}{
+    \bold{study} \tab \code{character} \tab study label \cr
+    \bold{N}     \tab \code{numeric}   \tab total sample size \cr
+    \bold{stdev} \tab \code{numeric}   \tab standard deviation estimate \cr
+    \bold{df}    \tab \code{numeric}   \tab associated degrees of freedom
+  }
+}
+\details{Schmidli \emph{et al.} (2017) investigated the use of
+  information on an endpoint's variance from previous (\dQuote{historical})
+  studies for the design and analysis of a new clinical trial. As an
+  example application, the problem of designing a trial in \emph{wet
+    age-related macular degeneration (AMD)} was considered. Trial
+  design, and in particular considerations regarding the required sample
+  size, hinge on the expected amount of variability in the primary
+  endpoint (here: \emph{visual acuity}).
+  
+  Historical data from six previous trials are available (Szabo \emph{et
+  al.}; 2015), each trial providing an estimate \eqn{\hat{s}_i}{s[i]} of
+  the endpoint's standard deviation along with the associated number of
+  degrees of freedom \eqn{\nu_i}{nu[i]}. The standard deviations
+  may then be modelled on the logarithmic scale, where the estimates and
+  their associated standard errors are given by 
+  \deqn{y_i=\log(\hat{s}_i) \quad \mbox{and} \quad 
+  \sigma_i=\sqrt{\frac{1}{2\,\nu_i}}}{y[i] = log(s[i])  and  sigma[i] =
+  sqrt(1/(2*nu[i]))}
+  
+  The \emph{unit information standard deviation} for a logarithmic
+  standard deviation then is at approximately
+  \eqn{\frac{1}{\sqrt{2}}}{2^-0.5}. 
+}
+\source{
+  H. Schmidli, B. Neuenschwander, T. Friede.
+  Meta-analytic-predictive use of historical variance data
+  for the design and analysis of clinical trials.
+  \emph{Computational Statistics and Data Analysis}, \bold{113}:100-110, 2017.
+  \doi{10.1016/j.csda.2016.08.007}.
+}
+\seealso{
+  \code{\link{uisd}}, \code{\link{ess}}.
+}
+\references{
+  S.M. Szabo, M. Hedegaard, K. Chan, K. Thorlund, R. Christensen,
+  H. Vorum, J.P. Jansen.
+  Ranibizumab vs. aflibercept for wet age-related macular degeneration:
+  network meta-analysis to understand the value of reduced frequency dosing.
+  \emph{Current Medical Research and Opinion}, \bold{31}(11):2031-2042, 2015.
+  \doi{10.1185/03007995.2015.1084909}.
+}
+\examples{
+# load data:
+data("SchmidliEtAl2017")
+
+# show data:
+SchmidliEtAl2017
+
+\dontrun{
+# derive log-SDs and their standard errors:
+dat <- cbind(SchmidliEtAl2017,
+             logstdev    = log(SchmidliEtAl2017$stdev),
+             logstdev.se = sqrt(0.5/SchmidliEtAl2017$df))
+dat
+
+# alternatively, use "metafor::escalc()" function:
+es <- escalc(measure="SDLN",
+             yi=log(stdev), vi=0.5/df, ni=N,
+             slab=study, data=SchmidliEtAl2017)
+es
+
+# perform meta-analysis of log-stdevs:
+bm <- bayesmeta(y=dat$logstdev,
+                sigma=dat$logstdev.se,
+                label=dat$study,
+                tau.prior=function(t){dhalfnormal(t, scale=sqrt(2)/4)})
+
+# or, alternatively:
+bm <- bayesmeta(es,
+                tau.prior=function(t){dhalfnormal(t, scale=sqrt(2)/4)})
+
+# draw forest plot (see Fig.1):
+forestplot(bm, zero=NA,
+           xlab="log standard deviation")
+
+# show heterogeneity posterior:
+plot(bm, which=4, prior=TRUE)
+
+# posterior of log-stdevs, heterogeneity,
+# and predictive distribution:
+bm$summary
+
+# prediction (standard deviations):
+exp(bm$summary[c(2,5,6),"theta"])
+
+# prediction (variances):
+exp(2 * bm$summary[c(2,5,6),"theta"])
+
+# sample size formula (12) (per arm):
+alpha <- 0.025
+beta  <- 0.20
+delta <- 8
+10.9^2 * 2*(qnorm(alpha) + qnorm(beta))^2 / delta^2
+
+# check UISD:
+uisd(es, indiv=TRUE)
+uisd(es)
+1 / sqrt(2)
+
+# compute predictive distribution's ESS:
+ess(bm, uisd=1/sqrt(2))
+# actual total sample size:
+sum(dat$N)
+
+# illustrate predictive distribution
+# on standard-deviation-scale (Fig.2):
+x <- seq(from=5, to=20, length=200)
+plot(x, (1/x) * bm$dposterior(theta=log(x), predict=TRUE), type="l",
+     xlab=expression("predicted standard deviation "*sigma[k+1]),
+     ylab="predictive density")
+abline(h=0, col="grey")
+}
+}
+\keyword{datasets}

man/bayesmeta-package.Rd

@@ -17,7 +17,7 @@
     Package: \tab bayesmeta\cr
     Type:    \tab Package\cr
     Version: \tab 3.1\cr
-    Date:    \tab 2022-03-14\cr
+    Date:    \tab 2022-03-16\cr
     License: \tab GPL (>=2)
   }
   The main functionality is provided by the \code{\link{bayesmeta}()}