---
title: "Introduction to statAPA"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to statAPA}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

**statAPA** produces publication-ready statistical tables formatted according
to the 7th edition of the American Psychological Association (APA) style
guidelines. All functions return an invisible list so results can be stored,
piped into `apa_to_flextable()` for Word export, or left to print to the
console via `message()`.

```{r load}
library(statAPA)
```

---

## 1. Descriptive statistics

```{r descriptives}
result <- apa_descriptives(
  mtcars,
  vars  = c("mpg", "wt", "hp"),
  group = "cyl"
)
```

The returned list has `$descriptives_df` (the formatted data frame) and
`$note` (the APA table note).

---

## 2. t-Test

```{r ttest}
# Two-sample Welch t-test: mpg by transmission type
auto   <- mtcars$mpg[mtcars$am == 0]
manual <- mtcars$mpg[mtcars$am == 1]

res <- apa_t_test(auto, manual, output = "console")
```

---

## 3. One-way Analysis of Variance (ANOVA)

```{r anova}
mtcars2       <- mtcars
mtcars2$cyl   <- factor(mtcars2$cyl)

res <- apa_anova(lm(mpg ~ cyl, data = mtcars2), es = "partial_eta2")
```

---

## 4. Two-Way Analysis of Variance (ANOVA) with simple effects

```{r twoway}
mtcars2$gear <- factor(mtcars2$gear)

res <- apa_twoway_anova(
  mpg ~ cyl * gear,
  data    = mtcars2,
  factorA = "cyl",
  factorB = "gear",
  simple_effects = TRUE
)
```

---

## 5. Analysis of Covariance (ANCOVA) with adjusted means

```{r ancova}
res <- apa_ancova(
  formula   = mpg ~ cyl + wt,
  data      = mtcars2,
  covariate = "wt",
  focal     = "cyl",
  es        = "partial_eta2"
)
```

The second table shows covariate-adjusted marginal means for each level of
`cyl`, evaluated at the mean of `wt`.

---

## 6. Multivariate Analysis of Variance (MANOVA)

```{r manova}
res <- apa_manova(
  cbind(Sepal.Length, Petal.Length) ~ Species,
  data = iris
)
```

All four multivariate test statistics are reported: Pillai's trace, Wilks'
lambda, Hotelling-Lawley trace, and Roy's largest root.

---

## 7. Post-hoc pairwise comparisons

```{r posthoc}
fit <- aov(mpg ~ cyl, data = mtcars2)
res <- apa_posthoc(fit, by = "cyl", adjust = "tukey")
```

---

## 8. Chi-square test

```{r chisq}
# Independence test
m <- matrix(c(30, 10, 20, 40), nrow = 2,
            dimnames = list(c("Group A", "Group B"),
                            c("Yes",    "No")))
res <- apa_chisq(m)
```

---

## 9. Proportion test with risk difference, risk ratio, and odds ratio

```{r proptest}
res <- apa_prop_test(x = c(30, 20), n = c(50, 50), output = "console")
```

---

## 10. Regression table

```{r regression}
fit <- lm(mpg ~ wt + hp + factor(cyl), data = mtcars)
res <- apa_table(fit)
```

---

## 11. Robust regression (Heteroscedasticity-Consistent standard errors)

```{r robust}
res <- apa_robust(fit, type = "HC3")
```

---

## 12. Heteroscedasticity diagnostics

```{r hetero}
res <- apa_hetero(fit)
res <- apa_homoskedasticity(fit)
```

---

## 13. Multilevel model reporting

```{r multilevel, eval = requireNamespace("lme4", quietly = TRUE)}
library(lme4)
data(ECLS_demo)

m0 <- lmer(math ~ 1 + (1 | schid),        data = ECLS_demo, REML = FALSE)
m1 <- lmer(math ~ SES + (1 | schid),      data = ECLS_demo, REML = FALSE)
m2 <- lmer(math ~ SES + gender + (1 | schid), data = ECLS_demo, REML = FALSE)

res <- apa_multilevel(
  m0, m1, m2,
  model_names = c("Null", "+ SES", "+ SES + Gender")
)
```

The function reports fixed effects, random effects, the intraclass correlation
coefficient (ICC), marginal and conditional R-squared, and a likelihood ratio
model-comparison table.

---

## 14. Exporting to Word

Any result can be passed to `apa_to_flextable()` and then saved:

```{r word, eval = FALSE}
ft <- apa_to_flextable(res)

doc <- officer::read_docx()
doc <- flextable::body_add_flextable(doc, ft)
print(doc, target = "my_table.docx")
```

Or use the built-in Word route directly:

```{r word2, eval = FALSE}
apa_table(fit, output = "word", file = "regression_table.docx")
```

---

## 15. APA figures

```{r plots, fig.width = 6, fig.height = 4}
apa_plot_descriptives(mtcars2, y = "mpg", group = "cyl", show_points = TRUE)
```

```{r plots2, fig.width = 6, fig.height = 4}
apa_plot_anova(aov(mpg ~ cyl, data = mtcars2), by = "cyl")
```