One, Two, and Paired Samples Hypothesis Tests with Extended Options

Performs statistical hypothesis tests with extended functionality beyond standard implementations. Supports t-tests, Wilcoxon-Mann-Whitney tests, and Brunner-Munzel tests with additional alternatives such as equivalence and minimal effect testing.

Usage

simple_htest(
  x,
  ...,
  paired = FALSE,
  alternative = c("two.sided", "less", "greater", "equivalence", "minimal.effect"),
  mu = NULL,
  alpha = 0.05
)

# Default S3 method
simple_htest(
  x,
  y = NULL,
  test = c("t.test", "wilcox.test", "brunner_munzel"),
  paired = FALSE,
  alternative = c("two.sided", "less", "greater", "equivalence", "minimal.effect"),
  mu = NULL,
  alpha = 0.05,
  ...
)

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

Arguments

x

a (non-empty) numeric vector of data values.

...

further arguments to be passed to or from the underlying test functions.

paired

a logical indicating whether you want a paired t-test.

alternative

the alternative hypothesis: - "two.sided": different from mu (default) - "less": less than mu - "greater": greater than mu - "equivalence": between specified bounds - "minimal.effect": outside specified bounds

mu

a number or vector specifying the null hypothesis value(s): - For standard alternatives (two.sided, less, greater): a single value (default: 0 for t-test/wilcox.test, 0.5 for brunner_munzel) - For equivalence/minimal.effect: either a single value (symmetric bounds will be created) or a vector of two values representing the lower and upper bounds

alpha

alpha level (default = 0.05)

y

an optional (non-empty) numeric vector of data values.

test

a character string specifying the type of hypothesis test to use: - "t.test": Student's t-test (parametric, default) - "wilcox.test": Wilcoxon-Mann-Whitney test (non-parametric) - "brunner_munzel": Brunner-Munzel test (non-parametric)

You can specify just the initial letter (e.g., "t" for "t.test").

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

A list with class "htest" containing the following components:

statistic: the value of the test statistic.
parameter: the parameter(s) for the test statistic (e.g., degrees of freedom for t-tests).
p.value: the p-value for the test.
conf.int: a confidence interval appropriate to the specified alternative hypothesis.
estimate: the estimated effect (e.g., mean difference for t-tests, probability estimate for Brunner-Munzel).
null.value: the specified hypothesized value(s). For equivalence and minimal effect tests, this will be two values.
stderr: the standard error of the estimate (for t-tests).
alternative: a character string describing the alternative hypothesis.
method: a character string indicating what type of test was performed.
data.name: a character string giving the name(s) of the data.

Details

This function provides a unified interface to several common hypothesis tests with expanded alternative hypotheses, particularly for equivalence testing and minimal effect testing.

When alternative = "equivalence", the test evaluates whether the effect is contained within the bounds specified by mu. This corresponds to the alternative hypothesis that the true effect is between the specified bounds. The function performs two one-sided tests and returns the most conservative result (highest p-value).

When alternative = "minimal.effect", the test evaluates whether the effect is outside the bounds specified by mu. This corresponds to the alternative hypothesis that the true effect is either less than the lower bound or greater than the upper bound. The function performs two one-sided tests and returns the most significant result (lowest p-value).

For standard alternatives ("two.sided", "less", "greater"), the function behaves similarly to the underlying test functions with some additional standardization in the output format.

The interpretation of mu depends on the test used:

For t-test and wilcox.test: mu represents the difference in means/medians (default: 0)
For brunner_munzel: mu represents the probability that a randomly selected value from the first sample exceeds a randomly selected value from the second sample (default: 0.5)

If mu is a single value for equivalence or minimal effect alternatives, symmetric bounds will be created automatically:

For t-test and wilcox.test: bounds become c(mu, -mu)
For brunner_munzel: bounds become c(mu, abs(mu-1))

Purpose

Use this function when:

You need a unified interface for different types of hypothesis tests
You want to perform equivalence testing or minimal effect testing with non-parametric methods
You need more flexibility in hypothesis testing than provided by standard functions
You want to easily switch between parametric and non-parametric methods

Examples

# Example 1: Basic t-test with equivalence alternative
# Testing if the difference in mpg between automatic and manual transmission cars
# is equivalent within ±3 units
data(mtcars)
simple_htest(mpg ~ am, data = mtcars, alternative = "equivalence", mu = 3)
#> 
#> 	Welch Two Sample t-test
#> 
#> data:  mpg by am
#> t = -2.2072, df = 18.332, p-value = 0.9799
#> alternative hypothesis: equivalence
#> null values:
#> difference in means difference in means 
#>                  -3                   3 
#> 90 percent confidence interval:
#>  -10.576623  -3.913256
#> sample estimates:
#> mean of x mean of y 
#>  17.14737  24.39231 
#> 

# Example 2: Using a non-parametric test with minimal effect alternative
# Testing if the effect of transmission type on mpg is meaningfully large
# (either less than -2 or greater than 2)
simple_htest(mpg ~ am, data = mtcars,
             test = "wilcox",
             alternative = "minimal.effect",
             mu = c(-2, 2))
#> 
#> 	Wilcoxon rank sum test with continuity correction
#> 
#> data:  mpg by am
#> W = 63, p-value = 0.01063
#> alternative hypothesis: minimal.effect
#> null values:
#> location shift location shift 
#>             -2              2 
#> 90 percent confidence interval:
#>  -10.999924  -3.600056
#> 

# Example 3: Paired samples test
# Using the sleep dataset to test if drug has an effect on sleep
data(sleep)
with(sleep, simple_htest(x = extra[group == 1],
                        y = extra[group == 2],
                        paired = TRUE,
                        alternative = "greater"))
#> mu set to 0
#> 
#> 	Paired t-test
#> 
#> data:  x and y
#> t = -4.0621, df = 9, p-value = 0.9986
#> alternative hypothesis: true mean difference is greater than 0
#> 95 percent confidence interval:
#>  -2.293005       Inf
#> sample estimates:
#> mean difference 
#>           -1.58 
#> 

# Example 4: Brunner-Munzel test
# Testing if values in one group tend to exceed values in another
set.seed(123)
group1 <- rnorm(20, mean = 5, sd = 1)
group2 <- rnorm(20, mean = 6, sd = 2)
simple_htest(x = group1, y = group2,
             test = "brunner_munzel",
             alternative = "less")
#> mu set to 0.5
#> 
#> 	two-sample Brunner-Munzel test
#> 
#> data:  x and y
#> t = -1.6893, df = 26.328, p-value = 0.05148
#> alternative hypothesis: true relative effect is less than 0.5
#> 90 percent confidence interval:
#>  0.0000000 0.5014218
#> sample estimates:
#> p(X>Y) + .5*P(X=Y) 
#>              0.345 
#>