designSaviLogrank: Designs a Safe Anytime-Valid Logrank Test Experiment
In safestats: Safe Anytime-Valid Inference

designSafeLogrank

R Documentation

Designs a Safe Anytime-Valid Logrank Test Experiment

Description

A designed experiment requires (1) an anticipated number of events nEvents, or even better nPlan, the number of participants to be recruited in the study, and (2) the parameter of the savi test, i.e., thetaS. Provided with a clinically relevant minimal hazard ratio hrMin, this function outputs thetaS = hrMin as the savi test defining parameter in accordance to the GROW criterion. If a tolerable type II error beta is provided then nEvents can be sampled. The sampled nEvents is then the smallest nEvents for which hrMin is found with power of at least 1 - beta under optional stopping. If exact equal FALSE, then the computations exploit the local asymptotic normal approximation to sampling distribution of the logrank test derived by Schoenfeld (1981).

Usage

designSaviLogrank(
  hrMin = NULL,
  power = NULL,
  nEvents = NULL,
  alpha = 0.05,
  h0 = 1,
  alternative = c("twoSided", "greater", "less"),
  m0 = 50000L,
  m1 = 50000L,
  testType = c("exactLogrank", "gaussianLogrank"),
  ratio = 1,
  exact = TRUE,
  parameter = NULL,
  eType = c("mom", "eGauss", "imom", "eCauchy", "grow"),
  wantSamplePaths = TRUE,
  groupSizePerTimeFunction = returnOne,
  pb = TRUE,
  seed = NULL,
  nSim = 1000L,
  nBoot = nSim,
  beta = NULL,
  relevanceTest = FALSE,
  relevanceSize = NULL,
  wantEValuesAtNMax = NULL,
  wantSimData = FALSE,
  ...
)

Arguments

`hrMin`	numeric that defines the minimal relevant hazard ratio, the smallest hazard ratio that we want to detect.
`beta`	numerical in (0,1). Old parameter now replaced by the power parameter
`nEvents`	numeric > 0, targetted number of events.
`alpha`	numeric in (0, 1) that specifies the tolerable type I error and the null rejection rule e >= 1/alpha.
`h0`	numeric > 0, represents the null hypothesis, default h0=1.
`alternative`	a character string specifying the alternative hypothesis, which must be one of "twoSided" (default),"greater" or "less". The alternative is pitted against the null hypothesis of equality of the survival distributions. More specifically, let lambda1 be the hazard rate of group 1 (i.e., placebo), and lambda2 the hazard ratio of group 2 (i.e., treatment), then the null hypothesis states that the hazard ratio theta = lambda2/lambda1 = 1. If alternative = "less", the null hypothesis is compared to theta < 1, thus, lambda2 < lambda1, that is, the hazard of group 2 (i.e., treatment) is less than that of group 1 (i.e., placebo), hence, the treatment is beneficial. If alternative = "greater", then the null hypothesis is compared to theta > 1, thus, lambda2 > lambda1, hence, harm.
`m0`	Number of subjects in the control group 0/1 at the beginning of the trial, i.e., `nPlan[1]`.
`m1`	Number of subjects in the treatment group 1/2 at the beginning of the trial, i.e., `nPlan[2]`.
`testType`	either one of "oneSample", "paired", "twoSample".
`ratio`	numeric > 0 representing the randomisation ratio of condition 2 (Treatment) over condition 1 (Placebo), thus, m1/m0. Note that m1 and m0 are not used to specify ratio. Ratio is only used when `zApprox=TRUE`, which ignores m1 and m0.
`exact`	a logical indicating whether the design should be based on the exact savi logrank test based on the hypergeometric likelihood. Default is `TRUE`, if `FALSE` then the design is based on a savi z-test.
`parameter`	Numeric > 0, represents the savi tests defining thetaS. Default NULL so it's decided by the algorithm, typically, this equals hrMin, which corresponds to the GROW choice.
`eType`	character one of "mom", "grow", "eGauss", and "eCauchy". "mom" is default and uses a non-local moment prior with bump(s) at meanDiffMin, "grow" uses point prior(s) at meanDiffMin, "eGauss" a zero-centred normal prior, "eCauchy" a zero centred Cauchy prior.
`wantSamplePaths`	logical, if `TRUE` then also outputs the sample paths.
`groupSizePerTimeFunction`	A function without parameters and integer output. This function provides the number of events at each time step. For instance, if `rpois(1, 7)` leads to a random number of events at each time step.
`pb`	logical, if `TRUE`, then show progress bar.
`seed`	integer, seed number.
`nSim`	integer > 0, the number of simulations needed to compute power or the number of events for the exact savi logrank test under continuous monitoring
`nBoot`	integer > 0 representing the number of bootstrap samples to assess the accuracy of the approximation of power or nEvents for the exact savi logrank test under continuous monitoring
`...`	further arguments to be passed to or from methods.
`power`	numeric in (0, 1) that specifies the desired power, that is, the targetted chance to stop for the alternative over the null hypothesis, when the alternative holds true. Note that prior to version 0.8.8 power <- 1-beta. This overrides the "beta" argument
`relevanceTest`	logical, if `TRUE` then impose rule to stop for minimal efficiency if e <= alphaRelevance. Default `FALSE`.
`relevanceSize`	numeric, the minimal clinical relevant standardised mean difference that we do not want to miss under the alternative. Default relevanceSize=NULL implies relevanceSize=abs(meanDiffMin)
`wantEValuesAtNMax`	logical. If `TRUE` then compute eValues at nMax. Default `FALSE`.
`wantSimData`	logical. If `TRUE`, then output the simulated data.

Value

Returns a saviDesign object that includes:

nEvents: the anticipated number of events, either (1) specified by the user, or (2) computed based on beta and thetaMin.
parameter: the parameter that defines the savi test. Here log(thetaS).
esMin: the minimally clinically relevant hazard ratio specified by the user.
alpha: the tolerable type I error provided by the user.
beta: the tolerable type II error provided by the user.
alternative: any of "twoSided", "greater", "less" provided by the user.
testType: "logrank".
ratio: default is 1. It defines the ratio between the planned randomisation of condition 2 over condition 1.
pilot: FALSE to indicate that the design is not a pilot study.
call: the expression with which this function is called.

References

Grünwald, P. D., de Heide, R., & Koolen, W. (2024). Safe testing. Journal of the Royal Statistical Society. Series B (Methodological), 86(5), 1091-1128. (With discussions), https://doi.org/10.1093/jrsssb/qkae011. ter Schure, J., Pérez-Ortiz, M. F., Ly, A., & Grünwald, P. D. (2024). The Safe Logrank Test: Error control under continuous monitoring with unlimited horizon. The New England Journal of Statistics in Data Science, 2(2), 190-214, https://doi.org/10.51387/24-NEJSDS65. Schoenfeld, D. (1981). The asymptotic properties of nonparametric tests for comparing survival distributions. Biometrika, 68(1), 316-319, https://doi.org/10.2307/2335833.

Examples

designSaviLogrank(hrMin=0.7)
designSaviLogrank(hrMin=0.7, exact=FALSE)
designSaviLogrank(hrMin=0.7, beta=0.3, nSim=10)
designSaviLogrank(hrMin=0.7, nEvents=190, nSim=10)

safestats documentation built on Sept. 6, 2026, 1:06 a.m.