[Power-commits] r35 - in pkg/sse: . man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Aug 22 11:30:51 CEST 2019
Author: thofab
Date: 2019-08-22 11:30:51 +0200 (Thu, 22 Aug 2019)
New Revision: 35
Removed:
pkg/sse/man/powCalc-class.Rd
pkg/sse/man/powPar-class.Rd
pkg/sse/man/sampleSize.Rd
Modified:
pkg/sse/ChangeLog
pkg/sse/DESCRIPTION
pkg/sse/man/SampleSize-class.Rd
pkg/sse/man/extractActualElement.Rd
pkg/sse/man/inspect.Rd
pkg/sse/man/plot.Rd
pkg/sse/man/powCalc.Rd
pkg/sse/man/powEx.Rd
pkg/sse/man/powPar.Rd
pkg/sse/man/power-class.Rd
pkg/sse/man/pp.Rd
pkg/sse/man/refine.Rd
pkg/sse/man/tex.Rd
pkg/sse/man/update.Rd
Log:
Several changes to harmonize documentation
Modified: pkg/sse/ChangeLog
===================================================================
--- pkg/sse/ChangeLog 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/ChangeLog 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,3 +1,6 @@
+version 0.7-12 2019/08/22
+ vignette: removing unused options
+ man pages: several changes to harmonize wording and improve structure
version 0.7-12 2019/08/13
splitting of tests into tests at tests/ and inst/slowTests to
reduce the time used for R CMD check
Modified: pkg/sse/DESCRIPTION
===================================================================
--- pkg/sse/DESCRIPTION 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/DESCRIPTION 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,7 +1,7 @@
Package: sse
Type: Package
Title: Sample Size Estimation
-Version: 0.7-12
+Version: 0.7-13
Author: Thomas Fabbro [aut, cre]
Maintainer: Thomas Fabbro <thomas.fabbro at unibas.ch>
URL: http://r-forge.r-project.org/projects/power/
Modified: pkg/sse/man/SampleSize-class.Rd
===================================================================
--- pkg/sse/man/SampleSize-class.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/SampleSize-class.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -4,24 +4,29 @@
\alias{SampleSize-class}
\title{Class "SampleSize"}
-\description{follow
- }
+\description{A class used internally only that contains an integer (the
+ estimated sample size).
+}
+
\section{Objects from the Class}{
-none
+ These objects are only used internally.
}
+
\section{Slots}{
\describe{
- \item{\code{estimate}:}{Object of class \code{"integer"} ~~ }
+ \item{\code{estimate}:}{Object of class \code{"integer"} }
}
}
+
\section{Methods}{
No methods defined with class "SampleSize" in the signature.
}
+
\author{\email{thomas.fabbro at unibas.ch}}
-\seealso{none
-}
+
\examples{
showClass("SampleSize")
}
+
\keyword{internal}
\keyword{classes}
Modified: pkg/sse/man/extractActualElement.Rd
===================================================================
--- pkg/sse/man/extractActualElement.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/extractActualElement.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -3,40 +3,50 @@
\alias{n}
\alias{theta}
\alias{xi}
+
\title{Extracting an actual n, theta, and xi}
+
\description{
Extracting the actual \code{n}, \code{theta}, or \code{xi} from an
- object of class \code{powPar}. This method is needed within the
- function (referred to as power-function) needed for evaluating the
- power.
+ object of class \linkS4class{powPar}. This functions are needed within
+ the 'power-function' for extracting always the actual element during
+ evaluation.
}
+
\usage{
n(x)
theta(x)
xi(x)
}
+
\arguments{
- \item{x}{An object of class \code{powPar}.}
- }
+ \item{x}{An object of class \linkS4class{powPar}.}
+}
+
\details{
During the evaluation process with \code{\link{powCalc}} every
combination of \code{n}, \code{theta}, and \code{xi} is evaluated. The
-described functions extracts the actual \code{n}, \code{theta}, or
+described functions extract the actual \code{n}, \code{theta}, or
\code{xi} during the evaluation process. The evaluation process with
\code{\link{powCalc}} changes the actual element to ensure that all
combinations are evaluated.
-When a \code{powPar}-object is created, the first element of \code{n},
-\code{theta}, or \code{xi} is also set to be the actual element. This
-allows to use this method also outside the evaluation with
-\code{\link{powCalc}} for testing the power function.
+When a objcect of class \linkS4class{powPar} is created, the first
+element of \code{n}, \code{theta}, or \code{xi} is also set to be the
+actual element. This allows to use this method also outside the
+evaluation with \code{\link{powCalc}} for testing the 'power function'.
}
-\value{An integer value for \code{n}. A numeric value for \code{theta} and \code{xi}.}
+
+\value{An integer value for \code{n}. A numeric value for \code{theta}
+and \code{xi}.}
+
\note{Do not use the method \code{pp} inside the power-function
e.g. like \code{pp(x, "n")}, because this would extract the whole
- sequence of \code{n} and not just the actual element.}
+ vector of \code{n} and not just the actual element.}
+
\seealso{\code{\link{pp}}, for extracting all other elements provided by
the user (exept \code{n}, \code{theta}, and \code{xi}.}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(n = seq(from = 20, to = 60, by = 2),
@@ -66,4 +76,5 @@
powFun(psi)
}
+
\keyword{misc}
Modified: pkg/sse/man/inspect.Rd
===================================================================
--- pkg/sse/man/inspect.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/inspect.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,14 +1,29 @@
\name{inspect}
\docType{methods}
\alias{inspect}
+
\title{Inspection Plot}
+
\description{
Creating a plot that allows to inspect the sample size calculation.
}
+
\usage{inspect(object)}
+
\arguments{
- \item{object}{An object of class \code{power}.}
+ \item{object}{An object of class \linkS4class{power}.}
}
+
+\details{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.
+}
+
+\value{A plot is generated but nothing is returned.}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.1),
@@ -33,5 +48,6 @@
## drawing an inspection plot
inspect(pow)
}
+
\keyword{methods}
Modified: pkg/sse/man/plot.Rd
===================================================================
--- pkg/sse/man/plot.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/plot.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,33 +1,38 @@
\name{plot}
\docType{methods}
\alias{plot}
+
\title{Power Plot}
+
\description{
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 \code{theta} is varied.
}
+
\usage{plot(x, y, ...)}
+
\arguments{
- \item{x}{The object of class \code{power} used for plotting}
+ \item{x}{The object of class \linkS4class{power} used for plotting}
\item{y}{Not used}
\item{...}{additional arguments implemented:
\itemize{
\item{\code{at = c(0.9, 0.8, 0.85, 0.95)} a numeric vector giving
- breakpoints along the power range.
- Contours (if any) will be drawn at these values. The contour
- line of the example will be emphasised. If \code{example = FALSE} the first
- number indicates, which contour should be emphasized.}
- \item{\code{smooth = FALSE} logical that indicates if the contours should be
- smoothed. If TRUE a span of 0.75 will be used by default. Alternatively the
- argument smooth can also take a numeric value that will be used
- for smoothing.See the documentation of the function \code{loess} for details.}
- \item{\code{example = TRUE} a logical indicating if an example should be
- drawn or not. An example is an arrow that points from the
- particular \code{theta} on the x-axis to the contour line and to
- the sample size on the y-axis.}
+ breakpoints along the power range. Contours (if any) will be
+ drawn at these values. The contour line of the example will be
+ emphasised. If \code{example = FALSE} the first number
+ indicates, which contour should be emphasized.}
+ \item{\code{smooth = FALSE} logical that indicates if the contours
+ should be smoothed. If TRUE a span of 0.75 will be used by
+ default. Alternatively the argument smooth can also take a
+ numeric value that will be used for smoothing.See the
+ documentation of the function \code{loess} for details.}
+ \item{\code{example = TRUE} a logical indicating if an example
+ should be drawn or not. An example is an arrow that points from
+ the particular \code{theta} on the x-axis to the contour line
+ and to the sample size on the y-axis.}
\item{\code{reflines = TRUE} a logical indicating if reference
- lines should be drawn or not. Reference lines are drawn at every
+ lines should be drawn or not. Reference lines are drawn at every
n and theta that was used for evaluating the power function. If
reference lines are drawn the background will be grey.}
}
@@ -36,10 +41,16 @@
\details{
Generates a contour plot with theta on the x-axis and n on the y-axis
- and the contours for the power indicated with the argument at.
+ and the contours for the estimated power (indicated with the argument
+ at).
}
+
+\value{A plot is generated but nothing is returned.}
+
\seealso{\code{\link{inspect}} for drawing an inspection plot and
- \code{\link{levelplot}} for further arguments that can be passed to plot.}
+ \code{\link{levelplot}} for further arguments that can be passed to
+ plot.}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.1),
@@ -70,5 +81,6 @@
## without example the contour line at the first element of at is bold
plot(pow, example = FALSE)
}
+
\keyword{methods}
Deleted: pkg/sse/man/powCalc-class.Rd
===================================================================
--- pkg/sse/man/powCalc-class.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/powCalc-class.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,60 +0,0 @@
-\name{powCalc-class}
-\Rdversion{1.1}
-\docType{class}
-\alias{powCalc-class}
-\alias{powFun-class}
-\alias{dim,powCalc-method}
-\alias{update,powCalc-method}
-\alias{powEx,powCalc-method}
-
-\title{Class "powCalc" }
-\description{A class for storing information of the power
- calculation. It inherits from "powPar", that contains the information
- for the calculation and from from "powEx", that contains information
- about the power-function.}
-\section{Objects from the Class}{
-Objects can be created by calling the creator \code{\link{powCalc}}.
-}
-\section{Slots}{
- \describe{
- \item{\code{core}:}{Object of class \code{"array"} with 4
- dimentions, n, theta, xi and endpoint.}
- \item{\code{core}:}{Object of class \code{"array"} with 4
- dimentions, n, theta, xi and endpoint.}
- \item{\code{statistic}:}{Object of class \code{"function"}, this
- function was used for calculating the power.}
- \item{\code{endpoint.name}:}{Object of class \code{"character"}
- names of the endpoints}
- \item{\code{iter}:}{Object of class \code{"integer"} how many
- iterations were used to estimate the power}
- }
-}
-\section{Slots inherited from powFun}{
- \describe{
- \item{\code{statistic}:}{Object of class \code{"function"}}
- \item{\code{return.power}:}{Object of class \code{"logical"}}
- \item{\code{return.list}:}{Object of class \code{"logical"}}
- \item{\code{return.n}:}{Object of class \code{"integer"}}
- \item{\code{return.names}:}{Object of class \code{"character"}}
- }
-}
-\section{Slots inherited from powPar}{
- \code{"\linkS4class{powPar}"}
-}
-\section{Extends}{
-Class \code{"\linkS4class{powFun}"}, directly.
-Class \code{"\linkS4class{powPar}"}, directly.
-}
-\usage{
-\S4method{powEx}{powCalc}(x, theta, xi = NA, endpoint = NA, power = 0.9, drop = 0,
- method = c("default", "lm", "step"), lm.range = NA,
- forceDivisor = FALSE)
-\S4method{update}{powCalc}(object, ...)
-\S4method{dim}{powCalc}(x)
-}
-\note{ none }
-\examples{
-showClass("powCalc")
-}
-\keyword{internal}
-\keyword{classes}
Modified: pkg/sse/man/powCalc.Rd
===================================================================
--- pkg/sse/man/powCalc.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/powCalc.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,15 +1,17 @@
\name{powCalc}
\docType{methods}
\alias{powCalc}
-\title{
-Power calculation
-}
+
+\title{Power calculation}
+
\description{
- The user-defined power-function provided as \code{statistic} will be
+ The user-defined 'power-function' provided as \code{statistic} will be
evaluated for the whole range of \code{n}, \code{theta}, and \code{xi}
- as specified in the \code{powPar}-object.
+ as specified in the \linkS4class{powPar}-object.
}
+
\usage{powCalc(object, statistic, n.iter = NA, cluster = FALSE)}
+
\arguments{
\item{object}{An object of class \code{powPar}.}
\item{statistic}{A function that takes an object of class
@@ -16,20 +18,24 @@
\code{powPar} as argument. Ideally this is also the only
argument. The function should return a vector of numeric values or a
vector of logicals, depending on the \code{type}. See Details.}
- \item{n.iter}{A number specifying how often the power-function is evaluated.}
- \item{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.}
+ \item{n.iter}{A number specifying how often the power-function is
+ evaluated.}
+ \item{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.}
\item{...}{Not used so far.}
}
+
\details{If the statistic does not return the power (a numeric value
between 0 and 1) but returns a logical (TRUE or FALSE) the argument
- \code{n.iter} is expected to be an integer. The statitic will then be
- evaluated n.iter-times and the proportion of successes will be
- interpreted as the power.
+ \code{n.iter} is expected. The statitic will then be evaluated
+ n.iter-times and the proportion of successes will be interpreted as
+ the power.
}
-\value{An object of class \code{powCalc}.}
+
+\value{An object of class \linkS4class{powCalc}.}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.1),
@@ -48,4 +54,5 @@
## evaluating the power-function for all combinations of n and theta
calc <- powCalc(psi, powFun)
}
+
\keyword{misc}
Modified: pkg/sse/man/powEx.Rd
===================================================================
--- pkg/sse/man/powEx.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/powEx.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,4 +1,5 @@
\name{powEx}
+\docType{methods}
\alias{powEx}
\title{
@@ -5,57 +6,68 @@
Defining the example to be used and the method to be used for sample
size estimation.
}
+
\description{
- A function for constructing an object of class \code{power} used for
- drawing an example in a sensitivity plot and for evaluating sample size.
+ A function for constructing an object of class \linkS4class{power}
+ used for drawing an example in a sensitivity plot and for estimating
+ the sample size.
}
+
\usage{powEx(x, theta, xi = NA, endpoint = NA, power = 0.9, drop = 0,
-method = c("default", "lm", "step"), lm.range = NA, forceDivisor = FALSE)
-}
+ method = c("default", "lm", "step"), lm.range = NA,
+ forceDivisor = FALSE)}
\arguments{
- \item{x}{An object of class \code{powCalc}.}
- \item{theta}{a numeric value indicating for which \code{theta} to draw the
- example in the sensitivity plot and where to evaluate sample size. It makes
- only sense to use a \code{theta} in the range evaluated.}
+ \item{x}{An object of class \linkS4class{powCalc}.}
+ \item{theta}{a numeric value indicating for which \code{theta} to draw
+ the example in the sensitivity plot and where to evaluate sample
+ size. It makes only sense to use a \code{theta} in the range
+ evaluated.}
\item{xi}{a numeric value, as \code{theta} but for \code{xi}}
\item{endpoint}{Object of class \code{character}, indidating for which
endpoint sample size should be evaluated}
\item{power}{Object of class \code{numeric}, indicating for what power
samle size should be evaluated}
- \item{method}{Defining the method how the sample size for the
- indicated theta, xi, and power is "estimated". If the power object
- was created using resampling the "default" evaluates to "lm",
- otherwise to "step".}
+ \item{method}{Defining the method how the sample size for the is
+ calculated. \code{method = "default"} uses \code{"lm"} if resampling
+ was used to calculate the \linkS4class{powCalc} object, otherwise
+ \code{"step"} is used.}
\item{lm.range}{The range of evaluations that are used for estimating
- the sample size if the \code{method} is set or evaluates to
- "lm". For the default \code{lm.range} = 0.2 this means from80 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.}
- \item{drop}{Object of class \code{numeric} (range: 0 to 1), indicating
- how many drop outs are expected in the study.
- This information is used to calculate the number of subject that
- should be recruited (addressed e.g. by the function \code{tex} using
- type \code{nRec}).}
+ the sample size if the \code{method = "lm"} or evaluates to
+ \code{"lm"}. For the default \code{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.}
+ \item{drop}{Object of class \code{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 \code{tex} using type \code{nRec}).}
\item{forceDivisor}{If \code{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.}
}
-\details{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 \code{lm.range}. This model is then used for
- predicting the sample size. Always inspect the result using \code{inspect}!
+\details{
+ For method equal to \code{"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 \code{lm.range}. This model is
+ then used for predicting the sample size. Always inspect the result
+ using \code{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.
}
-\value{An object of class \code{power}.}
-\seealso{In older verstions of the package: The function
- \code{merge} was used together with an object
- of class \code{powEx} to form an object of class \code{power}}
+
+\value{An object of class \linkS4class{power}.}
+
+\note{In older verstions of the package: The function \code{merge} was
+ used together with an object of class \linkS4class{powEx} to form an
+ object of class \linkS4class{power}.
+}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(theta = seq(from = 0.5, to = 1.5, by = 0.1),
@@ -89,4 +101,5 @@
## drawing an inspection plot
inspect(pow2)
}
+
\keyword{methods}
Deleted: pkg/sse/man/powPar-class.Rd
===================================================================
--- pkg/sse/man/powPar-class.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/powPar-class.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,51 +0,0 @@
-\name{powPar-class}
-\Rdversion{1.1}
-\docType{class}
-\alias{powPar-class}
-\alias{n,powPar-method}
-\alias{theta,powPar-method}
-\alias{xi,powPar-method}
-\alias{pp,powPar-method}
-\alias{dim,powPar-method}
-\alias{powCalc,powPar-method}
-
-\title{Class "powPar"}
-\description{A class used internally. Contains all the parameters
- needed to feed the \"power function\".
- For users there is a function
- \code{\link{powPar}} that constructs objects of this class and there are
- several functions for extracting information \code{\link{n}},
- \code{\link{theta}}, \code{\link{xi}}, \code{\link{pp}}.
-}
-\section{Slots}{
- \describe{
- \item{\code{list}:}{Object of class \code{"list"} ~~ }
- \item{\code{theta}:}{An \code{"numeric"} vector with possible values
- of a parameter that influences the power. The power will be calculated for
- every element of this vector to see how the power estimate depends
- on theta.}
- \item{\code{theta.name}:}{Object of class \code{"character"} ~~ }
- \item{\code{theta.act}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{xi}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{xi.name}:}{Object of class \code{"character"} ~~ }
- \item{\code{xi.act}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{n}:}{Object of class \code{"integer"} ~~ }
- \item{\code{n.act}:}{Object of class \code{"integer"} ~~ }
- }
-}
-\usage{
-\S4method{theta}{powPar}(x)
-\S4method{n}{powPar}(x)
-\S4method{xi}{powPar}(x)
-\S4method{pp}{powPar,character}(x, name)
-\S4method{dim}{powPar}(x)
-}
-
-\seealso{
-\code{\link{powPar}},\code{\linkS4class{power}}
-}
-\examples{
-## showClass("powPar")
-}
-\keyword{internal}
-\keyword{classes}
Modified: pkg/sse/man/powPar.Rd
===================================================================
--- pkg/sse/man/powPar.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/powPar.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,15 +1,18 @@
\name{powPar}
\alias{powPar}
-\title{
- Constructing an object of class powPar.
-}
+
+\title{Constructing an object of class 'powPar'.}
+
\description{
-A function for constructing an object of class \code{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 should be
-provided to this function by making use of the \code{...} argument.
+A function for constructing an object of class
+\linkS4class{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 \code{...} argument.
}
+
\usage{powPar(n, theta = NA, xi = NA, ...)}
+
\arguments{
\item{n}{A numeric vector, indicating for which sample sizes
to evaluate the power function.}
@@ -16,31 +19,38 @@
\item{theta}{A numeric vector that will be used for evaluating the
power function. The method \code{theta} can be used within the power
function to extract the elements of this vector one by one.}
- \item{xi}{A numeric vector that will be used for evaluating the power function.
- Since for every element of\code{xi} an individuall sensitivity plot
- has to be constructed, the length of the \code{xi} vector is usually short.}
- \item{...}{This arguemt is used to provide all parameters needed by
- the power function for calculating the power.}
+ \item{xi}{A numeric vector that will be used for evaluating the power
+ function. Since for every element of\code{xi} an individuall
+ sensitivity plot has to be constructed, the length of the \code{xi}
+ vector is usually short.}
+ \item{...}{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 \code{\link{pp}}.}
}
+
\details{
- An object of class \code{powPar} is used to evaluate the power function for a range of
- \code{n} and \code{theta} and optionally for several \code{xi} values.
+ An object of class \linkS4class{powPar} is used to evaluate the 'power
+ function' for a range of \code{n} and \code{theta} and optionally for
+ several \code{xi} values.
- The user can write a power function and extract the individual
- elements using the methods \code{n}, \code{theta}, and \code{xi}.
+ The user can write a 'power function' and extract the individual
+ elements using the functions \code{\link{n}}, \code{\link{theta}},
+ \code{\link{xi}} and \code{\link{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
+ To extract the vector of \code{theta}, instead of individual values, you can
use the method \code{pp} with the name theta.
- For historical reasons: If the argument \code{theta} is \code{NA} the argument
- \code{theta.name} (a character) has to be used, to indicate the name of a numeric
- vector that was passed to the argument (\code{...}).
- The same is true for the argument \code{xi}.
+ For historical reasons: If the argument \code{theta = NA} the
+ argument \code{theta.name} (a character) has to be used, to indicate
+ the name of a numeric vector that was passed to the argument
+ (\code{...}). The same is true for the argument \code{xi}.
}
-\value{An object of the class \code{powPar}}
+
+\value{An object of the class \linkS4class{powPar}}
+
\examples{
## defining the range of n and theta to be evaluated
psi <- powPar(n = seq(from = 20, to = 60, by = 2),
@@ -63,4 +73,5 @@
xlab = "Difference",
ylab = "Total Sample Size")
}
+
\keyword{misc}
Modified: pkg/sse/man/power-class.Rd
===================================================================
--- pkg/sse/man/power-class.Rd 2019-08-20 14:34:55 UTC (rev 34)
+++ pkg/sse/man/power-class.Rd 2019-08-22 09:30:51 UTC (rev 35)
@@ -1,94 +1,196 @@
\name{power-class}
\Rdversion{1.1}
\docType{class}
+% powPar
+\alias{powPar-class}
+\alias{dim,powPar-method}
+\alias{n,powPar-method}
+\alias{theta,powPar-method}
+\alias{xi,powPar-method}
+\alias{pp,powPar-method}
+\alias{powCalc,powPar-method}
+% powFun
+\alias{powFun-class}
+% powCalc
+\alias{powCalc-class}
+\alias{powEx,powCalc-method}
+\alias{dim,powCalc-method}
+\alias{update,powCalc-method}
+% powEx
+\alias{powEx-class}
+% power
\alias{power-class}
-\alias{powEx-class}
-\alias{show,power-method}
-\alias{update,power-method}
\alias{refine,power-method}
\alias{inspect,power-method}
-\alias{dim,power-method}
-\alias{plot,power-method}
-\alias{tex,power,character-method}
+\alias{show,power-method}
\alias{plot,ANY,ANY-method}
\alias{plot,power,missing-method}
+\alias{tex,power,character-method}
-\title{Class "power"}
-\description{follows}
-\section{Objects from the Class}{
-are ..
+\title{Class "power" and its subclasses "powPar", "powFun", "powCalc", "powEx".}
+
+\description{
+ A class used internally for storing information about the power
+ calculation. It inherits from different classes, see section "Extends" for
+ details.
}
-\section{Slots}{
+
+\usage{
+\S4method{show}{power}(object)
+\S4method{dim}{powPar}(x)
+\S4method{dim}{powCalc}(x)
+}
+
+\arguments{
+ \item{object,x}{object of class \linkS4class{power}, \linkS4class{powPar} or \linkS4class{powCalc}}
+}
+
+\section{Extends}{
+ The power-class has no privat slots but inherits everything from its
+ ancestors.
+
+ Class \linkS4class{powPar}, by class \linkS4class{powCalc}, distance 2.
+ Class \linkS4class{powFun}, by class \linkS4class{powCalc}, distance 2.
+ Class \linkS4class{powCalc}, directly.
+ Class \linkS4class{powEx}, directly.
+}
+
+\section{powPar-class}{
+ A class used internally. Contains all the parameters needed to feed
+ the 'power function'. For users there is a function
+ \code{\link{powPar}} that constructs objects of this class and there
+ are several functions for extracting information \code{\link{n}},
+ \code{\link{theta}}, \code{\link{xi}}, \code{\link{pp}}. These
+ functions should be used when writing the 'power function'.
+ Contains the Slots:
\describe{
- \item{\code{cluster}:}{Object of class \code{"list"} ~~ }
- \item{\code{core}:}{Object of class \code{"array"} ~~ }
- \item{\code{divisor}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{drop}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{endpoint.example}:}{Object of class \code{"character"} ~~ }
- \item{\code{forceDivisor}:}{Object of class \code{"logical"} ~~ }
- \item{\code{iter}:}{Object of class \code{"integer"} ~~ }
- \item{\code{list}:}{Object of class \code{"list"} ~~ }
- \item{\code{lm.range}:}{Object of class \code{"list"} ~~ }
- \item{\code{method}:}{Object of class \code{"character"} ~~ }
- \item{\code{n}:}{Object of class \code{"integer"} ~~ }
- \item{\code{n.act}:}{Object of class \code{"integer"} ~~ }
- \item{\code{power.example}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{return.list}:}{Object of class \code{"character"} ~~}
- \item{\code{return.n}:}{Object of class \code{"character"} ~~ }
- \item{\code{return.names}:}{Object of class \code{"character"} ~~ }
- \item{\code{return.power}:}{Object of class \code{"character"} ~~ }
- \item{\code{size}:}{Object of class \code{"array"} ~~ }
- \item{\code{statistic}:}{Object of class \code{"function"} ~~ }
- \item{\code{theta}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{theta.act}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{theta.example}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{theta.name}:}{Object of class \code{"character"} ~~ }
- \item{\code{xi}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{xi.name}:}{Object of class \code{"character"} ~~ }
- \item{\code{xi.act}:}{Object of class \code{"numeric"} ~~ }
- \item{\code{xi.example}:}{Object of class \code{"numeric"} ~~ }
+ \item{\code{list}:}{Object of class \code{"list"} that contains all
+ elements that were provided to \code{\link{powPar}} with the
+ \code{...} argument.}
+ \item{\code{theta}:}{An \code{"numeric"} vector with values that are
+ used to evaluate the power.}
+ \item{\code{theta.name}:}{Object of class \code{"character"} only
+ used if argument 'theta.name' of \code{\link{powPar}} was used.}
+ \item{\code{theta.act}:}{Object of class \code{"numeric"}. This slot
+ is only used during evaluation where it contains one element of
+ 'theta' after the other. The function \code{\link{theta}} extracts
+ this value. If not under evaluation this slot contains the first
+ element of 'theta'.}
+ \item{\code{xi}:}{Object of class \code{"numeric"} with values that
+ are used to evaluate the power.}
+ \item{\code{xi.name}:}{Object of class \code{"character"} only
+ used if argument 'theta.name' of \code{\link{powPar}} was used.}
+ \item{\code{xi.act}:}{Object of class \code{"numeric"}. This slot
+ is only used during evaluation where it contains one element of
+ 'xi' after the other. The function \code{\link{xi}} extracts
+ this value. If not under evaluation this slot contains the first
+ element of xi'.}
+ \item{\code{n}:}{Object of class \code{"integer"} with values that
+ are used to evaluate the power.}
+ \item{\code{n.act}:}{Object of class \code{"integer"}. This slot
+ is only used during evaluation where it contains one element of
+ 'n' after the other. The function \code{\link{n}} extracts
+ this value. If not under evaluation this slot contains the first
+ element of 'n'.}
+ }
+}
+\section{powFun-class}{
+ A class used internally. It contains the user defined 'power function'
+ and some information about what this function returns.
+
+ \code{showMethods(class = "powFun")} shows what methods are available.
+
+ Contains the Slots:
+ \describe{
+ \item{\code{statistic}:}{Object of class \code{"function"}}
+ \item{\code{return.power}:}{Object of class \code{"logical"},
+ indicating if the 'power function' returns a \code{"logical"}.}
+ \item{\code{return.list}:}{Object of class \code{"logical"},
+ indicating if the 'power function' returns a \code{"list"}.}
+ \item{\code{return.n}:}{Object of class \code{"integer"}, indicating
+ the number of elements returned by the 'power function'.}
+ \item{\code{return.names}:}{Object of class \code{"character"},
+ indicating the name of the elements returned by the 'power
+ function'.}
}
}
-\section{Slots from powEx}{
+
+\section{powCalc-class}{
+ A class used internally. Objects can be created by calls to the
+ function \code{\link{powCalc}}.
+
+ \code{showMethods(class = "powCalc")} shows what methods are available.
+
+ Contains the Slots:
\describe{
+ \item{\code{core}:}{Object of class \code{"array"} with 4
+ dimentions, n, theta, xi and endpoint.}
+ \item{\code{core}:}{Object of class \code{"array"} with 4
+ dimentions, n, theta, xi and endpoint.}
+ \item{\code{statistic}:}{Object of class \code{"function"}, this
+ function was used for calculating the power.}
+ \item{\code{endpoint.name}:}{Object of class \code{"character"}
+ names of the endpoints}
+ \item{\code{iter}:}{Object of class \code{"integer"} how many
+ iterations were used to estimate the power}
+ }
+}
+
+\section{powEx-class}{
+ A class used internally. Objects can be created by calls to the
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/power -r 35
More information about the Power-commits
mailing list