R: Sample size calculations

sampSize {DoseFinding} | R Documentation

## Sample size calculations

### Description

The sampSize function implements a bisection search algorithm for sample size calculation. The user can hand over a general target function (via targFunc) that is then iterated so that a certain target is achieved. The sampSizeMCT is a convenience wrapper of sampSize for multiple contrast tests using the power as target function.

The targN functions calculates a general target function for different given sample sizes. The powN function is a convenience wrapper of targN for multiple contrast tests using the power as target function.

### Usage

    sampSize(upperN, lowerN = floor(upperN/2), targFunc, target,
             tol = 0.001, alRatio, Ntype = c("arm", "total"),
             verbose = FALSE)

    sampSizeMCT(upperN, lowerN = floor(upperN/2), ..., power, sumFct = mean,
                tol = 0.001, alRatio, Ntype = c("arm", "total"),
                verbose = FALSE)

    targN(upperN, lowerN, step, targFunc, alRatio,
          Ntype = c("arm", "total"), sumFct = c("min", "mean", "max"))

    powN(upperN, lowerN, step, ..., alRatio,
         Ntype = c("arm", "total"), sumFct = c("min", "mean", "max"))

    ## S3 method for class 'targN'
    plot(x, superpose = TRUE, line.at = NULL,
         xlab = NULL, ylab = NULL, ...)

### Arguments

`upperN, lowerN` | Upper and lower bound for the target sample size. `lowerN` defaults to `floor(upperN/2)`.
`step` | Only needed for functions targN and powN. Stepsize for the sample size at which the target function is calculated. The steps are calculated via `seq(lowerN,upperN,by=step)`.
`targFunc, target` | The target function needs to take as an input the vector of sample sizes in the different dose groups. For sampSize it needs to return a univariate number. For function targN it should return a numerical vector. Example: targFunc could be a function that calculates the power of a test, and target the desired target power value. For function sampSize the bisection search iterates the sample size so that a specific target value is achieved (the implicit assumption is that targFunc is monotonically increasing in the sample size). Function targN simply calculates targFunc for a given set of sample sizes.
`tol` | A positive numeric value specifying the tolerance level for the bisection search algorithm. Bisection is stopped if the targFunc value is within tol of target.
`alRatio` | Vector describing the relative patient allocations to the dose groups up to proportionality, e.g. rep(1, length(doses)) corresponds to balanced allocations.
`Ntype` | One of "arm" or "total". Determines, whether the sample size in the smallest arm or the total sample size is iterated in bisection search algorithm.
`verbose` | Logical value indicating if a trace of the iteration progress of the bisection search algorithm should be displayed.
`...` | Arguments directly passed to the `powMCT` function in the sampSizeMCT and powN function. The placAdj argument needs to be FALSE (which is the default value for this argument). If sample size calculations are desired for a placebo-adjusted formulation use sampSize or targN directly. In case `S` is specified, the specified matrix needs to be proportional to the (hypothetical) covariance matrix of one single observation. The covariance matrix used for sample size calculation is 1/N*S, where N is the total sample size. Hence Ntype == "total" needs to be used if `S` is specified. When `S` is specified, automatically df = Inf is assumed in the underlying powMCT calls. For a homoscedastic normally distributed response variable only sigma needs to be specified, as the sample size n is iterated in the different powMCT calls.
`power, sumFct` | power is a numeric defining the desired summary power to achieve (in sampSizeMCT). sumFct needs to be a function that combines the power values under the different alternatives into one value (in sampSizeMCT).
`x, superpose, line.at, xlab, ylab` | arguments for the plot method of targN and powN, additional arguments are passed down to the low-level lattice plotting routines.

### Author(s)

Jose Pinheiro, Bjoern Bornkamp

### References

Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of dose finding studies combining multiple comparisons and modeling procedures, Journal of Biopharmaceutical Statistics, 16, 639–656

### See Also

`powMCT`

### Examples

    ## sampSize examples

    ## first define the target function
    ## first calculate the power to detect all of the models in the candidate set
    fmodels <- Mods(linear = NULL, emax = c(25),
                    logistic = c(50, 10.88111), exponential=c(85),
                    betaMod=matrix(c(0.33,2.31,1.39,1.39), byrow=TRUE, nrow=2),
                    doses = c(0,10,25,50,100,150), placEff=0, maxEff=0.4,
                    addArgs = list(scal=200))
    ## contrast matrix to use
    contMat <- optContr(fmodels, w=1)
    ## this function calculates the power under each model and then returns
    ## the average power under all models
    tFunc <- function(n){
      powVals <- powMCT(contMat, altModels=fmodels, n=n, sigma = 1,
                        alpha=0.05)
      mean(powVals)
    }

    ## assume we want to achieve 80% average power over the selected shapes
    ## and want to use a balanced allocations
    ## Not run:
    sSize <- sampSize(upperN = 80, targFunc = tFunc, target=0.8,
                      alRatio = rep(1,6), verbose = TRUE)
    sSize

    ## Now the same using the convenience sampSizeMCT function
    sampSizeMCT(upperN=80, contMat = contMat, sigma = 1, altModels=fmodels,
                power = 0.8, alRatio = rep(1, 6), alpha = 0.05)
    ## Alternatively one can also specify an S matrix
    ## covariance matrix in one observation (6 total observation result in a
    ## variance of 1 in each group)
    S <- 6*diag(6)
    ## this uses df = Inf, hence a slightly smaller sample size results
    sampSizeMCT(upperN=500, contMat = contMat, S=S, altModels=fmodels,
                power = 0.8, alRatio = rep(1, 6), alpha = 0.05, Ntype = "total")

    ## targN examples
    ## first calculate the power to detect all of the models in the candidate set
    fmodels <- Mods(linear = NULL, emax = c(25),
                    logistic = c(50, 10.88111), exponential=c(85),
                    betaMod=matrix(c(0.33,2.31,1.39,1.39), byrow=TRUE, nrow=2),
                    doses = c(0,10,25,50,100,150), placEff=0, maxEff=0.4,
                    addArgs = list(scal=200))
    ## corresponding contrast matrix
    contMat <- optContr(fmodels, w=1)
    ## define target function
    tFunc <- function(n){
      powMCT(contMat, altModels=fmodels, n=n, sigma = 1, alpha=0.05)
    }
    powVsN <- targN(upperN = 100, lowerN = 10, step = 10, tFunc,
                    alRatio = rep(1, 6))
    plot(powVsN)

    ## the same can be achieved using the convenience powN function
    ## without the need to specify a target function
    powN(upperN = 100, lowerN=10, step = 10, contMat = contMat,
         sigma = 1, altModels = fmodels, alpha = 0.05, alRatio = rep(1, 6))

    ## End(Not run)

[Package DoseFinding version 0.9-17 Index]