rpact: Confirmatory Adaptive Clinical Trial Design and Analysis


getAnalysisResults {rpact}R Documentation

Get Analysis Results

Description

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

Usage

getAnalysisResults(
  design,
  dataInput,
  ...,
  directionUpper = TRUE,
  thetaH0 = NA_real_,
  nPlanned = NA_real_,
  allocationRatioPlanned = 1,
  stage = NA_integer_
)

Arguments

design

The trial design.

dataInput

The summary data used for calculating the test results. This is either an element of DatasetMeans, of DatasetRates, or of DatasetSurvival and should be created with the function getDataset. For more information see getDataset.

...

Further arguments to be passed to methods (cf. separate functions in "See Also" below), e.g.,

thetaH1 and assumedStDev or pi1, pi2

The assumed effect size or assumed rates to calculate the conditional power. Depending on the type of dataset, either thetaH1 (means and survival) or pi1, pi2 (rates) can be specified. For testing means, an assumed standard deviation can be specified, default is 1.

normalApproximation

The type of computation of the p-values. Default is FALSE for testing means (i.e., the t test is used) and TRUE for testing rates and the hazard ratio. For testing rates, if normalApproximation = FALSE is specified, the binomial test (one sample) or the exact test of Fisher (two samples) is used for calculating the p-values. In the survival setting, normalApproximation = FALSE has no effect.

equalVariances

The type of t test. For testing means in two treatment groups, either the t test assuming that the variances are equal or the t test without assuming this, i.e., the test of Welch-Satterthwaite is calculated, default is TRUE.

iterations

Iterations for simulating the power for Fisher's combination test. If the power for more than one remaining stages is to be determined for Fisher's combination test, it is estimated via simulation with specified
iterations, the default is 1000.

seed

Seed for simulating the power for Fisher's combination test. See above, default is a random seed.

intersectionTest

Defines the multiple test for the intersection hypotheses in the closed system of hypotheses when testing multiple treatment arms. Five options are available: "Dunnett", "Bonferroni", "Simes", "Sidak", and "Hierarchical", default is "Dunnett".

varianceOption

Defines the way to calculate the variance in multiple treatment arms (> 2) for testing means. Three options are available: "overallPooled", "pairwisePooled", and "notPooled", default is "overallPooled".

thetaH1 and assumedStDevs or piTreatments, piControl

The assumed effect size or assumed rates to calculate the conditional power in multi-arm trials. You can specify a value or a vector with elements referring to the treatment arms.

directionUpper

Specifies the direction of the alternative, only applicable for one-sided testing; default is TRUE which means that larger values of the test statistics yield smaller p-values.

thetaH0

The null hypothesis value, default is 0 for the normal and the binary case (testing means and rates, respectively), it is 1 for the survival case (testing the hazard ratio).

For non-inferiority designs, thetaH0 is the non-inferiority bound. That is, in case of (one-sided) testing of

  • means: a value != 0 (or a value != 1 for testing the mean ratio) can be specified.

  • rates: a value != 0 (or a value != 1 for testing the risk ratio pi1 / pi2) can be specified.

  • survival data: a bound for testing H0: hazard ratio = thetaH0 != 1 can be specified.

For testing a rate in one sample, a value thetaH0 in (0, 1) has to be specified for defining the null hypothesis H0: pi = thetaH0.

nPlanned

The additional (i.e., "new" and not cumulative) sample size planned for each of the subsequent stages. The argument must be a vector with length equal to the number of remaining stages and contain the combined sample size from both treatment groups if two groups are considered. For survival outcomes, it should contain the planned number of additional events. For multi-arm designs, it is the per-comparison (combined) sample size.

allocationRatioPlanned

The planned allocation ratio n1 / n2 for a two treatment groups design, default is 1. For multi-arm designs, it is the allocation ratio relating the active arm(s) to the control.

stage

The stage number (optional). Default: total number of existing stages in the data input.

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) 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 only if effect size and sample size is specified. 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 designs.

Value

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

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.

Note on the dependency of mnormt

If intersectionTest = "Dunnett" or the design is a conditional Dunnett design and the dataset is a multi-arm dataset, rpact uses the R package mnormt to calculate the analysis results.

See Also

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

Examples


# Example 1
# 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
# 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),
# and repeated 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)
plot(x, thetaRange = c(0,0.8))

design <- getDesignConditionalDunnett(secondStageConditioning = FALSE)
y <- getAnalysisResults(design, dataInput = data, 
    nPlanned = c(40), thetaH1 = c(0.5, NA, 0.8), assumedStDevs = 1.2,  stage = 1)  
summary(y)
plot(y, thetaRange = c(0,0.4))



[Package rpact version 3.0.2 Index | www.rpact.org]