saviZTest: Safe Anytime-Valid Z-Test

In safestats: Safe Anytime-Valid Inference

Safe Anytime-Valid Z-Test

Description

Savi one- and two-sample Z-tests. Takes as input vector(s) of data and a designObj from designSaviZ. The function is modelled after t.test().

Usage

saviZTest(x, ...)

## Default S3 method:
saviZTest(
  x,
  y = NULL,
  paired = FALSE,
  designObj = NULL,
  ciValue = NULL,
  maxRoot = 10,
  sequential = NULL,
  ...
)

## S3 method for class 'formula'
saviZTest(formula, data, subset, na.action, ...)

savi.z.test(x, y = NULL, paired = FALSE, designObj = NULL, ...)

Arguments

x	a (non-empty) numeric vector of data values.
...	further arguments to be passed to or from methods.
y	an optional (non-empty) numeric vector of data values.
paired	a logical indicating whether you want the paired Z-test.
designObj	an object obtained from designSaviZ().
ciValue	numeric representing the confidence level. Default ciValue=NULL yields ciValue = 1 - alpha
maxRoot	Used to bound the candidate set of width of the confidence interval, whenever eType="eCauchy"
sequential	a logical indicating whether a sequential analysis should be performed.
formula	a formula of the form lhs ~ rhs where lhs is a numeric variable giving the data values and rhs either 1 for a one-sample or paired test or a factor with two levels giving the corresponding groups. If lhs is of class "Pair" and rhs is 1, a paired test is done
data	an optional matrix or data frame (or similar: see model.frame()) containing the variables in the formula. By default the variables are taken from environment(formula).
subset	an optional vector specifying a subset of observations to be used.
na.action	a function which indicates what should happen when the data contain NAs. Defaults to getOption("na.action").

Value

Returns an object of class 'saviTest'. An object of class 'saviTest' is a list containing at least the following components:

statistic

the value of the test statistic. Here the z-statistic.

n

The realised sample size(s).

eValue

the e-value of the savi test.

confSeq

a savi confidence interval for the mean (difference).

estimate

the estimated means or mean (difference) depending on whether it was a one-sample test or a two-sample test.

dataName

a character string giving the name(s) of the data.

designObj

an object of class "saviDesign" described in designSaviZ().

call

the expression with which this function is called.

Functions

• safeZTest(): Deprecated version of saviZTest

• safeZTest(default): Deprecated version of saviZTest.default

• safe.z.test(): Deprecated version of saviZTest

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. Ly, A, Boehm, Grünwald, P. D., Ramdas, A., & van Ravenzwaaij, D. (2024). Safe Anytime-Valid Inference: Practical maximally flexible sampling designs for experiments based on e-values. PsyArXiv Preprint, https://doi.org/10.31234/osf.io/h5vae.

Examples

## Examples with simulated data ----
set.seed(1)
x <- rnorm(30, mean=0)
y <- rnorm(40, mean=0)

# Because no designObj is specified, a default
# designObj is used with meanDiffMin = 1/2 and sigma=1,
# which can be thought of as a medium effect size
# according to Cohen.

res <- saviZTest(x=x, y=y)

# By default sequential=TRUE, because length(x) <= 200.
# This allows us to visualise the e-value as a function of
# the n1 and associated n2, where the ratio of sample sizes,
# ratio=n2/n1 is maintained. Here the e-value at n1=6 uses data
# x[1:6] and y[1:ceil(ratio*6)]
plot(res)

# Plots the confidence sequence
plot(res, wantConfSeqPlot=TRUE)

# See ?designSaviZ for more info
# This designObj also allows for
# evidence quantification that the
# mean difference is minimal clinically
# relevant, here, larger than
# relevanceSize=meanDiffMin
designObj <- designSaviZ(meanDiffMin=0.7, alpha=0.05,
                         alternative="twoSided",
                         testType="twoSample",
                         relevanceTest=TRUE)

res <- saviZTest(x=x, y=y, designObj=designObj)

plot(res)

# Note that the e-value against relevance falls below alphaRelevance
# We can reject the hypothesis that the effect is relevantly larger,
# larger than designObj$relevanceTestSim$parameter after a sample size of
min(which(res$eRelevanceVec <= designObj$relevanceTestSim$alpha))

set.seed(2)
x <- rnorm(30, mean=0.6)
y <- rnorm(40, mean=0)

res <- saviZTest(x, y, designObj=designObj)

plot(res)
# We could have stopped sampling after
min(which(res$eValueVec >= 1/designObj$alpha))
# the yellow curve crosses 1/alpha sooner,
# but we do **not** compare eRelevance >= 1/alpha, only eRelevance <= alphaRelevance

## Classical example: Student's sleep data -----
plot(extra ~ group, data = sleep)

designObj <- designSaviZ(meanDiffMin=0.6, sigma=2,
                         testType="twoSample")

## Traditional interface
with(sleep, saviZTest(extra[group == 1], extra[group == 2],
                      designObj=designObj))

## Formula interface
saviZTest(extra ~ group, data = sleep, designObj=designObj)

## Formula interface to one-sample test
designObj1 <- designSaviZ(meanDiffMin=0.6,
                          testType="oneSample",
                          sigma=2)

saviZTest(extra ~ 1, data = sleep, designObj=designObj1)

## Formula interface to paired test
## The sleep data are actually paired, so could have been in wide format:
designObjPaired <- designSaviZ(meanDiffMin=0.6,
                               testType="paired",
                               sigma=1.4)
sleep2 <- reshape(sleep, direction = "wide",
                  idvar = "ID", timevar = "group")
saviZTest(Pair(extra.1, extra.2) ~ 1, data = sleep2,
          designObj=designObjPaired)

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