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.

Note

Repeated p-values are calculated by identifying the smallest global significance level for which the observed test statistic would lead to rejection under the same design rule. Therefore, they require that the design can be re-created for arbitrary values of the global significance level. For user-defined designs with fixed userAlphaSpending values, this alpha-dependent design family is not uniquely defined. Consequently, repeated p-values are not available for such designs.

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 (2025), 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

Calculate the Optimal Conditional Error

Usage

getConditionalError(design, pValue, stage = 1)

Arguments

Details

The optimal conditional error $\alpha_2$ given a first-stage p-value $p_1$ is calculated as:

$\alpha_2(p_1)=\psi(-e^{c_0} \cdot \frac{\Delta_1^2}{l(p_1)}).$

The level constant $c_0$ as well as the specification of the effect size $\Delta_1$ and the likelihood ratio $l(p_1)$ must be contained in the design object (see ?getDesignOptimalConditionalError). Early stopping rules are supported, i.e., for $p_1 \leq \alpha_1$ with $\alpha_1 > 0$, the returned conditional error is 1 and for $p_1 > \alpha_0$, the returned conditional error is 0.

Value

A numeric vector of conditional errors, one per first-stage p-value.

References

Brannath, W. & Bauer, P. (2004). Optimal conditional error functions for the control of conditional power. Biometrics, 60(3), 715-723. doi:10.1111/j.0006-341X.2004.00221.x

Brannath, W., zur Verth, J., Dreher, M. & Scharpenberg, M. (2024; revised 2026). Optimal monotone conditional error functions. doi:10.48550/arXiv.2402.00814

The related R package optconerrf: Optimal Monotone Conditional Error Functions provides a standalone implementation of this methodology. The rpact implementation uses rpact design objects and interfaces; optconerrf is not required to run these functions.

See Also

Optimal Conditional Error Designs with rpact for a worked example with stopping rules, information constraints, interim estimates, and conditional power functions.

getDesignOptimalConditionalError()

Examples

# Create a design
design <- getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5, conditionalPower = 0.9,
    thetaH1 = 0.5, firstStageInformation = 40, useInterimEstimate = FALSE,
    likelihoodRatioDistribution = "fixed", thetaLR = 0.5
)

# Early efficacy gives 1, continuation gives the stage-two threshold,
# and binding futility gives 0.
getConditionalError(
    pValue = c(0.0005, 0.1, 0.3, 0.8), design = design
)

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(). Multi-arm simulation data additionally contain selectedForNextStage. At non-final stages, this logical value indicates whether the adaptation selected the arm to continue, conditional on the trial not stopping; it is NA at the final stage. In contrast, rejectPerStage indicates rejection of the arm's null hypothesis, while futilityPerStage is a trial-level futility-stopping decision repeated for the arm rows of the stage.

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 DatasetGeneral, DatasetMeans, DatasetRates, or DatasetSurvival can be created as follows:

• An element of DatasetGeneral for general estimates is created by
  getDataset(est =, se =, df =) where est, se, and optionally df are vectors with stage-wise estimates, standard errors, and degrees of freedom. If df is omitted, the degrees of freedom are set to Inf, corresponding to a normal approximation.

• 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 General Estimates without specifying degrees
# of freedom (internally, df is set to Inf for all stages):
datasetOfGeneralEstimates <- getDataset(
    est = c(0.10, 0.25, 0.38),
    se  = c(0.20, 0.18, 0.15)
)
datasetOfGeneralEstimates
datasetOfGeneralEstimates$degreesOfFreedom

# It is also possible to specify the degrees of freedom for each stage.
# Typically these come from a linear model analysis, e.g. with repeated measures
# using the [`mmrm`](https://cran.r-project.org/package=mmrm) package.
datasetOfLeastSquareMeans <- getDataset(
    est = c(0.10, 0.25, 0.38),
    se  = c(0.20, 0.18, 0.15),
    df  = c(10.3, 12.5, 15.1)
)
datasetOfLeastSquareMeans

# 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.

For an optimal conditional error design, supply theta through ... as a finite numeric vector of treatment effects on the mean difference scale. The design is evaluated at those effects without recalibration.

Value

For an optimal conditional error design, a TrialDesignOptimalConditionalErrorCharacteristics parameter set with theta, overallReject, rejectPerStage (two rows, one per stage), and futilityPerStage (one row for interim futility). Matrix columns correspond to entries in theta, including for a single effect. Final non-rejection is not counted as early futility. overallReject is overall power under an alternative and the type I error probability at theta = 0. See getDesignOptimalConditionalError() for the method and its assumptions.

For conventional designs, 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.

References

Brannath, W. & Bauer, P. (2004). Optimal conditional error functions for the control of conditional power. Biometrics, 60(3), 715-723. doi:10.1111/j.0006-341X.2004.00221.x

Brannath, W., zur Verth, J., Dreher, M. & Scharpenberg, M. (2024; revised 2026). Optimal monotone conditional error functions. doi:10.48550/arXiv.2402.00814

The related R package optconerrf: Optimal Monotone Conditional Error Functions provides a standalone implementation of this methodology. The rpact implementation uses rpact design objects and interfaces; optconerrf is not required to run these functions.

See Also

Optimal Conditional Error Designs with rpact for a worked example with stopping rules, information constraints, interim estimates, and conditional power functions.

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

Examples

design <- getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5, conditionalPower = 0.9,
    thetaH1 = 0.5, useInterimEstimate = FALSE, firstStageInformation = 4,
    likelihoodRatioDistribution = "maxlr"
)
getDesignCharacteristics(design, theta = c(0, 0.25, 0.5))

## 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 (2025), 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(), getDesignFixed(), 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_,
  alpha0Scale = c("pValue", "zValue", "condPowerAtObserved", "predictivePower"),
  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.

getFutilityBounds() for the specification of futility bounds on scales other than the p-value scale.

Vignette: Enhanced Futility Bounds Specification

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFixed(), 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

Create a fixed (single-stage) trial design. This convenience wrapper constructs an object of class TrialDesignFixed with kMax = 1.

Usage

getDesignFixed(
  alpha = NA_real_,
  beta = NA_real_,
  sided = 1L,
  directionUpper = NA,
  twoSidedPower = NA
)

Arguments

Details

The fixed design represents a single-stage hypothesis test. The returned object can be used with the standard analysis and plotting helpers in the package. Typical use is to specify the type I error alpha and the desired type II error beta (or equivalently power = 1 - beta).

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.

See Also

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

Examples

# Basic fixed design with default alpha and beta
design <- getDesignFixed()
design

# Custom significance and power
design2 <- getDesignFixed(alpha = 0.05, beta = 0.1)
design2

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_,
  efficacyStops = NA,
  futilityStops = NA,
  gammaB = NA_real_,
  bindingFutility = NA,
  futilityBoundsScale = c("zValue", "pValue", "reverseCondPower", "condPowerAtObserved",
    "predictivePower"),
  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.

getFutilityBounds() for the specification of futility bounds on scales other than the z-value scale.

Vignette: Enhanced Futility Bounds Specification

Other design functions: getDesignCharacteristics(), getDesignConditionalDunnett(), getDesignFisher(), getDesignFixed(), 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_,
  efficacyStops = NA,
  futilityStops = NA,
  gammaB = NA_real_,
  bindingFutility = NA,
  futilityBoundsScale = c("zValue", "pValue", "reverseCondPower", "condPowerAtObserved",
    "predictivePower"),
  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(), getDesignFixed(), 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

This function returns a design object which contains all important parameters for the specification of the optimal conditional error function. The returned object is of class TrialDesignOptimalConditionalError and can be passed to other package functions.

Usage

getDesignOptimalConditionalError(
  alpha,
  efficacyBounds,
  futilityBounds,
  conditionalPower = NA_real_,
  thetaH1 = NA_real_,
  minThetaH1 = NA_real_,
  maxThetaH1 = Inf,
  useInterimEstimate = TRUE,
  firstStageInformation,
  likelihoodRatioDistribution,
  minInformationPerStage = 0,
  maxInformationPerStage = Inf,
  minConditionalError = 0,
  maxConditionalError = 1,
  conditionalPowerFunction = NULL,
  minLevelConstant = 0,
  maxLevelConstant = 10,
  enforceMonotonicity = TRUE,
  efficacyBoundsScale = "pValue",
  futilityBoundsScale = "pValue",
  nonCentralityParameterH1 = NULL,
  minNonCentralityParameterH1 = NULL,
  maxNonCentralityParameterH1 = Inf,
  ...
)

Arguments

Details

The design object contains the information required to determine the specific setting of the optimal conditional error function and can be passed to other package functions. From the given user specifications, the constant to achieve level condition for control of the overall type I error rate as well as the constants to ensure a non-increasing optimal CEF (if required) are automatically calculated.

Value

An object of class TrialDesignOptimalConditionalError, which can be passed to getConditionalError(), getStageInformation(), and getDesignCharacteristics(). This adaptive design is not interchangeable with a conventional TrialDesign.

Hypotheses and trial decisions

The one-sided hypotheses are $H_0: \Delta \leq 0$ versus $H_1: \Delta > 0$. With a first-stage p-value $p_1$, stop for efficacy if $p_1 \leq \alpha_1$ and $\alpha_1 > 0$; stop for futility if $p_1 > \alpha_0$. Futility is binding: continuing beyond this boundary is not part of the calibrated design. In the continuation region, reject at stage two if its p-value is no larger than getConditionalError(). The second-stage p-value must be based on the new, independent second-stage data, not the cumulative data. Setting efficacyBounds = 0 disables early efficacy and futilityBounds = 1 disables early futility. Here, $\alpha_1$ denotes efficacyBounds and $\alpha_0$ denotes futilityBounds; both are single interim cutoffs on the p-value scale. The calibration satisfies

$\alpha = \alpha_1 + \int_{\alpha_1}^{\alpha_0} \alpha_2(p_1) \, dp_1.$

Target conditional power refers to a specified planning effect after continuation; it is not the overall power returned by getDesignCharacteristics().

Likelihood ratio distribution

To calculate the optimal conditional error function, an assumption about the true parameter under which the second-stage information is to be minimised is required. Various options are available and can be specified via the argument likelihoodRatioDistribution:

• likelihoodRatioDistribution="fixed": calculates the likelihood ratio for a fixed $\Delta$. The non-centrality parameter of the likelihood ratio $\vartheta$ is then computed as thetaLR*sqrt(firstStageInformation) and the likelihood ratio is calculated as:

  $l(p_1) = e^{\Phi^{-1}(1-p_1)\vartheta - \vartheta^2/2}.$

  thetaLR may also contain multiple elements, in which case a weighted likelihood ratio is calculated for the given values. Unless positive weights that sum to 1 are provided by the argument weightsLR, equal weights are assumed.

• likelihoodRatioDistribution="normal": calculates the likelihood ratio for a normally distributed prior of $\vartheta$ with mean thetaLR*sqrt(firstStageInformation) ($\mu$) and standard deviation stDevLR*sqrt(firstStageInformation) ($\sigma$). The parameters thetaLR and stDevLR must be specified on the mean difference scale.

  $l(p_1) = (1+\sigma^2)^{-\frac{1}{2}}\cdot e^{-(\mu/\sigma)^2/2 + (\sigma\Phi^{-1}(1-p_1) + \mu/\sigma)^2 / (2\cdot (1+\sigma^2))}$

• likelihoodRatioDistribution="exp": calculates the likelihood ratio for an exponentially distributed prior of $\vartheta$ with rate kappaLR*sqrt(firstStageInformation) ($\eta$). The likelihood ratio is then calculated as:

  $l(p_1) = \eta \cdot \sqrt{2\pi} \cdot e^{(\Phi^{-1}(1-p_1)-\eta)^2/2} \cdot \Phi(\Phi^{-1}(1-p_1)-\eta)$

• likelihoodRatioDistribution="unif": calculates the likelihood ratio for a uniformly distributed prior of $\vartheta$ on the support $[0, \Delta\cdot\sqrt{I_1}]$, where $\Delta$ is specified as maxThetaLR and $I_1$ is the firstStageInformation.

  $l(p_1) = \frac{\sqrt{2\pi}}{\Delta\cdot\sqrt{I_1}} \cdot e^{\Phi^{-1}(1-p_1)^2/2} \cdot (\Phi(\Delta\cdot\sqrt{I_1} - \Phi^{-1}(1-p_1))-p_1)$

• likelihoodRatioDistribution="maxlr": the non-centrality parameter $\vartheta$ is estimated from the data and no additional parameters must be specified. The likelihood ratio is estimated from the data as:

  $l(p_1) = e^{max(0, \Phi^{-1}(1-p_1))^2/2}$

  The maximum likelihood ratio is always restricted to effect sizes $\vartheta \geq 0$ (corresponding to $p_1 \leq 0.5$).

Effect for conditional power

For the treatment effect at which the target conditional power should be achieved, either a fixed effect or an interim estimate can be used. The planning effect thetaH1 need not equal thetaLR: the former sets the conditional power target, whereas the latter specifies the effect or mixture under which expected second-stage information is minimised. The usage of a fixed effect is indicated by setting useInterimEstimate=FALSE, in which case the fixed effect is provided by thetaH1 on the mean difference scale. For an interim estimate, specified by useInterimEstimate=TRUE, a lower cut-off for the interim estimate must be provided, by minThetaH1 on the mean difference scale. In addition, an upper limit of the estimate may be analogously provided by maxThetaH1. These effects may alternatively be specified on the non-centrality parameter scale as nonCentralityParameterH1, minNonCentralityParameterH1, and maxNonCentralityParameterH1.

Sample size and information

The first-stage information of the trial design must be specified to allow for calculations between the mean difference and non-centrality parameter scale. It is provided to the design object via firstStageInformation.
Listed below are some examples for the calculation between information ($I_1$) and sample size:

• One-sample z-test with $n$ total patients: $I_1 = \frac{n}{\sigma^2}$, where $\sigma^2$ is the variance of an individual observation

• Balanced two-sample z-test with $n_1$ patients per group: $I_1 = \frac{1}{2}\cdot\frac{n_1}{\sigma^2}$, where $\sigma^2$ is the common variance

• General two-sample z-test with $n_1$, $n_2$ patients per group: $I_1 = 1/(\frac{\sigma_1^2}{n_1}+\frac{\sigma_2^2}{n_2})$, where $\sigma_1^2$, $\sigma_2^2$ are the group-wise variances

Monotonicity

By default, the function Q (likelihood ratio divided by the squared effect) is transformed to be non-increasing in the first-stage p-value. For constant conditional power this yields a non-increasing conditional error function. A conditional power callback combined with interim effect estimates and information constraints can still produce a non-monotone conditional error function; enforceMonotonicity does not guarantee monotonicity in that setting. The necessary intervals and constants for the transformation are calculated by an internal monotonisation routine. Although not recommended for the operating characteristics of the design, the transformation may be omitted by setting enforceMonotonicity=FALSE.

Constraints

In some applications, it may be feasible to restrict the optimal conditional error function by a lower and/or upper limit. These constraints can be directly implemented on the function by using the arguments minConditionalError and maxConditionalError. By default, minConditionalError=0 and maxConditionalError=1, i.e., no constraints are applied. The constraints may also be specified on the second-stage information via minInformationPerStage and maxInformationPerStage. If both minConditionalError and maxInformationPerStage respectively maxConditionalError and minInformationPerStage are provided, both constraints will be applied. Set these constraints when creating the design, so that calibration accounts for them. For fixed $\Delta_1$ and conditional power $CP$, an upper information bound corresponds to the lower conditional error bound $\Phi(\Phi^{-1}(CP) - \Delta_1 \sqrt{I_{2,\max}})$; a lower information bound analogously corresponds to an upper conditional error bound. Information bounds apply only when the trial continues: information is zero after early stopping. They refer to additional stage-two information, not cumulative information. minInformationPerStage and maxInformationPerStage are scalar limits for stage two only; they do not constrain firstStageInformation. In the continuation region, conditional error cannot exceed the conditional power; an upper bound above it has no additional effect. Before calibration, the integrated lower and upper bounds are checked for compatibility with the overall alpha level.

Level constant

The level constant is determined by an internal root-finding routine. It is identified using the uniroot() function and by default, the interval between 0 and 10 is searched for the level constant. In specific settings, the level constant may lie outside of this interval. In such cases, the search interval can be changed by altering the parameters minLevelConstant and maxLevelConstant.
If inappropriate constraints to the optimal conditional error function are provided via minConditionalError and maxConditionalError or minInformationPerStage and maxInformationPerStage, it may be impossible to find a level constant which exhausts the full alpha level.

Numerical integration uses an adapted routine for piecewise constant functions where applicable. Set options(rpact.design.optimal.enforce.basic.integration = TRUE) to use standard adaptive integration for comparison.

Generic functions

The print() and plot() functions are available for objects of class TrialDesignOptimalConditionalError. For details, see ?print.TrialDesignOptimalConditionalError and ?plot.TrialDesignOptimalConditionalError.

References

Brannath, W. & Bauer, P. (2004). Optimal conditional error functions for the control of conditional power. Biometrics, 60(3), 715-723. doi:10.1111/j.0006-341X.2004.00221.x

Brannath, W., zur Verth, J., Dreher, M. & Scharpenberg, M. (2024; revised 2026). Optimal monotone conditional error functions. doi:10.48550/arXiv.2402.00814

The related R package optconerrf: Optimal Monotone Conditional Error Functions provides a standalone implementation of this methodology. The rpact implementation uses rpact design objects and interfaces; optconerrf is not required to run these functions.

See Also

Optimal Conditional Error Designs with rpact for a worked example with stopping rules, information constraints, interim estimates, and conditional power functions.

Examples

# Create a single-arm design with fixed parameter for the likelihood ratio
# and a fixed effect for conditional power. 80 patients are observed in the
# first-stage (firstStageInformation = 80 in the one-sample test, variance 1).
# The second-stage information is restricted to be between 40 and 160.
getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5, conditionalPower = 0.9,
    thetaH1 = 0.25, likelihoodRatioDistribution = "fixed", thetaLR = 0.25,
    firstStageInformation = 80, useInterimEstimate = FALSE,
    minInformationPerStage = 40, maxInformationPerStage = 160
)

# Create a design comparing two groups using the maximum likelihood ratio
# and an interim estimate for the effect for conditional power.
# 160 patients per arm are observed in the first stage
# (firstStageInformation = 80 in the balanced two-sample test, variance 1).
getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5, conditionalPower = 0.9,
    minThetaH1 = 0.25, likelihoodRatioDistribution = "maxlr",
    firstStageInformation = 80, useInterimEstimate = TRUE
)

# Weight several effects for the optimisation; retain a separate power target.
weightedDesign <- getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5, conditionalPower = 0.9,
    thetaH1 = 0.25, useInterimEstimate = FALSE, firstStageInformation = 80,
    likelihoodRatioDistribution = "fixed", thetaLR = c(0, 0.25, 0.5),
    weightsLR = c(0.25, 0.5, 0.25)
)
getStageInformation(pValue = c(0.05, 0.1, 0.3), design = weightedDesign)

# Allow a lower conditional power target for less promising interim results.
# Leave conditionalPower unspecified when supplying a callback.
flexibleDesign <- getDesignOptimalConditionalError(
    alpha = 0.025, efficacyBounds = 0.001, futilityBounds = 0.5,
    conditionalPowerFunction = function(p) pnorm(1 - p),
    thetaH1 = 0.25, useInterimEstimate = FALSE, firstStageInformation = 80,
    likelihoodRatioDistribution = "maxlr"
)
getConditionalError(pValue = c(0.05, 0.1, 0.3), design = flexibleDesign)

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 cumulative or stage-wise Fisher information at planned analyses for a design plan or simulation results object for means, rates, survival, or count data endpoints. This is particularly useful for calculating the information argument of getFutilityBounds().

Usage

getFisherInformation(
  designPlan,
  stage = NA_integer_,
  type = c("cumulative", "stageWise")
)

Arguments

Details

Cumulative information

With type = "cumulative", the function returns the total Fisher information available at each requested analysis, including information accumulated during all preceding stages. With type = "stageWise", it returns the increment contributed by each requested stage. The stage-wise value for stage j > 1 is calculated by subtracting the cumulative information at stage j - 1 from that at stage j, even if stage j - 1 was not included in stage. At the first analysis, cumulative and stage-wise information are identical.

To obtain stage-wise increments from cumulative values $I_1,\ldots,I_k$, use $I_1, I_2-I_1,\ldots,I_k-I_{k-1}$. For example:

informationCumulative <- as.numeric(getFisherInformation(
    designPlan,
    stage = 1:2
))
informationStageWise <- c(
    informationCumulative[1],
    diff(informationCumulative)
)

If the result contains several planning alternatives or treatment comparisons, apply the differences separately to each corresponding series. The function performs this calculation directly when type = "stageWise"; the explicit calculation above illustrates its definition.

Calculation by endpoint

Means

For a one-sample comparison, information is the cumulative sample size divided by the variance. For a two-sample comparison, it is the inverse variance of the estimated treatment difference, based on cumulative group sizes, standard deviations, and the planned allocation ratio. For a mean-ratio analysis, the null value is additionally taken into account.

Rates

Information is the inverse binomial variance of the estimated rate or rate difference under the planning assumptions. It uses cumulative planned sample sizes, event probabilities, and, for multiple groups, the planned allocation ratio.

Survival

Information is based on the cumulative number of events at the requested analysis and the planned allocation ratio. For multi-arm designs, the available events are apportioned to the relevant treatment comparisons using the planning assumptions.

Count data

Information is based on the negative binomial model and includes all exposure accumulated up to the requested analysis time. It accounts for recruitment, exposure or follow-up time, event rates, allocation ratio, and overdispersion. If the design plan already contains information by analysis, those stored cumulative values are used.

Use with getFutilityBounds

For a conversion involving "effectEstimate", pass the cumulative information returned for the relevant analysis as information[1]. For conditional- or predictive-power conversions in a two-stage setting, getFutilityBounds() interprets information[1] as the cumulative information at the first analysis and information[2] as the additional information after that analysis. It can therefore be populated directly with:

information <- getFisherInformation(
    designPlan,
    stage = 1:2,
    type = "stageWise"
)

For an effect-estimate conversion at analysis j, use:

information <- getFisherInformation(
    designPlan,
    stage = j,
    type = "cumulative"
)

The type field in every result enables getFutilityBounds() to detect incompatible use. The complete result can also be piped into getFutilityBounds(). In that case, its stage and situations fields are used to convert every applicable futility bound separately. With the default cumulative type, an omitted target scale means conversion to the effect-estimate scale:

designPlan |>
    getFisherInformation() |>
    getFutilityBounds()

Alternatively, pipe designPlan directly into getFutilityBounds(); the latter then calls this function internally with the information type required by the requested target scale. Cumulative information can also be piped into a conversion to the design-specific treatment-effect scale:

designPlan |>
    getFisherInformation(type = "cumulative") |>
    getFutilityBounds(targetScale = "treatmentEffect")

In this case, the information object's type, stages, and originating design plan are validated before the endpoint-specific transformation is applied. For two-group rates, the Farrington–Manning inversion uses the design plan's group sizes and null-restricted rates directly. For Count Data, the design and stages are reused without recalculating Fisher information, while the exact negative-binomial inversion evaluates its variance at each candidate rate ratio from the design-specific sample-size and exposure assumptions.

Value

A FisherInformation R6 object. Its public fields are information (the calculated numeric value, vector, or matrix), type, stage, and situations. The latter contains descriptive labels such as the corresponding alternatives, event probabilities, hazard ratios, or count-data rates where available. The originating design plan is stored privately for subsequent pipe-based conversion with getFutilityBounds().

Use as.numeric() to extract a plain numeric vector, as.matrix() to obtain a consistently arranged stage-by-situation matrix, and as.data.frame() to obtain a long-format data frame. Unsupported endpoint types are represented by NA_real_ in the information field.

See Also

getFutilityBounds() for converting futility bounds using the calculated information.

Examples

## Not run: 
designPlan <- getSampleSizeMeans(alternative = 0.4)
getFisherInformation(designPlan)

design <- getDesignGroupSequential(kMax = 3)
designPlan <- getPowerMeans(design,
    alternative = c(0.3, 0.4), maxNumberOfSubjects = 100
)
getFisherInformation(designPlan)
getFisherInformation(designPlan, stage = 2)
getFisherInformation(designPlan, stage = 1:3, type = "stageWise")

simulationResults <- getSimulationMeans(design,
    plannedSubjects = c(20, 40, 60), alternative = 0.4,
    maxNumberOfIterations = 10
)
getFisherInformation(simulationResults)

## End(Not run)

Description

This function converts futility bounds between different scales such as z-value, p-value, conditional power, predictive power, reverse conditional power, Wald effect estimate, and design-specific treatment effect.

Usage

getFutilityBounds(
  sourceValue,
  ...,
  sourceScale = c("zValue", "pValue", "conditionalPower", "condPowerAtObserved",
    "predictivePower", "reverseCondPower", "effectEstimate", "treatmentEffect"),
  targetScale = c("zValue", "pValue", "conditionalPower", "condPowerAtObserved",
    "predictivePower", "reverseCondPower", "effectEstimate", "treatmentEffect"),
  design = NULL,
  directionUpper = NA,
  theta = NA_real_,
  information = NA_real_,
  stage = NA_integer_,
  naAllowed = FALSE
)