Helper Functions for Working with 'htest' Objects

A collection of utility functions designed to help interpret, display, and standardize information from objects of class 'htest' (hypothesis test results). These functions make it easier to extract, format, and report statistical results from various test functions in R.

Usage

df_htest(htest, test_statistics = TRUE, show_ci = TRUE, extract_names = TRUE)

describe_htest(htest, alpha = NULL, digits = 3)

Arguments

htest: An S3 object of class 'htest', such as (but not limited to) output from t.test(), cor.test(), wilcox.test(), or TOSTER functions converted with as_htest().
test_statistics: A logical variable indicating whether to display the test statistics in the output (default = TRUE).
show_ci: A logical variable indicating whether to display the confidence interval in the output (default = TRUE).
extract_names: A logical variable indicating whether to take the names from the S3 object (i.e., statistic for t.test() would be "t") (default = TRUE).
alpha: The significance level to use for determining statistical significance. If NULL (default), it will be extracted from the confidence interval of the htest object or default to 0.05.
digits: Integer indicating the number of decimal places to display in the output (default = 3).

Value

df_htest(): Returns a data frame containing the formatted test information.
describe_htest(): Returns a character string with a formatted description of the test results.

Details

The package provides two main helper functions:

df_htest(): Converts an 'htest' object to a data frame with standardized columns, making it easier to combine multiple test results or export them for further analysis.
describe_htest(): Generates a formatted text description of the test results, following APA style guidelines and providing a complete statistical report with test statistics, p-values, effect sizes, and confidence intervals.

These functions work with standard R hypothesis tests (e.g., t.test(), wilcox.test(), cor.test()) as well as TOSTER-specific tests that have been converted to 'htest' format using the as_htest() function.

Examples

# Example 1: Working with a standard t-test
t_result <- t.test(extra ~ group, data = sleep)

# Convert to data frame
df_htest(t_result)
#>                    method         t       df    p.value mean difference
#> 1 Welch Two Sample t-test -1.860813 17.77647 0.07939414           -1.58
#>         SE  lower.ci  upper.ci conf.level alternative null
#> 1 0.849091 -3.365483 0.2054832       0.95   two.sided    0

# Generate formatted description
describe_htest(t_result)
#> [1] "The Welch Two Sample t-test is not statistically significant (t(17.776) = -1.86, p = 0.079, mean in group 1 = 0.75, mean in group 2 = 2.33, 95% C.I.[-3.37, 0.205]) at a 0.05 alpha-level. The null hypothesis cannot be rejected. At the desired error rate, it cannot be stated that the true difference in means between group 1 and group 2 is not equal to 0."

# Example 2: Working with a TOST result
tost_result <- t_TOST(extra ~ group, data = sleep, eqb = 1)
htest_conv <- as_htest(tost_result)
describe_htest(htest_conv)
#> [1] "The Welch Two Sample t-test is not statistically significant (t(17.776) = -0.683, p = 0.748, mean difference = -1.58, 90% C.I.[-3.05, -0.107]) at a 0.05 alpha-level. The null hypothesis cannot be rejected. At the desired error rate, it cannot be stated that the true mean difference is between -1 and 1."

# Example 3: Customizing output format
df_htest(t_result, test_statistics = TRUE, show_ci = FALSE)
#>                    method         t       df    p.value mean difference
#> 1 Welch Two Sample t-test -1.860813 17.77647 0.07939414           -1.58
#>         SE alternative null
#> 1 0.849091   two.sided    0
describe_htest(t_result, alpha = 0.01, digits = 2)
#> [1] "The Welch Two Sample t-test is not statistically significant (t(17.776) = -1.86, p = 0.08, mean in group 1 = 0.75, mean in group 2 = 2.33, 95% C.I.[-3.4, 0.21]) at a 0.01 alpha-level. The null hypothesis cannot be rejected. At the desired error rate, it cannot be stated that the true difference in means between group 1 and group 2 is not equal to 0."

# Example 4: Working with correlation tests
cor_result <- cor.test(mtcars$mpg, mtcars$wt)
df_htest(cor_result)
#>                                 method         t df      p.value        cor
#> 1 Pearson's product-moment correlation -9.559044 30 1.293959e-10 -0.8676594
#>     lower.ci   upper.ci conf.level alternative null
#> 1 -0.9338264 -0.7440872       0.95   two.sided    0
describe_htest(cor_result)
#> [1] "The Pearson's product-moment correlation is statistically significant (t(30) = -9.56, p < 0.001, cor = -0.868, 95% C.I.[-0.934, -0.744]) at a 0.05 alpha-level. The null hypothesis can be rejected. At the desired error rate, it can be stated that the true correlation is not equal to 0."