Package 'rpact'

Description

Calculates the Multivariate Normal Distribution with Product Correlation Structure published by Charles Dunnett, Algorithm AS 251.1 Appl.Statist. (1989), Vol.38, No.3, doi:10.2307/2347754.

Usage

as251Normal(
  lower,
  upper,
  sigma,
  ...,
  eps = 1e-06,
  errorControl = c("strict", "halvingIntervals"),
  intervalSimpsonsRule = 0
)

Arguments

Details

For a multivariate normal vector with correlation structure defined by rho(i,j) = bpd(i) * bpd(j), computes the probability that the vector falls in a rectangle in n-space with error less than eps.

This function calculates the bdp value from sigma, determines the right inf value and calls mvnprd.

Description

Calculates the Multivariate Normal Distribution with Product Correlation Structure published by Charles Dunnett, Algorithm AS 251.1 Appl.Statist. (1989), Vol.38, No.3, doi:10.2307/2347754.

Usage

as251StudentT(
  lower,
  upper,
  sigma,
  ...,
  df,
  eps = 1e-06,
  errorControl = c("strict", "halvingIntervals"),
  intervalSimpsonsRule = 0
)

Arguments

Details

For a multivariate normal vector with correlation structure defined by rho(i,j) = bpd(i) * bpd(j), computes the probability that the vector falls in a rectangle in n-space with error less than eps.

This function calculates the bdp value from sigma, determines the right inf value and calls mvstud.

Description

Returns an AccrualTime object that contains the accrual time and the accrual intensity.

Usage

getAccrualTime(
  accrualTime = NA_real_,
  ...,
  accrualIntensity = NA_real_,
  accrualIntensityType = c("auto", "absolute", "relative"),
  maxNumberOfSubjects = NA_real_
)

Arguments

Value

Returns an AccrualTime object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

Staggered patient entry

accrualTime is the time period of subjects' accrual in a study. It can be a value that defines the end of accrual or a vector. In this case, accrualTime can be used to define a non-constant accrual over time. For this, accrualTime is a vector that defines the accrual intervals. The first element of accrualTime must be equal to 0 and, additionally, accrualIntensity needs to be specified. accrualIntensity itself is a value or a vector (depending on the length of accrualTime) that defines the intensity how subjects enter the trial in the intervals defined through accrualTime.

accrualTime can also be a list that combines the definition of the accrual time and accrual intensity (see below and examples for details).

If the length of accrualTime and the length of accrualIntensity are the same (i.e., the end of accrual is undefined), maxNumberOfSubjects > 0 needs to be specified and the end of accrual is calculated. In that case, accrualIntensity is the number of subjects per time unit, i.e., the absolute accrual intensity.

If the length of accrualTime equals the length of accrualIntensity - 1 (i.e., the end of accrual is defined), maxNumberOfSubjects is calculated if the absolute accrual intensity is given. If all elements in accrualIntensity are smaller than 1, accrualIntensity defines the relative intensity how subjects enter the trial. For example, accrualIntensity = c(0.1, 0.2) specifies that in the second accrual interval the intensity is doubled as compared to the first accrual interval. The actual (absolute) accrual intensity is calculated for the calculated or given maxNumberOfSubjects. Note that the default is accrualIntensity = 0.1 meaning that the absolute accrual intensity will be calculated.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

getNumberOfSubjects() for calculating the number of subjects at given time points.

Examples

## Not run: 
# Assume that in a trial the accrual after the first 6 months is doubled
# and the total accrual time is 30 months.
# Further assume that a total of 1000 subjects are entered in the trial.
# The number of subjects to be accrued in the first 6 months and afterwards
# is achieved through
getAccrualTime(
    accrualTime = c(0, 6, 30),
    accrualIntensity = c(0.1, 0.2), maxNumberOfSubjects = 1000
)

# The same result is obtained via the list based definition
getAccrualTime(
    list(
        "0 - <6"   = 0.1,
        "6 - <=30" = 0.2
    ),
    maxNumberOfSubjects = 1000
)

# Calculate the end of accrual at given absolute intensity:
getAccrualTime(
    accrualTime = c(0, 6),
    accrualIntensity = c(18, 36), maxNumberOfSubjects = 1000
)

# Via the list based definition this is
getAccrualTime(
    list(
        "0 - <6" = 18,
        ">=6" = 36
    ),
    maxNumberOfSubjects = 1000
)

# You can use an accrual time object in getSampleSizeSurvival() or
# getPowerSurvival().
# For example, if the maximum number of subjects and the follow up
# time needs to be calculated for a given effect size:
accrualTime <- getAccrualTime(
    accrualTime = c(0, 6, 30),
    accrualIntensity = c(0.1, 0.2)
)
getSampleSizeSurvival(accrualTime = accrualTime, pi1 = 0.4, pi2 = 0.2)

# Or if the power and follow up time needs to be calculated for given
# number of events and subjects:
accrualTime <- getAccrualTime(
    accrualTime = c(0, 6, 30),
    accrualIntensity = c(0.1, 0.2), maxNumberOfSubjects = 110
)
getPowerSurvival(
    accrualTime = accrualTime, pi1 = 0.4, pi2 = 0.2,
    maxNumberOfEvents = 46
)

# How to show accrual time details

# You can use a sample size or power object as argument for the function
# getAccrualTime():
sampleSize <- getSampleSizeSurvival(
    accrualTime = c(0, 6), accrualIntensity = c(22, 53),
    lambda2 = 0.05, hazardRatio = 0.8, followUpTime = 6
)
sampleSize
accrualTime <- getAccrualTime(sampleSize)
accrualTime

## End(Not run)

Description

Calculates and returns the analysis results for the specified design and data.

Usage

getAnalysisResults(
  design,
  dataInput,
  ...,
  directionUpper = NA,
  thetaH0 = NA_real_,
  nPlanned = NA_real_,
  allocationRatioPlanned = 1,
  stage = NA_integer_,
  maxInformation = NULL,
  informationEpsilon = NULL
)

Arguments

Details

Given a design and a dataset, at given stage the function calculates the test results (effect sizes, stage-wise test statistics and p-values, overall p-values and test statistics, conditional rejection probability (CRP), conditional power, Repeated Confidence Intervals (RCIs), repeated overall p-values, and final stage p-values, median unbiased effect estimates, and final confidence intervals.

For designs with more than two treatments arms (multi-arm designs) or enrichment designs a closed combination test is performed. That is, additionally the statistics to be used in a closed testing procedure are provided.

The conditional power is calculated if the planned sample size for the subsequent stages (nPlanned) is specified. The conditional power is calculated either under the assumption of the observed effect or under the assumption of an assumed effect, that has to be specified (see above).
For testing rates in a two-armed trial, pi1 and pi2 typically refer to the rates in the treatment and the control group, respectively. This is not mandatory, however, and so pi1 and pi2 can be interchanged. In many-to-one multi-armed trials, piTreatments and piControl refer to the rates in the treatment arms and the one control arm, and so they cannot be interchanged. piTreatments and piControls in enrichment designs can principally be interchanged, but we use the plural form to indicate that the rates can be differently specified for the sub-populations.

Median unbiased effect estimates and confidence intervals are calculated if a group sequential design or an inverse normal combination test design was chosen, i.e., it is not applicable for Fisher's p-value combination test design. For the inverse normal combination test design with more than two stages, a warning informs that the validity of the confidence interval is theoretically shown only if no sample size change was performed.

A final stage p-value for Fisher's combination test is calculated only if a two-stage design was chosen. For Fisher's combination test, the conditional power for more than one remaining stages is estimated via simulation.

Final stage p-values, median unbiased effect estimates, and final confidence intervals are not calculated for multi-arm and enrichment designs.

Value

Returns an AnalysisResults object. The following generics (R generic functions) are available for this result object:

• names to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

getObservedInformationRates()

Other analysis functions: getClosedCombinationTestResults(), getClosedConditionalDunnettTestResults(), getConditionalPower(), getConditionalRejectionProbabilities(), getFinalConfidenceInterval(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
# Example 1 One-Sample t Test
# Perform an analysis within a three-stage group sequential design with
# O'Brien & Fleming boundaries and one-sample data with a continuous outcome
# where H0: mu = 1.2 is to be tested
dsnGS <- getDesignGroupSequential()
dataMeans <- getDataset(
    n = c(30, 30),
    means = c(1.96, 1.76),
    stDevs = c(1.92, 2.01)
)
getAnalysisResults(design = dsnGS, dataInput = dataMeans, thetaH0 = 1.2)

# You can obtain the results when performing an inverse normal combination test
# with these data by using the commands
dsnIN <- getDesignInverseNormal()
getAnalysisResults(design = dsnIN, dataInput = dataMeans, thetaH0 = 1.2)

# Example 2 Use Function Approach with Time to Event Data
# Perform an analysis within a use function approach according to an
# O'Brien & Fleming type use function and survival data where
# where H0: hazard ratio = 1 is to be tested. The events were observed
# over time and maxInformation = 120, informationEpsilon = 5 specifies
# that 116 > 120 - 5 observed events defines the final analysis.
design <- getDesignGroupSequential(typeOfDesign = "asOF")
dataSurvival <- getDataset(
    cumulativeEvents = c(33, 72, 116),
    cumulativeLogRanks = c(1.33, 1.88, 1.902)
)
getAnalysisResults(design,
    dataInput = dataSurvival,
    maxInformation = 120, informationEpsilon = 5
)

# Example 3 Multi-Arm Design
# In a four-stage combination test design with O'Brien & Fleming boundaries
# at the first stage the second treatment arm was dropped. With the Bonferroni
# intersection test, the results together with the CRP, conditional power
# (assuming a total of 40 subjects for each comparison and effect sizes 0.5
# and 0.8 for treatment arm 1 and 3, respectively, and standard deviation 1.2),
# RCIs and p-values of a closed adaptive test procedure are
# obtained as follows with the given data (treatment arm 4 refers to the
# reference group; displayed with summary and plot commands):
data <- getDataset(
    n1 = c(22, 23),
    n2 = c(21, NA),
    n3 = c(20, 25),
    n4 = c(25, 27),
    means1 = c(1.63, 1.51),
    means2 = c(1.4, NA),
    means3 = c(0.91, 0.95),
    means4 = c(0.83, 0.75),
    stds1 = c(1.2, 1.4),
    stds2 = c(1.3, NA),
    stds3 = c(1.1, 1.14),
    stds4 = c(1.02, 1.18)
)
design <- getDesignInverseNormal(kMax = 4)
x <- getAnalysisResults(design,
    dataInput = data, intersectionTest = "Bonferroni",
    nPlanned = c(40, 40), thetaH1 = c(0.5, NA, 0.8), assumedStDevs = 1.2
)
summary(x)
if (require(ggplot2)) plot(x, thetaRange = c(0, 0.8))
design <- getDesignConditionalDunnett(secondStageConditioning = FALSE)
y <- getAnalysisResults(design,
    dataInput = data,
    nPlanned = 40, thetaH1 = c(0.5, NA, 0.8), assumedStDevs = 1.2, stage = 1
)
summary(y)
if (require(ggplot2)) plot(y, thetaRange = c(0, 0.4))

# Example 4 Enrichment Design
# Perform an two-stage enrichment design analysis with O'Brien & Fleming boundaries
# where one sub-population (S1) and a full population (F) are considered as primary
# analysis sets. At interim, S1 is selected for further analysis and the sample
# size is increased accordingly. With the Spiessens & Debois intersection test,
# the results of a closed adaptive test procedure together with the CRP, repeated
# RCIs and p-values are obtained as follows with the given data (displayed with
# summary and plot commands):
design <- getDesignInverseNormal(kMax = 2, typeOfDesign = "OF")
dataS1 <- getDataset(
    means1 = c(13.2, 12.8),
    means2 = c(11.1, 10.8),
    stDev1 = c(3.4, 3.3),
    stDev2 = c(2.9, 3.5),
    n1 = c(21, 42),
    n2 = c(19, 39)
)
dataNotS1 <- getDataset(
    means1 = c(11.8, NA),
    means2 = c(10.5, NA),
    stDev1 = c(3.6, NA),
    stDev2 = c(2.7, NA),
    n1 = c(15, NA),
    n2 = c(13, NA)
)
dataBoth <- getDataset(S1 = dataS1, R = dataNotS1)
x <- getAnalysisResults(design,
    dataInput = dataBoth,
    intersectionTest = "SpiessensDebois",
    varianceOption = "pooledFromFull",
    stratifiedAnalysis = TRUE
)
summary(x)
if (require(ggplot2)) plot(x, type = 2)

## End(Not run)

Description

Calculates and returns the results from the closed combination test in multi-arm and population enrichment designs.

Usage

getClosedCombinationTestResults(stageResults)

Arguments

Value

Returns a ClosedCombinationTestResults object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other analysis functions: getAnalysisResults(), getClosedConditionalDunnettTestResults(), getConditionalPower(), getConditionalRejectionProbabilities(), getFinalConfidenceInterval(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
# In a four-stage combination test design with O'Brien & Fleming boundaries
# at the first stage the second treatment arm was dropped. With the Bonferroni
# intersection test, the results of a closed adaptive test procedure are
# obtained as follows with the given data (treatment arm 4 refers to the
# reference group):
data <- getDataset(
    n1 = c(22, 23),
    n2 = c(21, NA),
    n3 = c(20, 25),
    n4 = c(25, 27),
    means1 = c(1.63, 1.51),
    means2 = c(1.4, NA),
    means3 = c(0.91, 0.95),
    means4 = c(0.83, 0.75),
    stds1 = c(1.2, 1.4),
    stds2 = c(1.3, NA),
    stds3 = c(1.1, 1.14),
    stds4 = c(1.02, 1.18)
)

design <- getDesignInverseNormal(kMax = 4)
stageResults <- getStageResults(design,
    dataInput = data,
    intersectionTest = "Bonferroni"
)
getClosedCombinationTestResults(stageResults)

## End(Not run)

Description

Calculates and returns the results from the closed conditional Dunnett test.

Usage

getClosedConditionalDunnettTestResults(
  stageResults,
  ...,
  stage = stageResults$stage
)

Arguments

Details

For performing the conditional Dunnett test the design must be defined through the function getDesignConditionalDunnett().
See Koenig et al. (2008) and Wassmer & Brannath (2016), chapter 11 for details of the test procedure.

Value

Returns a ClosedCombinationTestResults object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other analysis functions: getAnalysisResults(), getClosedCombinationTestResults(), getConditionalPower(), getConditionalRejectionProbabilities(), getFinalConfidenceInterval(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
# In a two-stage design a conditional Dunnett test should be performed
# where the  unconditional second stage p-values should be used for the
# test decision.
# At the first stage the second treatment arm was dropped. The results of
# a closed conditionsal Dunnett test are obtained as follows with the given
# data (treatment arm 4 refers to the reference group):
data <- getDataset(
    n1 = c(22, 23),
    n2 = c(21, NA),
    n3 = c(20, 25),
    n4 = c(25, 27),
    means1 = c(1.63, 1.51),
    means2 = c(1.4, NA),
    means3 = c(0.91, 0.95),
    means4 = c(0.83, 0.75),
    stds1 = c(1.2, 1.4),
    stds2 = c(1.3, NA),
    stds3 = c(1.1, 1.14),
    stds4 = c(1.02, 1.18)
)

# For getting the results of the closed test procedure, use the following commands:
design <- getDesignConditionalDunnett(secondStageConditioning = FALSE)
stageResults <- getStageResults(design, dataInput = data)
getClosedConditionalDunnettTestResults(stageResults)

## End(Not run)

Description

Calculates and returns the conditional power.

Usage

getConditionalPower(stageResults, ..., nPlanned, allocationRatioPlanned = 1)

Arguments

Details

The conditional power is calculated if the planned sample size for the subsequent stages is specified.
For testing rates in a two-armed trial, pi1 and pi2 typically refer to the rates in the treatment and the control group, respectively. This is not mandatory, however, and so pi1 and pi2 can be interchanged. In many-to-one multi-armed trials, piTreatments and piControl refer to the rates in the treatment arms and the one control arm, and so they cannot be interchanged. piTreatments and piControls in enrichment designs can principally be interchanged, but we use the plural form to indicate that the rates can be differently specified for the sub-populations.

For Fisher's combination test, the conditional power for more than one remaining stages is estimated via simulation.

Value

Returns a ConditionalPowerResults object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

plot.StageResults() or plot.AnalysisResults() for plotting the conditional power.

Other analysis functions: getAnalysisResults(), getClosedCombinationTestResults(), getClosedConditionalDunnettTestResults(), getConditionalRejectionProbabilities(), getFinalConfidenceInterval(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
data <- getDataset(
    n1     = c(22, 13, 22, 13),
    n2     = c(22, 11, 22, 11),
    means1 = c(1, 1.1, 1, 1),
    means2 = c(1.4, 1.5, 1, 2.5),
    stds1  = c(1, 2, 2, 1.3),
    stds2  = c(1, 2, 2, 1.3)
)
stageResults <- getStageResults(
    getDesignGroupSequential(kMax = 4),
    dataInput = data, stage = 2, directionUpper = FALSE
)
getConditionalPower(stageResults, thetaH1 = -0.4,
    nPlanned = c(64, 64), assumedStDev = 1.5, 
    allocationRatioPlanned = 3
)

## End(Not run)

Description

Calculates the conditional rejection probabilities (CRP) for given test results.

Usage

getConditionalRejectionProbabilities(stageResults, ...)

Arguments

Details

The conditional rejection probability is the probability, under H0, to reject H0 in one of the subsequent (remaining) stages. The probability is calculated using the specified design. For testing rates and the survival design, the normal approximation is used, i.e., it is calculated with the use of the prototype case testing a mean for normally distributed data with known variance.

The conditional rejection probabilities are provided up to the specified stage.

For Fisher's combination test, you can check the validity of the CRP calculation via simulation.

Value

Returns a numeric vector of length kMax or in case of multi-arm stage results a matrix (each column represents a stage, each row a comparison) containing the conditional rejection probabilities.

See Also

Other analysis functions: getAnalysisResults(), getClosedCombinationTestResults(), getClosedConditionalDunnettTestResults(), getConditionalPower(), getFinalConfidenceInterval(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
# Calculate CRP for a Fisher's combination test design with
# two remaining stages and check the results by simulation.
design <- getDesignFisher(
    kMax = 4, alpha = 0.01,
    informationRates = c(0.1, 0.3, 0.8, 1)
)
data <- getDataset(n = c(40, 40), events = c(20, 22))
sr <- getStageResults(design, data, thetaH0 = 0.4)
getConditionalRejectionProbabilities(sr)
getConditionalRejectionProbabilities(sr,
    simulateCRP = TRUE,
    seed = 12345, iterations = 10000
)

## End(Not run)

Description

Returns the aggregated simulation data.

Usage

getData(x)

getData.SimulationResults(x)

Arguments

Details

This function can be used to get the aggregated simulated data from an simulation results object, for example, obtained by getSimulationSurvival(). In this case, the data frame contains the following columns:

1. iterationNumber: The number of the simulation iteration.

2. stageNumber: The stage.

3. pi1: The assumed or derived event rate in the treatment group.

4. pi2: The assumed or derived event rate in the control group.

5. hazardRatio: The hazard ratio under consideration (if available).

6. analysisTime: The analysis time.

7. numberOfSubjects: The number of subjects under consideration when the (interim) analysis takes place.

8. eventsPerStage1: The observed number of events per stage in treatment group 1.

9. eventsPerStage2: The observed number of events per stage in treatment group 2.

10. eventsPerStage: The observed number of events per stage in both treatment groups.

11. rejectPerStage: 1 if null hypothesis can be rejected, 0 otherwise.

12. eventsNotAchieved: 1 if number of events could not be reached with observed number of subjects, 0 otherwise.

13. futilityPerStage: 1 if study should be stopped for futility, 0 otherwise.

14. testStatistic: The test statistic that is used for the test decision, depends on which design was chosen (group sequential, inverse normal, or Fisher combination test)'

15. logRankStatistic: Z-score statistic which corresponds to a one-sided log-rank test at considered stage.

16. conditionalPowerAchieved: The conditional power for the subsequent stage of the trial for selected sample size and effect. The effect is either estimated from the data or can be user defined with thetaH1 or pi1H1 and pi2H1.

17. trialStop: TRUE if study should be stopped for efficacy or futility or final stage, FALSE otherwise.

18. hazardRatioEstimateLR: The estimated hazard ratio, derived from the log-rank statistic.

A subset of variables is provided for getSimulationMeans(), getSimulationRates(), getSimulationMultiArmMeans(),
getSimulationMultiArmRates(), or getSimulationMultiArmSurvival().

Value

Returns a data.frame.

Examples

## Not run: 
results <- getSimulationSurvival(
    pi1 = seq(0.3, 0.6, 0.1), pi2 = 0.3, eventTime = 12,
    accrualTime = 24, plannedEvents = 40, maxNumberOfSubjects = 200,
    maxNumberOfIterations = 50
)
data <- getData(results)
head(data)
dim(data)

## End(Not run)

Description

Creates a dataset object and returns it.

Usage

getDataset(..., floatingPointNumbersEnabled = FALSE)

getDataSet(..., floatingPointNumbersEnabled = FALSE)

Arguments

Details

The different dataset types DatasetMeans, of DatasetRates, or DatasetSurvival can be created as follows:

• An element of DatasetMeans for one sample is created by
  getDataset(sampleSizes =, means =, stDevs =) where
  sampleSizes, means, stDevs are vectors with stage-wise sample sizes, means and standard deviations of length given by the number of available stages.

• An element of DatasetMeans for two samples is created by
  getDataset(sampleSizes1 =, sampleSizes2 =, means1 =, means2 =,
stDevs1 =, stDevs2 =) where sampleSizes1, sampleSizes2, means1, means2, stDevs1, stDevs2 are vectors with stage-wise sample sizes, means and standard deviations for the two treatment groups of length given by the number of available stages.

• An element of DatasetRates for one sample is created by
  getDataset(sampleSizes =, events =) where sampleSizes, events are vectors with stage-wise sample sizes and events of length given by the number of available stages.

• An element of DatasetRates for two samples is created by
  getDataset(sampleSizes1 =, sampleSizes2 =, events1 =, events2 =) where sampleSizes1, sampleSizes2, events1, events2 are vectors with stage-wise sample sizes and events for the two treatment groups of length given by the number of available stages.

• An element of DatasetSurvival is created by
  getDataset(events =, logRanks =, allocationRatios =) where events, logRanks, and allocation ratios are the stage-wise events, (one-sided) logrank statistics, and allocation ratios.

• An element of DatasetMeans, DatasetRates, and DatasetSurvival for more than one comparison is created by adding subsequent digits to the variable names. The system can analyze these data in a multi-arm many-to-one comparison setting where the group with the highest index represents the control group.

Prefix overall[Capital case of first letter of variable name]... for the variable names enables entering the overall (cumulative) results and calculates stage-wise statistics. Since rpact version 3.2, the prefix cumulative[Capital case of first letter of variable name]... or cum[Capital case of first letter of variable name]... can alternatively be used for this.

n can be used in place of samplesizes.

Note that in survival design usually the overall (cumulative) events and logrank test statistics are provided in the output, so
getDataset(cumulativeEvents=, cumulativeLogRanks =, cumulativeAllocationRatios =)
is the usual command for entering survival data. Note also that for cumulativeLogranks also the z scores from a Cox regression can be used.

For multi-arm designs, the index refers to the considered comparison. For example,
getDataset(events1=c(13, 33), logRanks1 = c(1.23, 1.55), events2 = c(16, NA), logRanks2 = c(1.55, NA))
refers to the case where one active arm (1) is considered at both stages whereas active arm 2 was dropped at interim. Number of events and logrank statistics are entered for the corresponding comparison to control (see Examples).

For enrichment designs, the comparison of two samples is provided for an unstratified (sub-population wise) or stratified data input.
For non-stratified (sub-population wise) data input the data sets are defined for the sub-populations S1, S2, ..., F, where F refers to the full populations. Use of getDataset(S1 = , S2, ..., F = ) defines the data set to be used in getAnalysisResults() (see examples)
For stratified data input the data sets are defined for the strata S1, S12, S2, ..., R, where R refers to the remainder of the strata such that the union of all sets is the full population. Use of getDataset(S1 = , S12 = , S2, ..., R = ) defines the data set to be used in getAnalysisResults() (see examples)
For survival data, for enrichment designs the log-rank statistics can only be entered as stratified log-rank statistics in order to provide strong control of Type I error rate. For stratified data input, the variables to be specified in getDataset() are cumEvents, cumExpectedEvents, cumVarianceEvents, and cumAllocationRatios or overallEvents, overallExpectedEvents, overallVarianceEvents, and overallAllocationRatios. From this, (stratified) log-rank tests and and the independent increments are calculated.

Value

Returns a Dataset object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

Examples

## Not run: 
# Create a Dataset of Means (one group):
datasetOfMeans <- getDataset(
    n      = c(22, 11, 22, 11),
    means  = c(1, 1.1, 1, 1),
    stDevs = c(1, 2, 2, 1.3)
)
datasetOfMeans
datasetOfMeans$show(showType = 2)

datasetOfMeans2 <- getDataset(
    cumulativeSampleSizes = c(22, 33, 55, 66),
    cumulativeMeans = c(1.000, 1.033, 1.020, 1.017),
    cumulativeStDevs = c(1.00, 1.38, 1.64, 1.58)
)
datasetOfMeans2
datasetOfMeans2$show(showType = 2)
as.data.frame(datasetOfMeans2)

# Create a Dataset of Means (two groups):
datasetOfMeans3 <- getDataset(
    n1 = c(22, 11, 22, 11),
    n2 = c(22, 13, 22, 13),
    means1  = c(1, 1.1, 1, 1),
    means2  = c(1.4, 1.5, 3, 2.5),
    stDevs1 = c(1, 2, 2, 1.3),
    stDevs2 = c(1, 2, 2, 1.3)
)
datasetOfMeans3

datasetOfMeans4 <- getDataset(
    cumulativeSampleSizes1 = c(22, 33, 55, 66),
    cumulativeSampleSizes2 = c(22, 35, 57, 70),
    cumulativeMeans1  = c(1, 1.033, 1.020, 1.017),
    cumulativeMeans2  = c(1.4, 1.437, 2.040, 2.126),
    cumulativeStDevs1 = c(1, 1.38, 1.64, 1.58),
    cumulativeStDevs2 = c(1, 1.43, 1.82, 1.74)
)
datasetOfMeans4

df <- data.frame(
    stages = 1:4,
    n1      = c(22, 11, 22, 11),
    n2      = c(22, 13, 22, 13),
    means1  = c(1, 1.1, 1, 1),
    means2  = c(1.4, 1.5, 3, 2.5),
    stDevs1 = c(1, 2, 2, 1.3),
    stDevs2 = c(1, 2, 2, 1.3)
)
datasetOfMeans5 <- getDataset(df)
datasetOfMeans5

# Create a Dataset of Means (three groups) where the comparison of 
# treatment arm 1 to control is dropped at the second interim stage:
datasetOfMeans6 <- getDataset(
   cumN1      = c(22, 33, NA),
   cumN2      = c(20, 34, 56),
   cumN3      = c(22, 31, 52),
   cumMeans1  = c(1.64, 1.54, NA),
   cumMeans2  = c(1.7, 1.5, 1.77),
   cumMeans3  = c(2.5, 2.06, 2.99),
   cumStDevs1 = c(1.5, 1.9, NA),
   cumStDevs2 = c(1.3, 1.3, 1.1),
   cumStDevs3 = c(1, 1.3, 1.8))
datasetOfMeans6

# Create a Dataset of Rates (one group):
datasetOfRates <- getDataset(
    n = c(8, 10, 9, 11), 
    events = c(4, 5, 5, 6)
)
datasetOfRates

# Create a Dataset of Rates (two groups):
datasetOfRates2 <- getDataset(
    n2      = c(8, 10, 9, 11),
    n1      = c(11, 13, 12, 13),
    events2 = c(3, 5, 5, 6),
    events1 = c(10, 10, 12, 12)
)
datasetOfRates2

# Create a Dataset of Rates (three groups) where the comparison of 
# treatment arm 2 to control is dropped at the first interim stage:
datasetOfRates3 <- getDataset(
    cumN1      = c(22, 33, 44),
    cumN2      = c(20, NA, NA),
    cumN3      = c(20, 34, 44),
    cumEvents1 = c(11, 14, 22),
    cumEvents2 = c(17, NA, NA),
    cumEvents3 = c(17, 19, 33))
datasetOfRates3

# Create a Survival Dataset
datasetSurvival <- getDataset(
    cumEvents = c(8, 15, 19, 31),
    cumAllocationRatios = c(1, 1, 1, 2),
    cumLogRanks = c(1.52, 1.98, 1.99, 2.11)
)
datasetSurvival
 
# Create a Survival Dataset with four comparisons where treatment
# arm 2 was dropped at the first interim stage, and treatment arm 4
# at the second.
datasetSurvival2 <- getDataset(
    cumEvents1   = c(18, 45, 56),
    cumEvents2   = c(22, NA, NA),
    cumEvents3   = c(12, 41, 56),
    cumEvents4   = c(27, 56, NA),
    cumLogRanks1 = c(1.52, 1.98, 1.99),
    cumLogRanks2 = c(3.43, NA, NA),
    cumLogRanks3 = c(1.45, 1.67, 1.87),
    cumLogRanks4 = c(1.12, 1.33, NA)
)
datasetSurvival2

# Enrichment: Stratified and unstratified data input
# The following data are from one study. Only the first 
# (stratified) data input enables a stratified analysis. 

# Stratified data input
S1 <- getDataset(
    sampleSize1 = c(18, 17), 
    sampleSize2 = c(12, 33), 
    mean1       = c(125.6, 111.1), 
    mean2       = c(107.7, 77.7), 
    stDev1      = c(120.1, 145.6),
    stDev2      = c(128.5, 133.3)) 
S2 <- getDataset(
    sampleSize1 = c(11, NA), 
    sampleSize2 = c(14, NA), 
    mean1       = c(100.1, NA), 
    mean2      = c( 68.3, NA), 
    stDev1      = c(116.8, NA),
    stDev2      = c(124.0, NA)) 
S12 <- getDataset(           
    sampleSize1 = c(21, 17), 
    sampleSize2 = c(21, 12), 
    mean1       = c(135.9, 117.7), 
    mean2       = c(84.9, 107.7), 
    stDev1      = c(185.0, 92.3),
    stDev2      = c(139.5, 107.7)) 
R <- getDataset(
    sampleSize1 = c(19, NA), 
    sampleSize2 = c(33, NA), 
    mean1       = c(142.4, NA), 
    mean2       = c(77.1, NA), 
    stDev1      = c(120.6, NA),
    stDev2      = c(163.5, NA)) 
dataEnrichment <- getDataset(S1 = S1, S2 = S2, S12 = S12, R = R)
dataEnrichment

# Unstratified data input
S1N <- getDataset(
    sampleSize1 = c(39, 34), 
    sampleSize2 = c(33, 45), 
    stDev1      = c(156.503, 120.084), 
    stDev2      = c(134.025, 126.502), 
    mean1       = c(131.146, 114.4), 
    mean2       = c(93.191, 85.7))
S2N <- getDataset(
    sampleSize1 = c(32, NA), 
    sampleSize2 = c(35, NA), 
    stDev1      = c(163.645, NA), 
    stDev2      = c(131.888, NA),
    mean1       = c(123.594, NA), 
    mean2       = c(78.26, NA))
F <- getDataset(
    sampleSize1 = c(69, NA), 
    sampleSize2 = c(80, NA), 
    stDev1      = c(165.468, NA), 
    stDev2      = c(143.979, NA), 
    mean1       = c(129.296, NA), 
    mean2       = c(82.187, NA))
dataEnrichmentN <- getDataset(S1 = S1N, S2 = S2N, F = F)
dataEnrichmentN

## End(Not run)

Description

Calculates the characteristics of a design and returns it.

Usage

getDesignCharacteristics(design = NULL, ...)

Arguments

Details

Calculates the inflation factor (IF), the expected reduction in sample size under H1, under H0, and under a value in between H0 and H1. Furthermore, absolute information values are calculated under the prototype case testing H0: mu = 0 against H1: mu = 1.

Value

Returns a TrialDesignCharacteristics object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other design functions: getDesignConditionalDunnett(), getDesignFisher(), getDesignGroupSequential(), getDesignInverseNormal(), getGroupSequentialProbabilities(), getPowerAndAverageSampleNumber()

Examples

## Not run: 
# Calculate design characteristics for a three-stage O'Brien & Fleming 
# design at power 90% and compare it with Pocock's design.  
getDesignCharacteristics(getDesignGroupSequential(beta = 0.1))
getDesignCharacteristics(getDesignGroupSequential(beta = 0.1, typeOfDesign = "P")) 

## End(Not run)

Description

Defines the design to perform an analysis with the conditional Dunnett test.

Usage

getDesignConditionalDunnett(
  alpha = 0.025,
  informationAtInterim = 0.5,
  ...,
  secondStageConditioning = TRUE,
  directionUpper = NA
)

Arguments

Details

For performing the conditional Dunnett test the design must be defined through this function. You can define the information fraction and the way of how to compute the second stage p-values only in the design definition, and not in the analysis call.
See getClosedConditionalDunnettTestResults() for an example and Koenig et al. (2008) and Wassmer & Brannath (2016), chapter 11 for details of the test procedure.

Value

Returns a TrialDesign object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other design functions: getDesignCharacteristics(), getDesignFisher(), getDesignGroupSequential(), getDesignInverseNormal(), getGroupSequentialProbabilities(), getPowerAndAverageSampleNumber()

Description

Performs Fisher's combination test and returns critical values for this design.

Usage

getDesignFisher(
  ...,
  kMax = NA_integer_,
  alpha = NA_real_,
  method = c("equalAlpha", "fullAlpha", "noInteraction", "userDefinedAlpha"),
  userAlphaSpending = NA_real_,
  alpha0Vec = NA_real_,
  informationRates = NA_real_,
  sided = 1,
  bindingFutility = NA,
  directionUpper = NA,
  tolerance = 1e-14,
  iterations = 0,
  seed = NA_real_
)

Arguments

Details

getDesignFisher() calculates the critical values and stage levels for Fisher's combination test as described in Bauer (1989), Bauer and Koehne (1994), Bauer and Roehmel (1995), and Wassmer (1999) for equally and unequally sized stages.

Value

Returns a TrialDesign object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

getDesignSet() for creating a set of designs to compare.

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignGroupSequential(), getDesignInverseNormal(), getGroupSequentialProbabilities(), getPowerAndAverageSampleNumber()

Examples

## Not run: 
# Calculate critical values for a two-stage Fisher's combination test 
# with full level alpha = 0.05 at the final stage and stopping for 
# futility bound alpha0 = 0.50, as described in Bauer and Koehne (1994). 
getDesignFisher(kMax = 2, method = "fullAlpha", alpha = 0.05, alpha0Vec = 0.50) 

## End(Not run)

Description

Provides adjusted boundaries and defines a group sequential design.

Usage

getDesignGroupSequential(
  ...,
  kMax = NA_integer_,
  alpha = NA_real_,
  beta = NA_real_,
  sided = 1L,
  informationRates = NA_real_,
  futilityBounds = NA_real_,
  typeOfDesign = c("OF", "P", "WT", "PT", "HP", "WToptimum", "asP", "asOF", "asKD",
    "asHSD", "asUser", "noEarlyEfficacy"),
  deltaWT = NA_real_,
  deltaPT1 = NA_real_,
  deltaPT0 = NA_real_,
  optimizationCriterion = c("ASNH1", "ASNIFH1", "ASNsum"),
  gammaA = NA_real_,
  typeBetaSpending = c("none", "bsP", "bsOF", "bsKD", "bsHSD", "bsUser"),
  userAlphaSpending = NA_real_,
  userBetaSpending = NA_real_,
  gammaB = NA_real_,
  bindingFutility = NA,
  directionUpper = NA,
  betaAdjustment = NA,
  constantBoundsHP = 3,
  twoSidedPower = NA,
  delayedInformation = NA_real_,
  tolerance = 1e-08
)

Arguments

Details

Depending on typeOfDesign some parameters are specified, others not. For example, only if typeOfDesign "asHSD" is selected, gammaA needs to be specified.

If an alpha spending approach was specified ("asOF", "asP", "asKD", "asHSD", or "asUser") additionally a beta spending function can be specified to produce futility bounds.

For optimum designs, "ASNH1" minimizes the expected sample size under H1, "ASNIFH1" minimizes the sum of the maximum sample and the expected sample size under H1, and "ASNsum" minimizes the sum of the maximum sample size, the expected sample size under a value midway H0 and H1, and the expected sample size under H1.

Value

Returns a TrialDesign object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

getDesignSet() for creating a set of designs to compare different designs.

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFisher(), getDesignInverseNormal(), getGroupSequentialProbabilities(), getPowerAndAverageSampleNumber()

Examples

## Not run: 
# Calculate two-sided critical values for a four-stage 
# Wang & Tsiatis design with Delta = 0.25 at level alpha = 0.05
getDesignGroupSequential(kMax = 4, alpha = 0.05, sided = 2, 
    typeOfDesign = "WT", deltaWT = 0.25) 

# Calculate one-sided critical values and binding futility bounds for a three-stage 
# design with alpha- and beta-spending functions according to Kim & DeMets with gamma = 2.5
# (planned informationRates as specified, default alpha = 0.025 and beta = 0.2)
getDesignGroupSequential(kMax = 3, informationRates = c(0.3, 0.75, 1), 
    typeOfDesign = "asKD", gammaA = 2.5, typeBetaSpending = "bsKD", 
    gammaB = 2.5, bindingFutility = TRUE)

# Calculate the Pocock type alpha spending critical values if the first 
# interim analysis was performed after 40% of the maximum information was observed
# and the second after 70% of the maximum information was observed (default alpha = 0.025)
getDesignGroupSequential(informationRates = c(0.4, 0.7), typeOfDesign = "asP") 

## End(Not run)

Description

Provides adjusted boundaries and defines a group sequential design for its use in the inverse normal combination test.

Usage

getDesignInverseNormal(
  ...,
  kMax = NA_integer_,
  alpha = NA_real_,
  beta = NA_real_,
  sided = 1L,
  informationRates = NA_real_,
  futilityBounds = NA_real_,
  typeOfDesign = c("OF", "P", "WT", "PT", "HP", "WToptimum", "asP", "asOF", "asKD",
    "asHSD", "asUser", "noEarlyEfficacy"),
  deltaWT = NA_real_,
  deltaPT1 = NA_real_,
  deltaPT0 = NA_real_,
  optimizationCriterion = c("ASNH1", "ASNIFH1", "ASNsum"),
  gammaA = NA_real_,
  typeBetaSpending = c("none", "bsP", "bsOF", "bsKD", "bsHSD", "bsUser"),
  userAlphaSpending = NA_real_,
  userBetaSpending = NA_real_,
  gammaB = NA_real_,
  bindingFutility = NA,
  directionUpper = NA,
  betaAdjustment = NA,
  constantBoundsHP = 3,
  twoSidedPower = NA,
  tolerance = 1e-08
)

Arguments

Details

Depending on typeOfDesign some parameters are specified, others not. For example, only if typeOfDesign "asHSD" is selected, gammaA needs to be specified.

If an alpha spending approach was specified ("asOF", "asP", "asKD", "asHSD", or "asUser") additionally a beta spending function can be specified to produce futility bounds.

For optimum designs, "ASNH1" minimizes the expected sample size under H1, "ASNIFH1" minimizes the sum of the maximum sample and the expected sample size under H1, and "ASNsum" minimizes the sum of the maximum sample size, the expected sample size under a value midway H0 and H1, and the expected sample size under H1.

Value

Returns a TrialDesign object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

getDesignSet() for creating a set of designs to compare different designs.

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFisher(), getDesignGroupSequential(), getGroupSequentialProbabilities(), getPowerAndAverageSampleNumber()

Examples

## Not run: 
# Calculate two-sided critical values for a four-stage 
# Wang & Tsiatis design with Delta = 0.25 at level alpha = 0.05
getDesignInverseNormal(kMax = 4, alpha = 0.05, sided = 2, 
    typeOfDesign = "WT", deltaWT = 0.25) 

# Defines a two-stage design at one-sided alpha = 0.025 with provision of early stopping  
# if the one-sided p-value exceeds 0.5 at interim and no early stopping for efficacy. 
# The futility bound is non-binding.
getDesignInverseNormal(kMax = 2, typeOfDesign = "noEarlyEfficacy", futilityBounds = 0)  

# Calculate one-sided critical values and binding futility bounds for a three-stage 
# design with alpha- and beta-spending functions according to Kim & DeMets with gamma = 2.5
# (planned informationRates as specified, default alpha = 0.025 and beta = 0.2)
getDesignInverseNormal(kMax = 3, informationRates = c(0.3, 0.75, 1), 
    typeOfDesign = "asKD", gammaA = 2.5, typeBetaSpending = "bsKD", 
    gammaB = 2.5, bindingFutility = TRUE)

## End(Not run)

Description

Creates a trial design set object and returns it.

Usage

getDesignSet(...)

Arguments

Details

Specify a master design and one or more design parameters or a list of designs.

Value

Returns a TrialDesignSet object. The following generics (R generic functions) are available for this result object:

• names to obtain the field names,

• length to obtain the number of design,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

Examples

## Not run: 
# Example 1
design <- getDesignGroupSequential(
    alpha = 0.05, kMax = 6,
    sided = 2, typeOfDesign = "WT", deltaWT = 0.1
)
designSet <- getDesignSet()
designSet$add(design = design, deltaWT = c(0.3, 0.4))
if (require(ggplot2)) plot(designSet, type = 1)

# Example 2 (shorter script)
design <- getDesignGroupSequential(
    alpha = 0.05, kMax = 6,
    sided = 2, typeOfDesign = "WT", deltaWT = 0.1
)
designSet <- getDesignSet(design = design, deltaWT = c(0.3, 0.4))
if (require(ggplot2)) plot(designSet, type = 1)

# Example 3 (use of designs instead of design)
d1 <- getDesignGroupSequential(
    alpha = 0.05, kMax = 2,
    sided = 1, beta = 0.2, typeOfDesign = "asHSD",
    gammaA = 0.5, typeBetaSpending = "bsHSD", gammaB = 0.5
)
d2 <- getDesignGroupSequential(
    alpha = 0.05, kMax = 4,
    sided = 1, beta = 0.2, typeOfDesign = "asP",
    typeBetaSpending = "bsP"
)
designSet <- getDesignSet(
    designs = c(d1, d2),
    variedParameters = c("typeOfDesign", "kMax")
)
if (require(ggplot2)) plot(designSet, type = 8, nMax = 20)

## End(Not run)

Description

Returns the event probabilities for specified parameters at given time vector.

Usage

getEventProbabilities(
  time,
  ...,
  accrualTime = c(0, 12),
  accrualIntensity = 0.1,
  accrualIntensityType = c("auto", "absolute", "relative"),
  kappa = 1,
  piecewiseSurvivalTime = NA_real_,
  lambda2 = NA_real_,
  lambda1 = NA_real_,
  allocationRatioPlanned = 1,
  hazardRatio = NA_real_,
  dropoutRate1 = 0,
  dropoutRate2 = 0,
  dropoutTime = 12,
  maxNumberOfSubjects = NA_real_
)

Arguments

Details

The function computes the overall event probabilities in a two treatment groups design. For details of the parameters see getSampleSizeSurvival().

Value

Returns a EventProbabilities object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

Examples

## Not run: 
# Calculate event probabilities for staggered subjects' entry, piecewisely defined
# survival time and hazards, and plot it.
timeVector <- seq(0, 100, 1)
y <- getEventProbabilities(timeVector, accrualTime = c(0, 20, 60), 
    accrualIntensity = c(5, 20), 
    piecewiseSurvivalTime = c(0, 20, 80),
    lambda2 = c(0.02, 0.06, 0.1), 
    hazardRatio = 2
)
plot(timeVector, y$cumulativeEventProbabilities, type = 'l')

## End(Not run)

Description

Returns the final confidence interval for the parameter of interest. It is based on the prototype case, i.e., the test for testing a mean for normally distributed variables.

Usage

getFinalConfidenceInterval(
  design,
  dataInput,
  ...,
  directionUpper = NA,
  thetaH0 = NA_real_,
  tolerance = 1e-06,
  stage = NA_integer_
)

Arguments

Details

Depending on design and dataInput the final confidence interval and median unbiased estimate that is based on the stage-wise ordering of the sample space will be calculated and returned. Additionally, a non-standardized ("general") version is provided, the estimated standard deviation must be used to obtain the confidence interval for the parameter of interest.

For the inverse normal combination test design with more than two stages, a warning informs that the validity of the confidence interval is theoretically shown only if no sample size change was performed.

Value

Returns a list containing

• finalStage,

• medianUnbiased,

• finalConfidenceInterval,

• medianUnbiasedGeneral, and

• finalConfidenceIntervalGeneral.

See Also

Other analysis functions: getAnalysisResults(), getClosedCombinationTestResults(), getClosedConditionalDunnettTestResults(), getConditionalPower(), getConditionalRejectionProbabilities(), getFinalPValue(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
design <- getDesignInverseNormal(kMax = 2)
data <- getDataset(
    n = c(20, 30),
    means = c(50, 51),
    stDevs = c(130, 140)
)
getFinalConfidenceInterval(design, dataInput = data)

## End(Not run)

Description

Returns the final p-value for given stage results.

Usage

getFinalPValue(stageResults, ...)

Arguments

Details

The calculation of the final p-value is based on the stage-wise ordering of the sample space. This enables the calculation for both the non-adaptive and the adaptive case. For Fisher's combination test, it is available for kMax = 2 only.

Value

Returns a list containing

• finalStage,

• pFinal.

See Also

Other analysis functions: getAnalysisResults(), getClosedCombinationTestResults(), getClosedConditionalDunnettTestResults(), getConditionalPower(), getConditionalRejectionProbabilities(), getFinalConfidenceInterval(), getRepeatedConfidenceIntervals(), getRepeatedPValues(), getStageResults(), getTestActions()

Examples

## Not run: 
design <- getDesignInverseNormal(kMax = 2)
data <- getDataset(
    n      = c( 20,  30),
    means  = c( 50,  51),
    stDevs = c(130, 140)
)
getFinalPValue(getStageResults(design, dataInput = data))

## End(Not run)

Description

Calculates probabilities in the group sequential setting.

Usage

getGroupSequentialProbabilities(decisionMatrix, informationRates)

Arguments

Details

Given a sequence of information rates (fixing the correlation structure), and decisionMatrix with either 2 or 4 rows and kMax = length(informationRates) columns, this function calculates a probability matrix containing, for two rows, the probabilities:
P(Z_1 < l_1), P(l_1 < Z_1 < u_1, Z_2 < l_2),..., P(l_kMax-1 < Z_kMax-1 < u_kMax-1, Z_kMax < l_l_kMax)
P(Z_1 < u_1), P(l_1 < Z_1 < u_1, Z_2 < u_2),..., P(l_kMax-1 < Z_kMax-1 < u_kMax-1, Z_kMax < u_l_kMax)
P(Z_1 < Inf), P(l_1 < Z_1 < u_1, Z_2 < Inf),..., P(l_kMax-1 < Z_kMax-1 < u_kMax-1, Z_kMax < Inf)
with continuation matrix
l_1,...,l_kMax
u_1,...,u_kMax
That is, the output matrix of the function provides per stage (column) the cumulative probabilities for values specified in decisionMatrix and Inf, and reaching the stage, i.e., the test statistics is in the continuation region for the preceding stages. For 4 rows, the continuation region contains of two regions and the probability matrix is obtained analogously (cf., Wassmer and Brannath, 2016).

Value

Returns a numeric matrix containing the probabilities described in the details section.

See Also

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFisher(), getDesignGroupSequential(), getDesignInverseNormal(), getPowerAndAverageSampleNumber()

Examples

## Not run: 
# Calculate Type I error rates in the two-sided group sequential setting when
# performing kMax stages with constant critical boundaries at level alpha:
alpha <- 0.05
kMax <- 10
decisionMatrix <- matrix(c(
    rep(-qnorm(1 - alpha / 2), kMax),
    rep(qnorm(1 - alpha / 2), kMax)
), nrow = 2, byrow = TRUE)
informationRates <- (1:kMax) / kMax
probs <- getGroupSequentialProbabilities(decisionMatrix, informationRates)
cumsum(probs[3, ] - probs[2, ] + probs[1, ])

# Do the same for a one-sided design without futility boundaries:
decisionMatrix <- matrix(c(
    rep(-Inf, kMax),
    rep(qnorm(1 - alpha), kMax)
), nrow = 2, byrow = TRUE)
informationRates <- (1:kMax) / kMax
probs <- getGroupSequentialProbabilities(decisionMatrix, informationRates)
cumsum(probs[3, ] - probs[2, ])

# Check that two-sided Pampallona and Tsiatis boundaries with binding 
# futility bounds obtain Type I error probabilities equal to alpha:
x <- getDesignGroupSequential(
    alpha = 0.05, beta = 0.1, kMax = 3, typeOfDesign = "PT",
    deltaPT0 = 0, deltaPT1 = 0.4, sided = 2, bindingFutility = TRUE
)
dm <- matrix(c(
    -x$criticalValues, -x$futilityBounds, 0,
    x$futilityBounds, 0, x$criticalValues
), nrow = 4, byrow = TRUE)
dm[is.na(dm)] <- 0
probs <- getGroupSequentialProbabilities(
    decisionMatrix = dm, informationRates = (1:3) / 3
)
sum(probs[5, ] - probs[4, ] + probs[1, ])

# Check the Type I error rate decrease when using non-binding futility bounds:
x <- getDesignGroupSequential(
    alpha = 0.05, beta = 0.1, kMax = 3, typeOfDesign = "PT",
    deltaPT0 = 0, deltaPT1 = 0.4, sided = 2, bindingFutility = FALSE
)
dm <- matrix(c(
    -x$criticalValues, -x$futilityBounds, 0,
    x$futilityBounds, 0, x$criticalValues
), nrow = 4, byrow = TRUE)
dm[is.na(dm)] <- 0
probs <- getGroupSequentialProbabilities(
    decisionMatrix = dm, informationRates = (1:3) / 3
)
sum(probs[5, ] - probs[4, ] + probs[1, ])

## End(Not run)

Description

Returns the number of recruited subjects at given time vector.

Usage

getNumberOfSubjects(
  time,
  ...,
  accrualTime = c(0, 12),
  accrualIntensity = 0.1,
  accrualIntensityType = c("auto", "absolute", "relative"),
  maxNumberOfSubjects = NA_real_
)

Arguments

Details

Calculate number of subjects over time range at given accrual time vector and accrual intensity. Intensity can either be defined in absolute or relative terms (for the latter, maxNumberOfSubjects needs to be defined)
The function is used by getSampleSizeSurvival().

Value

Returns a NumberOfSubjects object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

AccrualTime for defining the accrual time.

Examples

## Not run: 
getNumberOfSubjects(time = seq(10, 70, 10), accrualTime = c(0, 20, 60), 
    accrualIntensity = c(5, 20))

getNumberOfSubjects(time = seq(10, 70, 10), accrualTime = c(0, 20, 60), 
    accrualIntensity = c(0.1, 0.4), maxNumberOfSubjects = 900)

## End(Not run)

Description

Recalculates the observed information rates from the specified dataset.

Usage

getObservedInformationRates(
  dataInput,
  ...,
  maxInformation = NULL,
  informationEpsilon = NULL,
  stage = NA_integer_
)

Arguments

Details

For means and rates the maximum information is the maximum number of subjects or the relative proportion if informationEpsilon < 1; for survival data it is the maximum number of events or the relative proportion if informationEpsilon < 1.

Value

Returns a list that summarizes the observed information rates.

See Also

• getAnalysisResults() for using getObservedInformationRates() implicit,

• www.rpact.org/vignettes/planning/rpact_boundary_update_example

Examples

## Not run: 
# Absolute information epsilon:
# decision rule 45 >= 46 - 1, i.e., under-running
data <- getDataset(
    overallN = c(22, 45),
    overallEvents = c(11, 28)
)
getObservedInformationRates(data,
    maxInformation = 46, informationEpsilon = 1
)

# Relative information epsilon:
# last information rate = 45/46 = 0.9783,
# is > 1 - 0.03 = 0.97, i.e., under-running
data <- getDataset(
    overallN = c(22, 45),
    overallEvents = c(11, 28)
)
getObservedInformationRates(data,
    maxInformation = 46, informationEpsilon = 0.03
)

## End(Not run)

Description

With this function the format of the standard outputs of all rpact objects can be shown and written to a file.

Usage

getOutputFormat(
  parameterName = NA_character_,
  ...,
  file = NA_character_,
  default = FALSE,
  fields = TRUE
)

Arguments

Details

Output formats can be written to a text file by specifying a file. See setOutputFormat()() to learn how to read a formerly saved file.

Note that the parameterName must not match exactly, e.g., for p-values the following parameter names will be recognized amongst others:

1. p value

2. p.values

3. p-value

4. pValue

5. rpact.output.format.p.value

Value

A named list of output formats.

See Also

Other output formats: setOutputFormat()

Examples

## Not run: 
# show output format of p values
getOutputFormat("p.value")

# set new p value output format
setOutputFormat("p.value", digits = 5, nsmall = 5)

# show sample sizes as smallest integers not less than the not rounded values
setOutputFormat("sample size", digits = 0, nsmall = 0, roundFunction = "ceiling")
getSampleSizeMeans()

# show sample sizes as smallest integers not greater than the not rounded values
setOutputFormat("sample size", digits = 0, nsmall = 0, roundFunction = "floor")
getSampleSizeMeans()

# set new sample size output format without round function
setOutputFormat("sample size", digits = 2, nsmall = 2)
getSampleSizeMeans()

# reset sample size output format to default
setOutputFormat("sample size")
getSampleSizeMeans()
getOutputFormat("sample size")

## End(Not run)

Description

Calculates the conditional performance score, its sub-scores and components according to (Herrmann et al. (2020), doi:10.1002/sim.8534) and (Bokelmann et al. (2024), doi:10.1186/s12874-024-02150-4) for a given simulation result from a two-stage design with continuous or binary endpoint. Larger (sub-)score and component values refer to a better performance.

Usage

getPerformanceScore(simulationResult)

Arguments

Details

The conditional performance score consists of two sub-scores, one for the sample size (subscoreSampleSize) and one for the conditional power (subscoreConditionalPower). Each of those are composed of a location (locationSampleSize, locationConditionalPower) and variation component (variationSampleSize, variationConditionalPower). The term conditional refers to an evaluation perspective where the interim results suggest a trial continuation with a second stage. The score can take values between 0 and 1. More details on the performance score can be found in Herrmann et al. (2020), doi:10.1002/sim.8534 and Bokelmann et al. (2024) doi:10.1186/s12874-024-02150-4.

Author(s)

Stephen Schueuerhuis

Examples

## Not run: 
# Example from Table 3 in "A new conditional performance score for 
# the evaluation of adaptive group sequential designs with samplesize 
# recalculation from Herrmann et al 2023", p. 2097 for 
# Observed Conditional Power approach and Delta = 0.5

# Create two-stage Pocock design with binding futility boundary at 0
design <- getDesignGroupSequential(
    kMax = 2, typeOfDesign = "P", 
    futilityBounds = 0, bindingFutility = TRUE)

# Initialize sample sizes and effect; 
# Sample sizes are referring to overall stage-wise sample sizes
n1 <- 100
n2 <- 100
nMax <- n1 + n2
alternative <- 0.5

# Perform Simulation; nMax * 1.5 defines the maximum 
# sample size for the additional stage
simulationResult <- getSimulationMeans(
    design = design,
    normalApproximation = TRUE,
    thetaH0 = 0,
    alternative = alternative,
    plannedSubjects = c(n1, nMax),
    minNumberOfSubjectsPerStage = c(NA_real_, 1),
    maxNumberOfSubjectsPerStage = c(NA_real_, nMax * 1.5),
    conditionalPower = 0.8,
    directionUpper = TRUE,
    maxNumberOfIterations = 1e05,
    seed = 140
)

# Calculate performance score
getPerformanceScore(simulationResult)

## End(Not run)

Description

Returns a PiecewiseSurvivalTime object that contains the all relevant parameters of an exponential survival time cumulative distribution function. Use names to obtain the field names.

Usage

getPiecewiseSurvivalTime(
  piecewiseSurvivalTime = NA_real_,
  ...,
  lambda1 = NA_real_,
  lambda2 = NA_real_,
  hazardRatio = NA_real_,
  pi1 = NA_real_,
  pi2 = NA_real_,
  median1 = NA_real_,
  median2 = NA_real_,
  eventTime = 12,
  kappa = 1,
  delayedResponseAllowed = FALSE
)

Arguments

Value

Returns a PiecewiseSurvivalTime object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

Piecewise survival time

The first element of the vector piecewiseSurvivalTime must be equal to 0. piecewiseSurvivalTime can also be a list that combines the definition of the time intervals and hazard rates in the reference group. The definition of the survival time in the treatment group is obtained by the specification of the hazard ratio (see examples for details).

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

Examples

## Not run: 
getPiecewiseSurvivalTime(lambda2 = 0.5, hazardRatio = 0.8)

getPiecewiseSurvivalTime(lambda2 = 0.5, lambda1 = 0.4)

getPiecewiseSurvivalTime(pi2 = 0.5, hazardRatio = 0.8)

getPiecewiseSurvivalTime(pi2 = 0.5, pi1 = 0.4)

getPiecewiseSurvivalTime(pi1 = 0.3)

getPiecewiseSurvivalTime(hazardRatio = c(0.6, 0.8), lambda2 = 0.4)

getPiecewiseSurvivalTime(piecewiseSurvivalTime = c(0, 6, 9), 
    lambda2 = c(0.025, 0.04, 0.015), hazardRatio = 0.8)

getPiecewiseSurvivalTime(piecewiseSurvivalTime = c(0, 6, 9), 
    lambda2 = c(0.025, 0.04, 0.015), 
    lambda1 = c(0.025, 0.04, 0.015) * 0.8)

pwst <- getPiecewiseSurvivalTime(list(
    "0 - <6"   = 0.025, 
    "6 - <9"   = 0.04, 
    "9 - <15"  = 0.015, 
    "15 - <21" = 0.01, 
    ">=21"     = 0.007), hazardRatio = 0.75)
pwst

# The object created by getPiecewiseSurvivalTime() can be used directly in 
# getSampleSizeSurvival():
getSampleSizeSurvival(piecewiseSurvivalTime = pwst)

# The object created by getPiecewiseSurvivalTime() can be used directly in 
# getPowerSurvival():
getPowerSurvival(piecewiseSurvivalTime = pwst, 
    maxNumberOfEvents = 40, maxNumberOfSubjects = 100)

## End(Not run)

Description

Returns the power and average sample number of the specified design.

Usage

getPowerAndAverageSampleNumber(design, theta = seq(-1, 1, 0.02), nMax = 100)

Arguments

Details

This function returns the power and average sample number (ASN) of the specified design for the prototype case which is testing H0: mu = mu0 in a one-sample design. theta represents the standardized effect (mu - mu0) / sigma and power and ASN is calculated for maximum sample size nMax. For other designs than the one-sample test of a mean the standardized effect needs to be adjusted accordingly.

Value

Returns a PowerAndAverageSampleNumberResult object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFisher(), getDesignGroupSequential(), getDesignInverseNormal(), getGroupSequentialProbabilities()

Examples

## Not run: 
# Calculate power, stopping probabilities, and expected sample 
# size for the default design with specified theta and nMax  
getPowerAndAverageSampleNumber(
    getDesignGroupSequential(), 
    theta = seq(-1, 1, 0.5), nMax = 100)

## End(Not run)

Description

Returns the power, stopping probabilities, and expected sample size for testing mean rates for negative binomial distributed event numbers in two samples at given sample sizes.

Usage

getPowerCounts(
  design = NULL,
  ...,
  directionUpper = NA,
  maxNumberOfSubjects = NA_real_,
  lambda1 = NA_real_,
  lambda2 = NA_real_,
  lambda = NA_real_,
  theta = NA_real_,
  thetaH0 = 1,
  overdispersion = 0,
  fixedExposureTime = NA_real_,
  accrualTime = NA_real_,
  accrualIntensity = NA_real_,
  followUpTime = NA_real_,
  allocationRatioPlanned = NA_real_
)

Arguments

Details

At given design the function calculates the power, stopping probabilities, and expected sample size for testing the ratio of two mean rates of negative binomial distributed event numbers in two samples at given maximum sample size and effect. The power calculation is performed either for a fixed exposure time or a variable exposure time with fixed follow-up where the information over the stages is calculated according to the specified information rate in the design. Additionally, an allocation ratio = n1 / n2 can be specified where n1 and n2 are the number of subjects in the two treatment groups. A null hypothesis value thetaH0 can also be specified.

Value

Returns a TrialDesignPlan object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other power functions: getPowerMeans(), getPowerRates(), getPowerSurvival()

Examples

## Not run: 
# Fixed sample size trial where a therapy is assumed to decrease the 
# exacerbation rate from 1.4 to 1.05 (25% decrease) within an 
# observation period of 1 year, i.e., each subject has a equal 
# follow-up of 1 year.
# Calculate power at significance level 0.025 at given sample size = 180 
# for a range of lambda1 values if the overdispersion is assumed to be 
# equal to 0.5, is obtained by
getPowerCounts(alpha = 0.025, lambda1 = seq(1, 1.4, 0.05), lambda2 = 1.4, 
    maxNumberOfSubjects = 180, overdispersion = 0.5, fixedExposureTime = 1)

# Group sequential alpha and beta spending function design with O'Brien and 
# Fleming type boundaries: Power and test characteristics for N = 286, 
# under the assumption of a fixed exposure time, and for a range of 
# lambda1 values: 
getPowerCounts(design = getDesignGroupSequential(
        kMax = 3, alpha = 0.025, beta = 0.2, 
        typeOfDesign = "asOF", typeBetaSpending = "bsOF"), 
    lambda1 = seq(0.17, 0.23, 0.01), lambda2 = 0.3, 
    directionUpper = FALSE, overdispersion = 1, maxNumberOfSubjects = 286, 
    fixedExposureTime = 12, accrualTime = 6)

# Group sequential design alpha spending function design with O'Brien and 
# Fleming type boundaries: Power and test characteristics for N = 1976, 
# under variable exposure time with uniform recruitment over 1.25 months,
# study time (accrual + followup) = 4 (lambda1, lambda2, and overdispersion 
# as specified, no futility stopping):
getPowerCounts(design = getDesignGroupSequential(
        kMax = 3, alpha = 0.025, beta = 0.2, typeOfDesign = "asOF"),
    lambda1 = seq(0.08, 0.09, 0.0025), lambda2 = 0.125, 
    overdispersion = 5, directionUpper = FALSE, maxNumberOfSubjects = 1976, 
    followUpTime = 2.75, accrualTime = 1.25)

## End(Not run)

Description

Returns the power, stopping probabilities, and expected sample size for testing means in one or two samples at given maximum sample size.

Usage

getPowerMeans(
  design = NULL,
  ...,
  groups = 2L,
  normalApproximation = FALSE,
  meanRatio = FALSE,
  thetaH0 = ifelse(meanRatio, 1, 0),
  alternative = seq(0, 1, 0.2),
  stDev = 1,
  directionUpper = NA,
  maxNumberOfSubjects = NA_real_,
  allocationRatioPlanned = NA_real_
)

Arguments

Details

At given design the function calculates the power, stopping probabilities, and expected sample size for testing means at given sample size. In a two treatment groups design, additionally, an allocation ratio = n1 / n2 can be specified where n1 and n2 are the number of subjects in the two treatment groups. A null hypothesis value thetaH0 != 0 for testing the difference of two means or thetaH0 != 1 for testing the ratio of two means can be specified. For the specified sample size, critical bounds and stopping for futility bounds are provided at the effect scale (mean, mean difference, or mean ratio, respectively)

Value

Returns a TrialDesignPlan object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other power functions: getPowerCounts(), getPowerRates(), getPowerSurvival()

Examples

## Not run: 
# Calculate the power, stopping probabilities, and expected sample size 
# for testing H0: mu1 - mu2 = 0 in a two-armed design against a range of 
# alternatives H1: mu1 - m2 = delta, delta = (0, 1, 2, 3, 4, 5), 
# standard deviation sigma = 8, maximum sample size N = 80 (both treatment 
# arms), and an allocation ratio n1/n2 = 2. The design is a three stage 
# O'Brien & Fleming design with non-binding futility bounds (-0.5, 0.5) 
# for the two interims. The computation takes into account that the t test 
# is used (normalApproximation = FALSE). 
getPowerMeans(getDesignGroupSequential(alpha = 0.025, 
    sided = 1, futilityBounds = c(-0.5, 0.5)), 
    groups = 2, alternative = c(0:5), stDev = 8,
    normalApproximation = FALSE, maxNumberOfSubjects = 80, 
    allocationRatioPlanned = 2)

## End(Not run)

Description

Returns the power, stopping probabilities, and expected sample size for testing rates in one or two samples at given maximum sample size.

Usage

getPowerRates(
  design = NULL,
  ...,
  groups = 2L,
  riskRatio = FALSE,
  thetaH0 = ifelse(riskRatio, 1, 0),
  pi1 = seq(0.2, 0.5, 0.1),
  pi2 = 0.2,
  directionUpper = NA,
  maxNumberOfSubjects = NA_real_,
  allocationRatioPlanned = NA_real_
)

Arguments

Details

At given design the function calculates the power, stopping probabilities, and expected sample size for testing rates at given maximum sample size. The sample sizes over the stages are calculated according to the specified information rate in the design. In a two treatment groups design, additionally, an allocation ratio = n1 / n2 can be specified where n1 and n2 are the number of subjects in the two treatment groups. If a null hypothesis value thetaH0 != 0 for testing the difference of two rates or thetaH0 != 1 for testing the risk ratio is specified, the formulas according to Farrington & Manning (Statistics in Medicine, 1990) are used (only one-sided testing). Critical bounds and stopping for futility bounds are provided at the effect scale (rate, rate difference, or rate ratio, respectively). For the two-sample case, the calculation here is performed at fixed pi2 as given as argument in the function. Note that the power calculation for rates is always based on the normal approximation.

Value

Returns a TrialDesignPlan object. The following generics (R generic functions) are available for this result object:

• names() to obtain the field names,

• print() to print the object,

• summary() to display a summary of the object,

• plot() to plot the object,

• as.data.frame() to coerce the object to a data.frame,

• as.matrix() to coerce the object to a matrix.

How to get help for generic functions

Click on the link of a generic in the list above to go directly to the help documentation of the rpact specific implementation of the generic. Note that you can use the R function methods to get all the methods of a generic and to identify the object specific name of it, e.g., use methods("plot") to get all the methods for the plot generic. There you can find, e.g., plot.AnalysisResults and obtain the specific help documentation linked above by typing ?plot.AnalysisResults.

See Also

Other power functions: getPowerCounts(), getPowerMeans(), getPowerSurvival()

Examples

## Not run: 
# Calculate the power, stopping probabilities, and expected sample size in a
# two-armed design at given maximum sample size N = 200 in a three-stage 
# O'Brien & Fleming design with information rate vector (0.2,0.5,1), 
# non-binding futility boundaries (0,0), i.e., the study stops for futility 
# if the p-value exceeds 0.5 at interm, and allocation ratio = 2 for a range 
# of pi1 values when testing H0: pi1 - pi2 = -0.1:
getPowerRates(getDesignGroupSequential(informationRates = c(0.2, 0.5, 1), 
    futilityBounds = c(0, 0)), groups = 2, thetaH0 = -0.1, 
    pi1 = seq(0.3, 0.6, 0.1), directionUpper = FALSE, 
    pi2 = 0.7, allocationRatioPlanned = 2, maxNumberOfSubjects = 200)

# Calculate the power, stopping probabilities, and expected sample size in a single 
# arm design at given maximum sample size N = 60 in a three-stage two-sided 
# O'Brien & Fleming design with information rate vector (0.2, 0.5,1) 
# for a range of pi1 values when testing H0: pi = 0.3:
getPowerRates(getDesignGroupSequential(informationRates = c(0.2, 0.5,1), 
    sided = 2), groups = 1, thetaH0 = 0.3, pi1 = seq(0.3, 0.5, 0.05),  
    maxNumberOfSubjects = 60)

## End(Not run)