powEx: Defining the example to be used and the method to be used for...
In sse: Sample Size Estimation

Description Usage Arguments Details Value Note Examples

A function for constructing an object of class power used for drawing an example in a sensitivity plot and for estimating the sample size.

1
2
3

powEx(x, theta, xi = NA, endpoint = NA, power = 0.9, drop = 0,
             method = c("default", "lm", "step"), lm.range = NA,
             forceDivisor = FALSE)

`x`	An object of class powCalc.
`theta`	a numeric value indicating for which `theta` to draw the example in the sensitivity plot and where to evaluate sample size. It makes only sense to use a `theta` in the range evaluated.
`xi`	a numeric value, as `theta` but for `xi`
`endpoint`	Object of class `character`, indidating for which endpoint sample size should be evaluated
`power`	Object of class `numeric`, indicating for what power samle size should be evaluated
`method`	Defining the method how the sample size for the is calculated. `method = "default"` uses `"lm"` if resampling was used to calculate the powCalc object, otherwise `"step"` is used.
`lm.range`	The range of evaluations that are used for estimating the sample size if the `method = "lm"` or evaluates to `"lm"`. For the default `lm.range` = 0.2 this means from 80 to 120 % of the power in the example, e.g. for the power of 0.9 this is a range from 0.72 to 1.08. Note that the range is cut at 0 and 1.
`drop`	Object of class `numeric` (range: 0 to 1), indicating how many drop outs are expected. This information is used to calculate the number of subject that should be recruited (addressed e.g. by the function `tex` using type `nRec`).
`forceDivisor`	If `TRUE` the biggest common divisor of all evaluated sample sizes is used as divisor and the estimated sample size is increased to be divisible by this divisor. If an integer is provided it is used as divisor.

For method equal to "lm" a linear model is fit as lm(sample.size ~ transformed(power)) with all data where theta, and xi are equal to the theta and xi of the example and within the power-range as defined by the argument lm.range. This model is then used for predicting the sample size. Always inspect the result using inspect!

The method "step" returns the last element in the sequence of sample sizes - power pairs, sorted with decreasing power, where the power is above the power defined for the example.

An object of class power.

In older verstions of the package: The function merge was used together with an object of class powEx to form an object of class power.

## defining the range of n and theta to be evaluated
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.1),
              n = seq(from = 20, to = 60, by = 2),
              muA = 0,
              muB = 1)

## defining a power-function     
powFun <- function(psi){
  power.t.test(n = n(psi)/2,
               delta = pp(psi, "muA") - pp(psi, "muB"),
               sd = theta(psi)
               )$power
}

## evaluating the power-function for all combinations of n and theta
calc <- powCalc(psi, powFun)

## adding example at theta of 1 and power of 0.9
pow <- powEx(calc, theta = 1, power = 0.9)

## drawing the power plot with 3 contour lines
plot(pow,
     xlab = "Standard Deviation",
     ylab = "Total Sample Size",
     at = c(0.85, 0.9, 0.95))

## changing the estimation method
pow2 <- powEx(calc, theta = 1, power = 0.9, method = "lm")

## drawing an inspection plot
inspect(pow2)