|
| 1 | +# Copilot Instructions for ggstatsplot |
| 2 | + |
| 3 | +## Package Overview |
| 4 | + |
| 5 | +`ggstatsplot` is an R package that creates `ggplot2`-based plots with statistical details included in the plots themselves. It serves as a visualization frontend for `statsExpressions`. |
| 6 | + |
| 7 | +## Architecture |
| 8 | + |
| 9 | +### Main Functions (R/) |
| 10 | + |
| 11 | +- **Visualization functions**: `ggbetweenstats()`, `ggwithinstats()`, `gghistostats()`, `ggdotplotstats()`, `ggscatterstats()`, `ggcorrmat()`, `ggpiestats()`, `ggbarstats()`, `ggcoefstats()` |
| 12 | +- **Grouped variants**: `grouped_ggbetweenstats()`, etc. - repeat same analysis across grouping variable |
| 13 | +- **Each function supports 4 types** via `type` parameter: `"parametric"`, `"nonparametric"`, `"robust"`, `"bayes"` |
| 14 | +- **Output**: All functions return ggplot objects with statistical annotations |
| 15 | + |
| 16 | +### Key Helper Functions |
| 17 | + |
| 18 | +- `extract_stats()`: Extract statistical details from a ggstatsplot object |
| 19 | +- `extract_subtitle()`: Extract expression from subtitle |
| 20 | +- `extract_caption()`: Extract expression from caption |
| 21 | +- `theme_ggstatsplot()`: Default theme for plots |
| 22 | +- `combine_plots()`: Combine multiple plots using patchwork |
| 23 | + |
| 24 | +### Dependencies |
| 25 | + |
| 26 | +Core: `ggplot2`, `statsExpressions`, tidyverse stack (`dplyr`, `purrr`, `tidyr`, `rlang`), `patchwork`, `paletteer`, easystats ecosystem (`insight`, `parameters`, `performance`, `datawizard`, `correlation`) |
| 27 | + |
| 28 | +## Developer Workflow |
| 29 | + |
| 30 | +### Common Commands (via Makefile) |
| 31 | + |
| 32 | +```bash |
| 33 | +make document # Generate documentation (roxygen2) |
| 34 | +make build # Build package tarball |
| 35 | +make check # Run R CMD check |
| 36 | +make install # Install package locally |
| 37 | +make lint # Run lintr checks |
| 38 | +make format # Format code with styler |
| 39 | +make install_deps # Install/update dependencies |
| 40 | +``` |
| 41 | + |
| 42 | +### Testing |
| 43 | + |
| 44 | +- Framework: `testthat` (edition 3) with parallel execution |
| 45 | +- Run tests: `devtools::test()` or `make check` |
| 46 | +- **Snapshot tests**: Used for plot output verification via `vdiffr` |
| 47 | +- Test files mirror source files: `R/ggbetweenstats.R` -> `tests/testthat/test-ggbetweenstats.R` |
| 48 | +- Coverage requirement: **100%** (enforced by codecov) |
| 49 | + |
| 50 | +### Adding New Tests |
| 51 | + |
| 52 | +```r |
| 53 | +test_that("descriptive name", { |
| 54 | + set.seed(123) |
| 55 | + p <- function_under_test(data = dataset, x = var1, y = var2) |
| 56 | + expect_s3_class(p, "ggplot") |
| 57 | + vdiffr::expect_doppelganger("descriptive-name", p) |
| 58 | +}) |
| 59 | +``` |
| 60 | + |
| 61 | +## Code Conventions |
| 62 | + |
| 63 | +### Style |
| 64 | + |
| 65 | +- **Linting**: Uses `lintr::all_linters()` with exceptions in `.lintr` |
| 66 | +- **Formatting**: `styler::style_pkg()` (run via `make format`) |
| 67 | +- **Naming**: snake_case for functions and variables |
| 68 | +- **Pipes**: Use base R `|>` pipe (NOT magrittr `%>%`) |
| 69 | + |
| 70 | +### Roxygen Documentation |
| 71 | + |
| 72 | +- Uses `roxygen2` with markdown support (`Roxygen: list(markdown = TRUE)`) |
| 73 | +- Uses `@autoglobal` annotation from `roxyglobals` for global variables |
| 74 | +- Template files in `man-roxygen/` for shared documentation |
| 75 | +- Run `make document` after modifying roxygen comments |
| 76 | + |
| 77 | +### Function Parameters |
| 78 | + |
| 79 | +Common parameters across functions: |
| 80 | + |
| 81 | +- `data`: Input dataframe |
| 82 | +- `x`, `y`: Column names (unquoted, uses tidy evaluation) |
| 83 | +- `type`: One of `"parametric"`, `"nonparametric"`, `"robust"`, `"bayes"` |
| 84 | +- `paired`: Logical for paired/within-subjects designs |
| 85 | +- `results.subtitle`: Whether to show statistical results in subtitle |
| 86 | +- `centrality.plotting`: Whether to show centrality measure |
| 87 | +- `bf.message`: Whether to show Bayes factor message in caption |
| 88 | +- `ggtheme`: ggplot2 theme to use |
| 89 | +- `palette`, `package`: Color palette specifications |
| 90 | + |
| 91 | +## Important Patterns |
| 92 | + |
| 93 | +### Plot Construction |
| 94 | + |
| 95 | +Functions build plots layer by layer using ggplot2: |
| 96 | + |
| 97 | +```r |
| 98 | +ggplot(data, aes(x = x, y = y)) + |
| 99 | + geom_violin() + |
| 100 | + geom_boxplot() + |
| 101 | + labs(subtitle = stats_expression, caption = bf_expression) + |
| 102 | + theme_ggstatsplot() |
| 103 | +``` |
| 104 | + |
| 105 | +### Statistical Analysis Delegation |
| 106 | + |
| 107 | +All statistical computations are delegated to `statsExpressions`: |
| 108 | + |
| 109 | +```r |
| 110 | +statsExpressions::two_sample_test(data, x, y, type = type) |
| 111 | +``` |
| 112 | + |
| 113 | +### Grouped Functions |
| 114 | + |
| 115 | +Use `purrr::pmap()` to apply function across groups: |
| 116 | + |
| 117 | +```r |
| 118 | +purrr::pmap(list_of_args, ggbetweenstats) |> |
| 119 | + patchwork::wrap_plots() |
| 120 | +``` |
| 121 | + |
| 122 | +## Testing Tips |
| 123 | + |
| 124 | +- Set seeds before tests: `set.seed(123)` |
| 125 | +- Use `skip_if_not_installed()` for optional dependencies |
| 126 | +- Use `vdiffr::expect_doppelganger()` for visual regression tests |
| 127 | +- Use `suppressWarnings()` when tests intentionally trigger warnings |
| 128 | + |
| 129 | +## Files to Update Together |
| 130 | + |
| 131 | +When modifying a function: |
| 132 | + |
| 133 | +1. `R/<function>.R` - Source code |
| 134 | +2. `man/<function>.Rd` - Will auto-generate from roxygen |
| 135 | +3. `tests/testthat/test-<function>.R` - Tests |
| 136 | +4. `vignettes/web_only/<function>.Rmd` - Vignette (if exists) |
| 137 | +5. `NEWS.md` - Document user-facing changes |
| 138 | + |
| 139 | +## CI/CD |
| 140 | + |
| 141 | +- GitHub Actions workflows in `.github/workflows/` |
| 142 | +- Automated R CMD check on multiple platforms |
| 143 | +- Code coverage uploaded to Codecov (100% required) |
| 144 | +- Visual regression tests with vdiffr |
| 145 | +- Dependency updates via Dependabot |
0 commit comments