---
title: "Test and effect size details"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 4
vignette: >
  %\VignetteIndexEntry{Test and effect size details}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label = "setup",
#| include = FALSE
source("setup.R")
```

## Introduction

This article describes the data that `{statsExpressions}` functions expect, and
summarizes, for each function, the statistical tests carried out, the effect
sizes returned, and the underlying functions used to compute them.

Abbreviations used: CI = Confidence Interval

## Data requirements

The one-sample, group-comparison, correlation, and centrality functions expect
**long (tidy) data** — one row per observation. Contingency-table functions also
accept a `counts` column for aggregated frequencies; `meta_analysis()` instead
requires `estimate` and `std.error` columns, with one row per study.
A few additional requirements are worth noting:

- **Within-subjects (repeated measures) designs**: The data must contain exactly
  *one* observation per subject per condition (a complete, balanced block design).
  If you have multiple trials per subject-condition cell, aggregate them first
  (e.g., by taking the mean) before passing the data.
  You can verify this with `table(data$subject, data$condition)` — every cell
  should equal `1`.

- **`subject.id` argument**: For within-subjects designs, always specify
  `subject.id` explicitly. If omitted, the function pairs observations by
  row order within each condition, so any data that is not already sorted
  identically within every condition level can produce silently incorrect
  paired tests — even with exactly two conditions and no missing values.

- **Missing data**: Missing values are removed internally. For within-subjects
  designs, any subject who has `NA` in *any* condition, or lacks a row in a
  condition, is removed entirely by `complete_subjects()`, ensuring a balanced
  design is maintained. For between-subjects designs, only
  the rows with `NA` are removed, unless `subject.id` is also supplied, in
  which case all rows of a subject with an `NA` are removed.

## Summary of functionality

```{r child="../man/rmd-fragments/functionality.Rmd"}
```

## Summary of tests and effect sizes

To learn how an argument is resolved, or to browse the source code, consult the
underlying function listed in these tables. For example, for the
between-subjects one-way ANOVA, run `?stats::oneway.test` in your R console.

### `centrality_description()`

```{r child="../man/rmd-fragments/centrality_description.Rmd"}
```

### `oneway_anova()`

```{r child="../man/rmd-fragments/oneway_anova.Rmd"}
```

### `two_sample_test()`

```{r child="../man/rmd-fragments/two_sample_test.Rmd"}
```

### `one_sample_test()`

```{r child="../man/rmd-fragments/one_sample_test.Rmd"}
```

### `corr_test()`

```{r child="../man/rmd-fragments/corr_test.Rmd"}
```

### `contingency_table()`

```{r child="../man/rmd-fragments/contingency_table.Rmd"}
```

### `pairwise_comparisons()`

```{r child="../man/rmd-fragments/pairwise_comparisons.Rmd"}
```

### `pairwise_contingency_table()`

```{r child="../man/rmd-fragments/pairwise_contingency_table.Rmd"}
```

### `meta_analysis()`

```{r child="../man/rmd-fragments/meta_analysis.Rmd"}
```

## Effect size interpretation

See `{effectsize}`'s interpretation functions to check different rules/conventions
to interpret effect sizes:

<https://easystats.github.io/effectsize/reference/index.html#interpretation>

## References

- For parametric and non-parametric effect sizes:
  <https://easystats.github.io/effectsize/articles/>

- For robust effect sizes:
  <https://CRAN.R-project.org/package=WRS2/vignettes/WRS2.pdf>

- For Bayesian posterior estimates:
  <https://easystats.github.io/bayestestR/articles/bayes_factors.html>

## Suggestions

If you find any bugs or have any suggestions/remarks, please file an issue on GitHub:
<https://github.com/IndrajeetPatil/statsExpressions/issues>

## Citation

```{r citation, echo = FALSE, comment = ""}
citation("statsExpressions")
```