Title: | Sample Size Estimation |
---|---|
Description: | Provides functions to evaluate user-defined power functions for a parameter range, and draws a sensitivity plot. It also provides a resampling procedure for semi-parametric sample size estimation and methods for adding information to a Sweave report. |
Authors: | Thomas Fabbro [aut, cre] |
Maintainer: | Thomas Fabbro <[email protected]> |
License: | GPL-3 |
Version: | 0.7-15 |
Built: | 2024-10-25 04:32:09 UTC |
Source: | https://github.com/thofab/sse |
Extracting the actual n
, theta
, or xi
from an
object of class powPar. This functions are needed within
the 'power-function' for extracting always the actual element during
evaluation.
n(x) theta(x) xi(x)
n(x) theta(x) xi(x)
x |
An object of class powPar. |
During the evaluation process with powCalc
every
combination of n
, theta
, and xi
is evaluated. The
described functions extract the actual n
, theta
, or
xi
during the evaluation process. The evaluation process with
powCalc
changes the actual element to ensure that all
combinations are evaluated.
When a objcect of class powPar is created, the first
element of n
, theta
, or xi
is also set to be the
actual element. This allows to use this method also outside the
evaluation with powCalc
for testing the 'power function'.
An integer value for n
. A numeric value for theta
and xi
.
Do not use the method pp
inside the power-function
e.g. like pp(x, "n")
, because this would extract the whole
vector of n
and not just the actual element.
pp
, for extracting all other elements provided by
the user (exept n
, theta
, and xi
.
## defining the range of n and theta to be evaluated psi <- powPar(n = seq(from = 20, to = 60, by = 2), theta = seq(from = 0.5, to = 1.5, by = 0.1), muA = 0, muB = 1) ## extracting all elements of psi individually, starting with the first n(psi) theta(psi) xi(psi) ## extracting all elements, not just the actual: pp(psi, name = "n") pp(psi, name = "theta") pp(psi, name = "xi") ## an example of usage powFun <- function(psi){ power.t.test(n = n(psi), delta = pp(psi, "muA") - pp(psi, "muB"), sd = theta(psi) )$power } ## testing the power-function powFun(psi)
## defining the range of n and theta to be evaluated psi <- powPar(n = seq(from = 20, to = 60, by = 2), theta = seq(from = 0.5, to = 1.5, by = 0.1), muA = 0, muB = 1) ## extracting all elements of psi individually, starting with the first n(psi) theta(psi) xi(psi) ## extracting all elements, not just the actual: pp(psi, name = "n") pp(psi, name = "theta") pp(psi, name = "xi") ## an example of usage powFun <- function(psi){ power.t.test(n = n(psi), delta = pp(psi, "muA") - pp(psi, "muB"), sd = theta(psi) )$power } ## testing the power-function powFun(psi)
All information needed for the 'power-function' should be provided by
an object of class powPar
. To extract this information the
function pp
should be used.
pp(x, name)
pp(x, name)
x |
An object of class powPar. |
name |
A character indicating the name of the object to be extracted. |
Everything that can be stored within a list is possible.
The name pp
is an abbreviation for power parameter.
For extracting individual elements of n
, theta
and xi
the functions n
, theta
, or
xi
should be used.
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.5), n = seq(from = 10, to = 30, by = 10), muA = 0, muB = 1) pp(psi, name = "muA") ## an example of usage powFun <- function(psi){ power.t.test(n = n(psi), delta = pp(psi, "muA") - pp(psi, "muB"), sd = theta(psi) )$power } ## testing the power-function powFun(psi)
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.5), n = seq(from = 10, to = 30, by = 10), muA = 0, muB = 1) pp(psi, name = "muA") ## an example of usage powFun <- function(psi){ power.t.test(n = n(psi), delta = pp(psi, "muA") - pp(psi, "muB"), sd = theta(psi) )$power } ## testing the power-function powFun(psi)
Creating a plot that allows to inspect the sample size calculation.
inspect(object)
inspect(object)
object |
An object of class power. |
The plot shows for every evaluated theta the sample size and the power on a transformed scale. The method used for sample size estimation 'step' or 'lm' is indicated. If the method 'lm' is used a red regression line is shown for the range that was used for estimation.
A plot is generated but nothing is returned.
## 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 an inspection plot inspect(pow)
## 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 an inspection plot inspect(pow)
A sensitivity plot (called power plot) for the sample size
calculation. Using a contour for a given power, it shows how sample
size changes if theta
is varied.
plot(x, y, ...)
plot(x, y, ...)
x |
The object of class power used for plotting |
y |
Not used |
... |
additional arguments implemented:
|
Generates a contour plot with theta on the x-axis and n on the y-axis and the contours for the estimated power (indicated with the argument at).
A plot is generated but nothing is returned.
inspect
for drawing an inspection plot and
levelplot
for further arguments that can be passed to
plot.
## 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)) ## without example the contour line at the first element of at is bold plot(pow, example = FALSE)
## 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)) ## without example the contour line at the first element of at is bold plot(pow, example = FALSE)
The user-defined 'power-function' provided as statistic
will be
evaluated for the whole range of n
, theta
, and xi
as specified in the powPar-object.
powCalc(object, statistic, n.iter = NA, cluster = FALSE)
powCalc(object, statistic, n.iter = NA, cluster = FALSE)
object |
An object of class |
statistic |
A function that takes an object of class
|
n.iter |
A number specifying how often the power-function is evaluated. |
cluster |
Still experimental! This argument can be logical, indicating if the library parallel should be used or not, or numeric. In the latter case the number is passed as integer to the function makeCluster from library parallel. The default is FALSE. |
... |
Not used so far. |
If the statistic does not return the power (a numeric value
between 0 and 1) but returns a logical (TRUE or FALSE) the argument
n.iter
is expected. The statitic will then be evaluated
n.iter-times and the proportion of successes will be interpreted as
the power.
An object of class powCalc.
## 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)
## 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)
A function for constructing an object of class power used for drawing an example in a sensitivity plot and for estimating the sample size.
powEx(x, theta, xi = NA, endpoint = NA, power = 0.9, drop = 0, method = c("default", "lm", "step"), lm.range = NA, forceDivisor = FALSE)
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 |
xi |
a numeric value, as |
endpoint |
Object of class |
power |
Object of class |
method |
Defining the method how the sample size for the is
calculated. |
lm.range |
The range of evaluations that are used for estimating
the sample size if the |
drop |
Object of class |
forceDivisor |
If |
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)
## 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)
A function for constructing an object of class
powPar. Such an object is used for evaluating the user
defined 'power function' for a parameter range. All information that is
needed for calculating the power (e.g. a pilot data set) should be
provided by making use of the ...
argument.
powPar(n, theta = NA, xi = NA, ...)
powPar(n, theta = NA, xi = NA, ...)
n |
A numeric vector, indicating for which sample sizes to evaluate the power function. |
theta |
A numeric vector that will be used for evaluating the
power function. The method |
xi |
A numeric vector that will be used for evaluating the power
function. Since for every element of |
... |
This arguemt is used to provide additional parameters
needed by the power function for calculating the power. This
parameters can be extracted using the function |
An object of class powPar is used to evaluate the 'power
function' for a range of n
and theta
and optionally for
several xi
values.
The user can write a 'power function' and extract the individual
elements using the functions n
, theta
,
xi
and pp
.
It is a good practice to include everything that is needed for the calculation, also data sets etc.
To extract the vector of theta
, instead of individual values, you can
use the method pp
with the name theta.
For historical reasons: If the argument theta = NA
the
argument theta.name
(a character) has to be used, to indicate
the name of a numeric vector that was passed to the argument
(...
). The same is true for the argument xi
.
An object of the class powPar
## defining the range of n and theta to be evaluated psi <- powPar(n = seq(from = 20, to = 60, by = 2), theta = seq(from = 0.5, to = 1.5, by = 0.05) ) ## defining a power-function powFun <- function(psi){ return(power.t.test(n = n(psi)/2, delta = theta(psi), sig.level = 0.05)$power) } ## evaluating the power-function for all combinations of n and theta calc <- powCalc(psi, statistic = powFun) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc, theta = 1) ## drawing the power plot plot(pow, xlab = "Difference", ylab = "Total Sample Size")
## defining the range of n and theta to be evaluated psi <- powPar(n = seq(from = 20, to = 60, by = 2), theta = seq(from = 0.5, to = 1.5, by = 0.05) ) ## defining a power-function powFun <- function(psi){ return(power.t.test(n = n(psi)/2, delta = theta(psi), sig.level = 0.05)$power) } ## evaluating the power-function for all combinations of n and theta calc <- powCalc(psi, statistic = powFun) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc, theta = 1) ## drawing the power plot plot(pow, xlab = "Difference", ylab = "Total Sample Size")
Increasing the number of iterations for estimating the sample size for the 'theta' and 'xi' as specified for the example.
refine(object, factor = 10)
refine(object, factor = 10)
object |
An object of class power. |
factor |
An integer larger than one that is multiplied with the available number of iterations to from the target number of iterations. |
An object of class power.
This function is only useful if the object of class power was generated using a resamling approach.
## takes quite some time ## 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)) ## defining a power-function powFun <- function(psi){ x <- rnorm(n(psi)/2) y <- rnorm(n(psi)/2) + theta(psi) return(wilcox.test(x = x, y = y)$p.value < 0.05) } ## evaluating the power-function for all combinations of n and theta calc <- powCalc(psi, powFun, n.iter = 10) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc, theta = 1, power = 0.9) ## another 900 (= 1000 - 100) iterations refine(pow)
## takes quite some time ## 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)) ## defining a power-function powFun <- function(psi){ x <- rnorm(n(psi)/2) y <- rnorm(n(psi)/2) + theta(psi) return(wilcox.test(x = x, y = y)$p.value < 0.05) } ## evaluating the power-function for all combinations of n and theta calc <- powCalc(psi, powFun, n.iter = 10) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc, theta = 1, power = 0.9) ## another 900 (= 1000 - 100) iterations refine(pow)
Methods for function tex
tex(x, type, ...)
tex(x, type, ...)
x |
The object of class power used for extraction |
type |
Currently available:
|
... |
Not used so far |
A character string.
This methods prepare strings that can directly be used for including information from objects of power into Sweave reports.
## 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)) ## tex(pow, type = "sampling")
## 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)) ## tex(pow, type = "sampling")
A function for updating an existing object of class powCalc or power.
update(object, ...)
update(object, ...)
object |
|
... |
The following elements (slots) of the object can be updated:
|
An object of class powCalc.
Be careful if you use this function to update objects of class power.
powCalc
for geneating new objcets of class
powCalc.
## 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) ## updating by using additional elements for "n" calc2 <- update(calc, n = seq(from = 20, to = 90, by = 2)) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc2, 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))
## 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) ## updating by using additional elements for "n" calc2 <- update(calc, n = seq(from = 20, to = 90, by = 2)) ## adding example at theta of 1 and power of 0.9 pow <- powEx(calc2, 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))