R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Sample Size Calculations via Bayesian Average Errors

ssdFcts

R Documentation

Sample Size Calculations via Bayesian Average Errors

Description

A Bayesian average error based approach to sample size determination. These functions compute the required sample size for various designs common to clinical trials. A specified Total Error rate is maintain and more emphasis can be placed on controlling Average Type-I Error or Type-II Error.

Usage

  ssd.binom(alpha, w, logm, minn = 2, maxn = 1000, two.sample = FALSE,
            all = FALSE, ...)
  ssd.norm1KV(alpha, w, logm, minn = 2, maxn = 1000, all = FALSE, ...)

Arguments

alpha

Scalar. The bound to maintain on the Total Error rate. Must be a decimal between 0 and 1.

w

Scalar. The weight to be given to Average Type-I Error. Larger values of w control Type-I error rates more. Must be a decimal between 0 and 1.

logm

Function. Computes the log marginal (prior predictive density) under H0 and H1. This function should return a list that contains two components:

`logm0`	vector giving marginal density under H0.
`logm1`	vector giving marginal density under H1.

The first parameter of this function should be the observed data. See details for necessary form. The second parameter should be the sample size.

minn, maxn

Scalar. The minimum and maximum sample size to consider.

all

Boolean. If FALSE (default), the function terminates when an acceptable sample size is found or when maxn is reached. If TRUE, the function will only terminate when maxn is reached. This is useful for tracing out the Average Error as a function of sample size.

two.sample

Boolean. If FALSE (default), one sample experiment is assumed. If TRUE, two sample experiment is assumed.

...

Additional parameters to be passed to logm if necessary.

Details

Sample size calculations are dependent upon the knowledge of the marginal density under each hypothesis. The function logm should provide these densities.

For a one-sample binomial experiment, the first argument of logm should be a vector in which each entry represents a different number of successes out of n independent binary trials. For a two-sample binomial experiment, the first argument of logm should be a matrix, in which each row represents the number of successes for each of the samples out of n indpendent trials. For an example see binom1.1sided.

For a one-sample normal experiment with known variance, the first argument shoul be a vector of different sample means. For an example see norm1KV.1sided.

In addition, there are a few functions specific to a given situation (or suite); these are

ssd.norm1KV.2sided(alpha, w, sigma, theta0, prob, mu, 
      tau, minn = 2, maxn = 1000, all = FALSE)

ssd.norm2KV.2sided(alpha, w, sigma, prob, mu0, tau0,
      mu1, tau1, mu2, tau2, m = 2500, minn = 2, maxn = 1000, all = FALSE)

ssd.norm1UV.2sided(alpha, w, theta0, prob, mu, scale,
      shape, rate, m = 2500, minn = 3, maxn = 1000, all = FALSE)

The only parameter unique to these functions is

m: The number of Monte Carlo replicates to use in computing the average errors.

The logm function is not required as the function is specific to that suite. Instead, various parameters unique to that suite are required. See the corresponding suite for details.

Value

An object of class "BAEssd" which is a list containing the following elements:

`call`	The call to the function.
`history`	Dataframe. Contains one row for each sample size considered during the function evaluation. Each row records the sample size attempted, the average type-I and type-II errors, the total weighted error, and the total error.
`n`	Scalar. The chosen sample size with attributes related to the function call and total error.

Examples

############################################################
# Computing a sample size for a one-sample binomial
# experiment with a two-sided alternative.

# load suite of functions
f1 <- binom1.2sided(p0=0.5,prob=0.5,a=1,b=1)

# calculate sample size for total error bound of 0.25 and weight 0.5
attach(f1)
ss1 <- ssd.binom(alpha=0.25,w=0.5,logm=logm,two.sample=FALSE)
detach(f1)

# see results
ss1

# examine structure
str(ss1)


############################################################
# Computing a sample size for a one-sample normal
# experiment with a two-sided alternative using the
# functions internal to the suite.

# load suite of functions
f2 <- norm1KV.2sided(sigma=5,theta0=0,prob=0.5,mu=2,tau=1)

# calculate sample size for total error bound of 0.25 and weight 0.5
attach(f2)
ss2 <- ssd.norm1KV.2sided(alpha=0.25,w=0.5)
detach(f2)

# see results
ss2

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(BAEssd)
Loading required package: mvtnorm
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/BAEssd/ssdFcts.Rd_%03d_medium.png", width=480, height=480)
> ### Name: ssdFcts
> ### Title: Sample Size Calculations via Bayesian Average Errors
> ### Aliases: ssdFcts ssd ssd.binom ssd.norm1KV ssd.norm1KV.2sided
> ###   ssd.norm2KV.2sided ssd.norm1UV.2sided print.BAEssd
> 
> ### ** Examples
> 
> ############################################################
> # Computing a sample size for a one-sample binomial
> # experiment with a two-sided alternative.
> 
> # load suite of functions
> f1 <- binom1.2sided(p0=0.5,prob=0.5,a=1,b=1)

Loading the 'binom1.2sided' suite... 
  This suite contains functions pertaining to a one sample experiment 
  with a binary outcome. The hypothesis of interest has a two-sided 
  alternative.

> 
> # calculate sample size for total error bound of 0.25 and weight 0.5
> attach(f1)
> ss1 <- ssd.binom(alpha=0.25,w=0.5,logm=logm,two.sample=FALSE)
> detach(f1)
> 
> # see results
> ss1

Bayesian Average Error Sample Size Determination

Call: ssd.binom(alpha = 0.25, w = 0.5, logm = logm, two.sample = FALSE)

Sample Size:  94
Total Average Error:  0.2494501

Acceptable sample size determined!

> 
> # examine structure
> str(ss1)
List of 3
 $ call   : language ssd.binom(alpha = 0.25, w = 0.5, logm = logm, two.sample = FALSE)
 $ history:'data.frame':	93 obs. of  5 variables:
  ..$ n  : num [1:93] 2 3 4 5 6 7 8 9 10 11 ...
  ..$ AE1: num [1:93] 0.5 0.25 0.125 0.375 0.219 ...
  ..$ AE2: num [1:93] 0.333 0.5 0.6 0.333 0.429 ...
  ..$ TWE: num [1:93] 0.417 0.375 0.363 0.354 0.324 ...
  ..$ TE : num [1:93] 0.833 0.75 0.725 0.708 0.647 ...
 $ n      : atomic [1:1] 94
  ..- attr(*, "alpha")= num 0.25
  ..- attr(*, "w")= num 0.5
  ..- attr(*, "TE")= num 0.249
 - attr(*, "class")= chr "BAEssd"
> 
> 
> ############################################################
> # Computing a sample size for a one-sample normal
> # experiment with a two-sided alternative using the
> # functions internal to the suite.
> 
> # load suite of functions
> f2 <- norm1KV.2sided(sigma=5,theta0=0,prob=0.5,mu=2,tau=1)

Loading the 'norm1KV.2sided' suite... 
  This suite contains functions pertaining to one-sample experiment 
  involving a normally distributed response with known variance. The 
  hypothesis of interest has a two-sided alternative.

> 
> # calculate sample size for total error bound of 0.25 and weight 0.5
> attach(f2)
> ss2 <- ssd.norm1KV.2sided(alpha=0.25,w=0.5)
> detach(f2)
> 
> # see results
> ss2

Bayesian Average Error Sample Size Determination

Call: ssd.norm1KV.2sided(alpha = 0.25, w = 0.5)

Sample Size:  65
Total Average Error:  0.2482418

Acceptable sample size determined!

> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>