Package 'TH'

Title: Educational Hypothesis Tests in R
Description: Provides educational implementations of one- and two-sample Z tests, Student and Welch t tests, a paired t test, an F test for two variances, and Pearson chi-square tests for goodness of fit, independence, and homogeneity. Functions validate mutually exclusive raw-data and summary-statistics interfaces, return structured htest-compatible results, and optionally display step-by-step graphical explanations.
Authors: Willian Silva Barros [aut, cre, cph]
Maintainer: Willian Silva Barros <[email protected]>
License: GPL (>= 3)
Version: 1.0.0
Built: 2026-10-06 10:59:59 UTC
Source: https://github.com/cran/TH

Help Index

F Test for Two Variances

Description

Performs an F test for comparing two population variances.

Usage

tf2(
  dadosX = NULL,
  dadosY = NULL,
  alfa = 0.05,
  Ha = 1,
  s2X = NULL,
  nX = NULL,
  s2Y = NULL,
  nY = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector for the first sample. Use NULL when summary statistics are supplied.
dadosY

Numeric vector for the second sample. Use NULL when summary statistics are supplied.
alfa

Significance level.
Ha

Alternative hypothesis: 1 or "two.sided" for a two-sided test; 2 or "greater" for variance of X greater than variance of Y.
s2X

Variance of the first sample.
nX

Size of the first sample.
s2Y

Variance of the second sample.
nY

Size of the second sample.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function accepts raw data or the sample variances and sample sizes.

Main assumptions:

  • independent samples;

  • normal populations;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(8, 12, 16, 20, 24, 28)
Y <- c(14, 15, 14, 15, 14, 15)
tf2(X, Y, alfa = 0.05, Ha = 2, plot = FALSE)

Chi-Square Goodness-of-Fit Test

Description

Compares observed frequencies with a specified categorical distribution.

Usage

tq2a(
  dadosX = NULL,
  p = NULL,
  FO = NULL,
  FE = NULL,
  alfa = 0.05,
  Ha = 2,
  r = 0,
  plot = TRUE
)

Arguments

dadosX

Vector containing the observed categories. Use NULL when frequencies are supplied.
p

Vector of positive expected weights or proportions. Used only when FE is not supplied.
FO

Vector of observed frequencies.
FE

Vector of expected frequencies.
alfa

Significance level.
Ha

Right-tailed alternative. Use 2 or "greater"; other values are rejected.
r

Number of restrictions due to parameters estimated from the data when calculating expected frequencies.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Input modes are mutually exclusive: use raw categories with p, FO with p, or FO with FE. Named p and FE vectors are aligned to named observed categories. The standard omnibus chi-square goodness-of-fit test has an upper-tail rejection region.

Main assumptions:

  • mutually exclusive categories;

  • independent observations;

  • adequately large expected frequencies;

Value

Invisibly returns an object of classes th_test and htest containing the statistic, degrees of freedom, p-value, critical value, decision, observed frequencies, and expected frequencies. When plot = TRUE, an educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

See Also

tq2i(), tq2h()

Examples

categories <- c(rep("A", 50), rep("B", 30), rep("C", 20))
tq2a(categories, p = c(1, 1, 1), alfa = 0.05, Ha = 2, r = 0, plot = FALSE)

Chi-Square Test of Homogeneity

Description

Compares categorical distributions across groups or populations.

Usage

tq2h(
  dadosX = NULL,
  dadosY = NULL,
  FO = NULL,
  alfa = 0.05,
  Ha = 2,
  r = 0,
  plot = TRUE
)

Arguments

dadosX

Vector identifying the groups or populations. Use NULL when a frequency table is supplied.
dadosY

Vector containing the response categories. Use NULL when a frequency table is supplied.
FO

Matrix of observed frequencies.
alfa

Significance level.
Ha

Right-tailed alternative. Use 2 or "greater"; other values are rejected.
r

Retained for backward compatibility. It must be zero; Pearson degrees of freedom are used without adjustment.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

The function accepts individual categorical observations or an observed frequency matrix. The standard omnibus chi-square homogeneity test has an upper-tail rejection region.

Main assumptions:

  • independent samples or groups;

  • mutually exclusive categories;

  • adequately large expected frequencies;

Value

Invisibly returns an object of classes th_test and htest containing the statistic, degrees of freedom, p-value, critical value, decision, observed frequencies, and expected frequencies. When plot = TRUE, an educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

See Also

tq2a(), tq2i()

Examples

FO <- matrix(c(30, 15, 5, 10, 25, 15, 20, 20, 10), nrow = 3, byrow = TRUE)
tq2h(NULL, NULL, FO = FO, alfa = 0.05, Ha = 2, r = 0, plot = FALSE)

Chi-Square Test of Independence

Description

Assesses association between two categorical variables.

Usage

tq2i(
  dadosX = NULL,
  dadosY = NULL,
  FO = NULL,
  alfa = 0.05,
  Ha = 2,
  r = 0,
  plot = TRUE
)

Arguments

dadosX

Vector for the first categorical variable. Use NULL when a frequency table is supplied.
dadosY

Vector for the second categorical variable. Use NULL when a frequency table is supplied.
FO

Matrix of observed frequencies.
alfa

Significance level.
Ha

Right-tailed alternative. Use 2 or "greater"; other values are rejected.
r

Retained for backward compatibility. It must be zero; Pearson degrees of freedom are used without adjustment.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

The function accepts two categorical variables recorded at the observation level or an observed contingency table. The standard omnibus chi-square test of independence has an upper-tail rejection region.

Main assumptions:

  • independent observations;

  • mutually exclusive categories;

  • adequately large expected frequencies;

Value

Invisibly returns an object of classes th_test and htest containing the statistic, degrees of freedom, p-value, critical value, decision, observed frequencies, and expected frequencies. When plot = TRUE, an educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

See Also

tq2a(), tq2h()

Examples

FO <- matrix(c(30, 10, 5, 10, 25, 20), nrow = 2, byrow = TRUE)
tq2i(NULL, NULL, FO = FO, alfa = 0.05, Ha = 2, r = 0, plot = FALSE)

One-Sample t Test

Description

Performs Student's t test for one population mean when the population variance is unknown.

Usage

tt1(
  dadosX = NULL,
  mp,
  alfa = 0.05,
  Ha = 1,
  unidade = NULL,
  media = NULL,
  s2 = NULL,
  n = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector containing the sample data. Use NULL when summary statistics are supplied.
mp

Population mean specified under the null hypothesis.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
unidade

Measurement unit displayed in the graph.
media

Sample mean used when dadosX = NULL.
s2

Sample variance used when dadosX = NULL.
n

Sample size used when dadosX = NULL.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function can be run using raw observations or the sample mean, sample variance, and sample size.

Main assumptions:

  • random sampling and independent observations;

  • approximately normal population, particularly for small samples;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(11, 12, 13, 12, 14, 13, 12, 15)
tt1(X, mp = 10, alfa = 0.05, Ha = 2, unidade = " units", plot = FALSE)

Two-Sample t Test with Unequal Variances

Description

Compares two independent population means without assuming equal population variances.

Usage

tt2d(
  dadosX = NULL,
  dadosY = NULL,
  alfa = 0.05,
  Ha = 1,
  mX = NULL,
  s2X = NULL,
  nX = NULL,
  mY = NULL,
  s2Y = NULL,
  nY = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector for the first sample. Use NULL when summary statistics are supplied.
dadosY

Numeric vector for the second sample. Use NULL when summary statistics are supplied.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
mX

Mean of the first sample.
s2X

Variance of the first sample.
nX

Size of the first sample.
mY

Mean of the second sample.
s2Y

Variance of the second sample.
nY

Size of the second sample.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function accepts raw data or summary statistics and uses Welch's standard error with Welch-Satterthwaite fractional degrees of freedom.

Main assumptions:

  • independent samples;

  • approximately normal populations;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(20, 21, 19, 22, 18, 20)
Y <- c(10, 15, 5, 20, 0, 10)
tt2d(X, Y, alfa = 0.05, Ha = 2, plot = FALSE)

Two-Sample t Test with Equal Variances

Description

Compares two independent population means under the assumption of equal population variances.

Usage

tt2i(
  dadosX = NULL,
  dadosY = NULL,
  alfa = 0.05,
  Ha = 1,
  mX = NULL,
  s2X = NULL,
  nX = NULL,
  mY = NULL,
  s2Y = NULL,
  nY = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector for the first sample. Use NULL when summary statistics are supplied.
dadosY

Numeric vector for the second sample. Use NULL when summary statistics are supplied.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
mX

Mean of the first sample.
s2X

Variance of the first sample.
nX

Size of the first sample.
mY

Mean of the second sample.
s2Y

Variance of the second sample.
nY

Size of the second sample.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function accepts raw data or summary statistics and uses the pooled variance of the two samples.

Main assumptions:

  • independent samples;

  • approximately normal populations;

  • equal population variances;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(18, 20, 19, 21, 22, 20)
Y <- c(14, 15, 16, 15, 14, 16)
tt2i(X, Y, alfa = 0.05, Ha = 1, plot = FALSE)

Paired t Test

Description

Performs a t test for two dependent or paired measurements.

Usage

tt2p(
  dadosX1 = NULL,
  dadosX2 = NULL,
  mpD = 0,
  alfa = 0.05,
  Ha = 1,
  unidade = NULL,
  mD = NULL,
  s2D = NULL,
  nD = NULL,
  plot = TRUE
)

Arguments

dadosX1

Numeric vector for the first condition.
dadosX2

Numeric vector for the second condition, in the corresponding paired order.
mpD

Population mean of the differences specified under the null hypothesis; the default is zero.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
unidade

Measurement unit displayed in the graph.
mD

Mean of the differences when the vectors are not supplied.
s2D

Variance of the differences when the vectors are not supplied.
nD

Number of pairs when the vectors are not supplied.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw paired data and summary statistics for the differences are mutually exclusive. In raw-data mode, the difference is calculated as dadosX2 - dadosX1.

Main assumptions:

  • correct pairing of the observations;

  • independence among pairs;

  • approximately normal distribution of the paired differences;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

before <- c(70, 72, 68, 75, 74, 71, 69, 73)
after <- c(66, 69, 65, 71, 70, 68, 66, 69)
tt2p(before, after, mpD = 0, alfa = 0.05, Ha = 3, unidade = " units", plot = FALSE)

One-Sample Z Test

Description

Performs a Z test for one population mean when the population variance is known.

Usage

tz1(
  dadosX = NULL,
  mp,
  vp,
  alfa = 0.05,
  Ha = 1,
  unidade = NULL,
  media = NULL,
  n = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector containing the sample data. Use NULL when summary statistics are supplied.
mp

Population mean specified under the null hypothesis.
vp

Known population variance.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
unidade

Measurement unit displayed in the graph.
media

Sample mean used when dadosX = NULL.
n

Sample size used when dadosX = NULL.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function accepts either raw observations or the sample mean and sample size. It produces a graphical representation of the main stages of the test.

Main assumptions:

  • random sampling and independent observations;

  • known population variance;

  • normal population or an adequately large sample;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(52, 49, 51, 50, 53, 54, 48, 52, 51, 50)
tz1(X, mp = 50, vp = 4, alfa = 0.05, Ha = 1, unidade = " units", plot = FALSE)

Two-Sample Z Test

Description

Performs a Z test for comparing two population means when both population variances are known.

Usage

tz2(
  dadosX = NULL,
  dadosY = NULL,
  vpX,
  vpY,
  alfa = 0.05,
  Ha = 1,
  mX = NULL,
  nX = NULL,
  mY = NULL,
  nY = NULL,
  plot = TRUE
)

Arguments

dadosX

Numeric vector for the first sample. Use NULL when summary statistics are supplied.
dadosY

Numeric vector for the second sample. Use NULL when summary statistics are supplied.
vpX

Known population variance for the first population.
vpY

Known population variance for the second population.
alfa

Significance level.
Ha

Alternative hypothesis. Use 1 or "two.sided", 2 or "greater", and 3 or "less".
mX

Mean of the first sample when dadosX = NULL.
nX

Size of the first sample when dadosX = NULL.
mY

Mean of the second sample when dadosY = NULL.
nY

Size of the second sample when dadosY = NULL.
plot

Logical. If TRUE (default), draw the educational graph; if FALSE, return the result without plotting.

Details

Raw-data and summary-statistics modes are mutually exclusive. The function accepts raw data or summary statistics for two samples and displays the hypothesis test graphically.

Main assumptions:

  • independent samples;

  • known population variances;

  • normal populations or adequately large samples;

Value

Invisibly returns an object of classes th_test and htest containing the test statistic, degrees of freedom when applicable, p-value, estimates, critical values, significance level, and decision. When plot = TRUE, the educational graph is produced as a side effect.

Author(s)

Willian Silva Barros

Examples

X <- c(15, 16, 14, 17, 15, 16, 14, 15)
Y <- c(11, 12, 13, 10, 12, 11, 13, 12)
tz2(X, Y, vpX = 4, vpY = 4, alfa = 0.05, Ha = 2, plot = FALSE)