saviTTest: Safe Anytime-Valid Student's T-Test.

In safestats: Safe Anytime-Valid Inference

Safe Anytime-Valid Student's T-Test.

Description

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

Usage

saviTTest(x, ...)

## Default S3 method:
saviTTest(
  x,
  y = NULL,
  designObj = NULL,
  paired = FALSE,
  varEqual = TRUE,
  ciValue = NULL,
  maxRoot = 10,
  sequential = NULL,
  tDensity = FALSE,
  nuMin = 2,
  wantCi = TRUE,
  ...
)

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

savi.t.test(
  x,
  y = NULL,
  paired = FALSE,
  designObj = NULL,
  varEqual = TRUE,
  ciValue = NULL,
  ...
)

Arguments

tDensity	Uses the the representation of the savi T-test as the likelihood ratio of t densities.
paired	a logical, if TRUE then pair the data.
...	further arguments to be passed to or from methods.
x	a (non-empty) numeric vector of data values.
y	an optional (non-empty) numeric vector of data values.
designObj	an object obtained from designSaviT.
varEqual	a logical variable indicating whether to treat the two variances as being equal. Default varEqual=TRUE.
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/
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")..
nuMin	numeric > 0, the minimum degrees of freedom under which the results are trivial, thus, 1.
wantCi	default TRUE

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 t-statistic.

n

The realised sample size(s).

eValue

the realised e-value from 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.

stderr

the standard error of the mean (difference), used as denominator in the t-statistic formula.

dataName

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

designObj

an object of class "saviDesign" obtained from designSaviT().

call

the expression with which this function is called.

Functions

• safeTTestStat(): Deprecated version of saviTTestStat

• safeTTestStatNEffNu(): Deprecated version of saviTTestStatNEffNu #nu >0 degrees of freedom

• safeTTestStatNEffNuMom(): Deprecated version of saviTTestStatNEffNuMom

• safeTTestStatTDensity(): Deprecated version of saviTTestStatTDensity

• safeTTest(): Deprecated version of saviTTest

• safeTTest.default(): Deprecated version of saviTTest.default

• safeTTest.formula(): Deprecated version of saviTTest.formula

• safe.t.test(): Deprecated version of savi.t.test

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. Pérez-Ortiz, M. F., Lardy, T., de Heide, R., & Grünwald, P. D. (2024). E-statistics, group invariance and anytime valid testing. The Annals of Statistics, 52(4), 1410-1432, http://dx.doi.org/10.1214/24-AOS2394. Wang, H., & Ramdas, A. (in press). Anytime-valid t-tests and confidence sequences for Gaussian means with unknown variance. Sequential Analysis, https://doi.org/10.48550/arXiv.2310.03722.

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 deltaMin = 1/2,
# which can be thought of as a medium effect size
# according to Cohen.

res <- saviTTest(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 ?designSaviT for more info
# This designObj also allows for
# evidence quantification that the
# mean difference is minimal clinically
# relevant, here, larger than
# relevanceSize=meanDiffMin
designObj <- designSaviT(deltaMin=0.7, alpha=0.05,
                         alternative="twoSided",
                         testType="twoSample",
                         relevanceTest=TRUE)

res <- saviTTest(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 large,
# 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 <- saviTTest(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 <- designSaviT(deltaMin=0.6, testType="twoSample")

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

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

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

saviTTest(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 <- designSaviT(deltaMin=0.6,
                               testType="paired",
                               sigma=1.4)
sleep2 <- reshape(sleep, direction = "wide",
                  idvar = "ID", timevar = "group")
saviTTest(Pair(extra.1, extra.2) ~ 1, data = sleep2,
          designObj=designObjPaired)

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