ecss: Compute Effective Current Sample Size (ECSS)
In wiesenfa/ESS: Quantification of prior informativeness in terms of prior effective and effective current sample size

Description Usage Arguments Details Value Author(s) References See Also Examples

Compute Effective Current Sample Size (ECSS) which - roughly - quantifies the number of current samples to be added or subtracted to the likelihood in order to obtain a posterior inference equivalent to that of a baseline prior model (e.g. in terms of mean squared error, MSE).

## S3 method for class 'mix'
ecss(prior,
    data, n, r, m, sigma, se, true.mean,
    n.target, 
    min.ecss, 
    prior.base, D = MSE, 
    by, grid.length = 50, min.q, 
    cores = 1, integrate = FALSE, subdivisions = 100L, ...)

## S3 method for class 'mixture.prior'
ecss(prior, ...)

## S3 method for class 'ecss'
ecss(prior, n.target, tol = 1e-06, tol2 = 0.001, ...)

`prior`	An `RBesT betaMix` or `normMix` object, a powerprior object created by `as.powerprior`, a `StudyPrior` mixture.prior object or an `ecss` object created by `ecss`
`data`	if applied to given data, individual data as in `postmix`. If the individual data is not given, then summary data has to be provided
`n`	if applied to given data, sample size
`r`	in case of binary outcome, if applied to given data, number of successes
`m`	in case of normal outcome, if applied to given data, data mean
`sigma`	in case of normal outcome, sample standard deviation
`se`	in case of normal outcome, sample standard error
`true.mean`	the true mean in case of prospective use at planning stage. If provided, the truth is assumed to equal true.mean instead of the posterior mean given the data
`n.target`	The sample size of interest at which the ECSS is evaluated. Can be a vector.
`min.ecss`	minimal ECSS of interest (usually negative)
`prior.base`	RBesT betaMix or normMix object (single mixture component) serving as baseline prior. Usually flat prior and uniform prior in case of normal and beta prior of interest, respectively.
`D`	A function that measures informativeness, e.g. `MSE` or user-specified function.
`by`	stepsize of effective sample sizes where `D` is evaluated, interpolation in between. Defaults to 5 for normal outcome and to 1 for binary outcome. In case of binary outcome, by=1 recommended.
`grid.length`	number of elements on grid for integration, with bounds determined by `min.q`
`min.q`	lower quantile of normal or binomial likelihood to specify width of grid for integration (1-min.q upper quantile), small for a wide grid. Defaults to 1e-6 for `normMix` objects and 0 for `betaMix` objects.
`cores`	number of parallel cores used in mclapply
`integrate`	use `integrate`? Not recommended
`subdivisions`	passed to `integrate` if `integrate=FALSE`
`tol`	not to be changed by user
`tol2`	only change if result is NA, and use `plot.ecss` for diagnostics then
`...`	possible arguments passed to function provided in `D`

Let π be the prior of interest specified by prior with mean θ_π, π_b a baseline prior (an objective or reference prior) specified by prior.base and f_n(y_{1:n} | θ_0) be the data distribution.

The ECSS at target sample size k (specified by n.target) is defined as the sample size m which minimizes

ECSS=argmin_{m} | D^{θ_0}_{MSE}({π}(θ|y_{1:(k-m)})) - D^{θ_0}_{MSE}(π_b(θ|y_{1:k})) |

where D^{θ_0}_{MSE} is the mean squared error measure induced by the posterior mean estimate \mbox{E}_π(θ|y_{1:k}),

D^{θ_0}_{MSE}({π}(θ|y_{1:k}))=E_{y|θ_0 } [ E_π(θ|y_{1:k})-θ_0 ]^2

or a different target measure specified by D.

The true parameter value θ_0 is either assumed to be known and specified by true.mean (useful for prospective quantification of the prior impact at planning stage) or replaced by the posterior mean under the baseline prior specification given specified data (useful for sensitivity analyses or adaptive designs).

See Wiesenfarth and Calderazzo (2019) for details.

Prints ECSS at n.target, returns an ecss object which can be updated using ecss.ecss.

Manuel Wiesenfarth

Wiesenfarth, M., Calderazzo, S. (2019). Quantification of Prior Impact in Terms of Effective Current Sample Size. Submitted.

ess, ehss

######################
# Normal Outcome
  # standard deviation
    sigma=1
  # baseline
    rob=c(0,10)
    vague <-mixnorm(vague=c(1, rob), sigma=sigma)
  # prior with nominal prior ESS=50
    inf=c(0,1/sqrt(50))
    info <-mixnorm(informative=c(1, inf), sigma=sigma)
  # robust mixture
    mix50 <-mixnorm(informative=c(.5, inf),vague=c(.5, rob), sigma=sigma)
  
  
  # before seeing data
    true.mean=.2 # hypothetic true value
    ecss(info,true.mean=true.mean,sigma=sigma,
         n.target=100,min.ecss = -100,prior.base = vague)
    ecss(as.powerprior(info),true.mean=true.mean,sigma=sigma,
         n.target=100,min.ecss = -100,prior.base = vague)
    ecss(mix50,true.mean=true.mean,sigma=sigma,
         n.target=100,min.ecss = -100,prior.base = vague)
  
  # for observed data
    m=.2 #data mean
    n=100 # sample size
    
    ecss(info,m=m,sigma=sigma,n=n,
         n.target=100,min.ecss = -100,prior.base = vague)
    ecss(as.powerprior(info),m=m,sigma=sigma,n=n,
         n.target=100,min.ecss = -100,prior.base = vague)
    ecss(mix50,m=m,sigma=sigma,n=n,
         n.target=100,min.ecss = -100,prior.base = vague)
   
       
#############
# binary outcome
  unif  <- mixbeta(               c(1.0, 1, 1))
  beta  <- mixbeta(c(1.0, 4, 16)              )
  mix50 <- mixbeta(c(0.5, 4, 16), c(0.5, 1, 1))

  # before seeing data
    true.mean=10/20
    ecss(beta,true.mean=true.mean,
           n.target=20,min.ecss = -40,prior.base = unif,by=1)
    ecss(mix50,true.mean=true.mean,
           n.target=20,min.ecss = -10,prior.base = unif,by=1)
    ecss(as.powerprior(beta,p.prior.a=1,p.prior.b=1),true.mean=true.mean,
           n.target=20,min.ecss = -10,prior.base = unif,by=1)


  # for observed data
    r=10
    n=20
    ecss(beta,r=r,n=n,
           n.target=20,min.ecss = -40,prior.base = unif,by=1)
    ecss(mix50,r=r,n=n,
           n.target=20,min.ecss = -10,prior.base = unif,by=1)
    ecss(as.powerprior(beta,p.prior.a=1,p.prior.b=1),r=r,n=n,
           n.target=20,min.ecss = -10,prior.base = unif,by=1)


## Not run: 
library(StudyPrior)
pars <- matrix(c(2.4,1,3.7,1),ncol=2)

#A mixture of 0.5 Be(2.4,3.7) + 0.5 Be(1,1) 
mymix <- create.mixture.prior(type="beta", pars = pars, weights=c(0.5,0.5))
ecss(mymix,r=r,n=n,
         n.target=20,min.ecss = -10,prior.base = unif,by=1)

## End(Not run)