---
title: "Getting Started with the TH Package"
author: "Willian Silva Barros"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with the TH Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.width = 10,
  fig.height = 7
)
```

# Introduction

The **TH** package was developed to support the teaching and learning of hypothesis testing in R. Each function presents a graphical sequence containing the null and alternative hypotheses, significance level, reference distribution, critical values, rejection and non-rejection regions, calculated statistic, and statistical decision.

Version 1.0.0 preserves the educational graphical approach while correcting unsafe argument defaults, directional F-test logic, chi-square formulations, Welch degrees of freedom, input validation, graphical side effects, and inferential wording. Numeric `Ha` values remain supported for backward compatibility.

# Installation

```{r installation, eval=FALSE}
install.packages(
  "TH_1.0.0.tar.gz",
  repos = NULL,
  type = "source"
)
```

# Loading the package

```{r loading}
library(TH)
packageVersion("TH")
```

```{r package-help, eval=FALSE}
help(package = "TH")
```

# Available functions

| Function | Statistical procedure |
|---|---|
| `tz1()` | One-Sample Z Test |
| `tz2()` | Two-Sample Z Test |
| `tt1()` | One-Sample t Test |
| `tt2i()` | Two-Sample t Test with Equal Variances |
| `tt2d()` | Two-Sample t Test with Unequal Variances |
| `tt2p()` | Paired t Test |
| `tf2()` | F Test for Two Variances |
| `tq2a()` | Chi-Square Goodness-of-Fit Test |
| `tq2i()` | Chi-Square Test of Independence |
| `tq2h()` | Chi-Square Test of Homogeneity |

# Meaning of the `Ha` argument

For tests concerning means, `Ha = 1` selects a two-sided test, `Ha = 2` a right-tailed test, and `Ha = 3` a left-tailed test. The equivalent character values are `"two.sided"`, `"greater"`, and `"less"`. In `tf2()`, only two-sided and right-tailed alternatives are supported. The three chi-square procedures use only the standard upper-tail omnibus test, so `Ha` must be `2` or `"greater"`.

# Choosing a function

| Statistical situation | Function |
|---|---|
| One mean and known population variance | `tz1()` |
| Two means and known population variances | `tz2()` |
| One mean and unknown population variance | `tt1()` |
| Two independent means with equal variances | `tt2i()` |
| Two independent means with unequal variances | `tt2d()` |
| Two paired measurements | `tt2p()` |
| Two variances | `tf2()` |
| Observed versus expected frequencies | `tq2a()` |
| Association between two categorical variables | `tq2i()` |
| Homogeneity across groups or populations | `tq2h()` |

# Examples for all functions

## One-Sample Z Test

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

```{r example-tz1, fig.show="hold"}
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")
```
## Two-Sample Z Test

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

```{r example-tz2, fig.show="hide"}
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)
```
## One-Sample t Test

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

```{r example-tt1, fig.show="hide"}
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 Equal Variances

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

```{r example-tt2i, fig.show="hide"}
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)
```
## Two-Sample t Test with Unequal Variances

Compares two independent population means without assuming equal population variances.

```{r example-tt2d, fig.show="hide"}
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)
```
## Paired t Test

Performs a t test for two dependent or paired measurements.

```{r example-tt2p, fig.show="hide"}
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)
```
## F Test for Two Variances

Performs an F test for comparing two population variances.

```{r example-tf2, fig.show="hide"}
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

Compares observed frequencies with expected frequencies for mutually exclusive categories.

```{r example-tq2a, fig.show="hide"}
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 Independence

Assesses the association between two categorical variables.

```{r example-tq2i, fig.show="hide"}
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)
```
## Chi-Square Test of Homogeneity

Compares categorical distributions across groups or populations.

```{r example-tq2h, fig.show="hide"}
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)
```

# Interpreting the graphical output

Read the output in the following order:

1. identify the null and alternative hypotheses;
2. verify the significance level;
3. locate the critical value or critical values;
4. identify the rejection region;
5. locate the calculated test statistic;
6. record the decision to reject or not reject the null hypothesis;
7. interpret the decision in the context of the problem.

Failure to reject the null hypothesis does not prove that it is true. It indicates that the data did not provide sufficient evidence to reject it at the selected significance level.

# Assumptions and limitations

The appropriate test must be selected according to the sampling design, independence of observations, distributional assumptions, knowledge of population variances, equality of variances when required, and adequacy of expected frequencies in chi-square procedures.

Version 1.0.0 is an educational implementation with validated inputs, executable examples, automated regression tests, structured invisible results, and optional graphical output. Raw-data and summary-statistics modes are mutually exclusive. Users remain responsible for checking study design and statistical assumptions.

# Help and citation

```{r help-citation, eval=FALSE}
?tz1
citation("TH")
browseVignettes("TH")
```

# Author

**Willian Silva Barros**  
Federal University of Pelotas  
Email: `willian.barros@ufpel.edu.br`

# Session information

```{r session-information}
sessionInfo()
```