---
title: "Getting started with colleyRstats"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with colleyRstats}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`colleyRstats` helps streamline a typical analysis workflow: configure a session,
check assumptions, create a plot, and generate manuscript-ready text.

## Session setup

Attach the packages you need first, then configure the session.
`colleyRstats_setup()` sets the package's `ggplot2` theme, so every figure below
comes out with consistent typography.

```{r}
library(colleyRstats)

colleyRstats_setup(print_citation = FALSE, verbose = FALSE)
```

If you also want the package's `conflicted` preferences -- `dplyr::filter()`
over `stats::filter()`, `psych::describe()` over `Hmisc::describe()`, and so on
-- pass `set_conflicts = TRUE`, and put that call **after** every `library()`
call in the script:

```r
library(colleyRstats)
library(easystats)
library(dplyr)

colleyRstats_setup(set_conflicts = TRUE)   # last
```

The ordering matters in both directions. Activating `conflicted` replaces
`library()` for the rest of the session, and meta-packages such as `easystats`
cannot be attached once it has; and `conflicted` resolves only those names that
are ambiguous among the packages attached at the time, so a call made before the
rest of your `library()` calls has less to work with.

## Example data

```{r}
set.seed(123)

main_df <- data.frame(
  Participant = factor(rep(1:20, each = 2)),
  ConditionID = factor(rep(c("Control", "Treatment"), times = 20)),
  score = rnorm(40, mean = rep(c(50, 55), times = 20), sd = 8)
)
```

## Check assumptions

```{r}
check_normality_by_group(main_df, "ConditionID", "score")
check_homogeneity_by_group(main_df, "ConditionID", "score")
```

## Create a plot

```{r}
plot_effect(
  data = transform(main_df, Group = ConditionID),
  x = "ConditionID",
  y = "score",
  fillColourGroup = "Group",
  ytext = "Score",
  xtext = "Condition"
)
```

## Produce a reporting sentence

```{r}
art_summary <- data.frame(
  Effect = "ConditionID",
  Df = 1,
  `F value` = 5.42,
  `Pr(>F)` = 0.027,
  Df.res = 19,
  check.names = FALSE
)

report_art(art_summary, dv = "score")
```

## Next steps

- `vignette("analyzing-a-user-study")` walks a complete within-subjects study
  from raw data to manuscript-ready text and figures, including the one-call
  `analyze_and_report()` / `report_all()` pipeline.
- `vignette("choosing-a-test")` shows how `recommend_test()` selects the right
  test or mixed model from the data, and how to report GLMMs/CLMMs.
- `vignette("overleaf")` covers getting the LaTeX output into an Overleaf
  project that compiles immediately (`latex_preamble()`, `use_colleyrstats_sty()`,
  `emit_overleaf()`).
- Browse the reference for reporting helpers such as `reportMeanAndSD()` and
  `reportDunnTest()`, and use `generateMoboPlot()` / `generateMoboPlot2()` for
  optimization studies.