lsr

Imported from djnavarro/lsr (AGENTS.md). Install upstream with npx skills add djnavarro/lsr. Copyright stays with the author.

lsr – Agent Instructions

Package Overview

lsr (Learning Statistics with R) is a companion package to the textbook Learning Statistics with R: A Tutorial for Psychology Students and Other Beginners (Navarro, 2015). It provides beginner-friendly wrappers around common statistical procedures and is published on CRAN.

• Current version: 0.5.2
• R dependency: >= 3.0.0
• License: MIT
• Repository: https://github.com/djnavarro/lsr
• Documentation site: https://learningstatisticswithr.com

Development Status and Priorities

The package is stable and feature-frozen. No new exported functions, no API changes, and no new dependencies are planned. Work is limited to six stages, listed in order of priority:

1. Test suite quality – Complete. 28 test files, 448 assertions, all 29 exported functions covered.
2. Internal hardening – Complete. 486 assertions. All five original targets addressed; full review of all 29 source files conducted and four additional groups of issues resolved. See PLAN.md for details.
3. Bug fixes – Complete. 501 assertions. All five open GitHub issues resolved; three code bugs fixed, two closed as non-bugs. One missed Stage 2 hardening item also fixed. See PLAN.md for details.
4. Release infrastructure – Complete. Bumped to dev version 0.5.2.9000, created NEWS.md.
5. Test coverage review – Complete. Coverage raised from 75% to 82% (556 assertions). correlate() loop bug fixed. See PLAN.md for details.
6. Documentation improvement – Complete. Roxygen tags revised for accuracy and beginner-friendliness across all 29 functions, in four groups (PRs #17–#20, 2026-07-11). Also fixed a duplicate @description bug in quantileCut. See PLAN.md for details.
7. Code linting – Complete. Tidyverse style applied via styler across all 29 source files and all test files; dead code removed from bars.R, rowCopy.R, and correlate.R; two internal variable renames (cttp → ct_result in correlate.R; c → var_call in who.R); fragile exists() call in test-rmAll.R fixed (PR #21, 2026-07-11). See PLAN.md for details.
8. pkgdown site – Complete. Structured Reference section in _pkgdown.yml (five named groups, all 34 exported names); rewritten README.Rmd (orienting description, motivating example, "where to go next" links); two pkgdown-only articles: vignettes/articles/overview.Rmd (guided novice tour of all major functions) and vignettes/articles/commentary.Rmd (first-person critical assessment, historical context, alternatives). knitr and rmarkdown added to Suggests. Four PRs (#22–#23, plus #20a for _pkgdown.yml and README). See PLAN.md for details.
9. CRAN submission preparation – Complete. Version bumped to 1.0.0; LazyLoad removed; Language: en-GB added; Description rewritten; inst/CITATION removed; inst/WORDLIST added; NEWS.md finalised; spelling, URL, R CMD check --as-cran, rhub, win-builder, and reverse-dependency checks all passed. Seven additional bugs fixed after a release-candidate stress test (PRs #25, #27). Single PR (stage-9-cran-prep) targeting dev. See PLAN.md for details.
10. CRAN submission and post-release – Package submitted to CRAN on 2026-07-12. Awaiting review. After acceptance: tag v1.0.0, open dev at 1.0.0.9000. See PLAN.md for details.

When in doubt, do less. A minimal, safe, targeted change is always preferable to a broad refactor.

Branch Workflow

Never open a PR directly against main unless it is the final release merge from dev.

Repository Layout

R/              # Source files – one file per exported function (mostly)
tests/
  testthat/     # One test file per source file, named test-<function>.R
man/            # Roxygen2-generated .Rd files (do not edit by hand)
inst/CITATION   # Academic citation information
.github/
  workflows/    # R-CMD-check, test-coverage, pkgdown CI
DESCRIPTION
NAMESPACE       # Generated by roxygen2 (do not edit by hand)
NEWS            # Changelog

Exported Functions

The package exports 29 functions across four areas:

Hypothesis tests oneSampleTTest, independentSamplesTTest, pairedSamplesTTest, associationTest, goodnessOfFitTest, posthocPairwiseT

Effect sizes and summaries cohensD, etaSquared, cramersV, ciMean, correlate

Data manipulation wideToLong, longToWide, expandFactors, permuteLevels, quantileCut, sortFrame, tFrame, colCopy, rowCopy

Workspace utilities who, modeOf, aad, maxFreq, rmAll, unlibrary, importList, standardCoefs

Custom S3 classes with print methods: TTest, whoList, correlate, assocTest, gofTest.

Testing

• Framework: testthat (>= 3.0.0, edition 3)
• Entry point: tests/testthat.R
• One test file per function, named test-<function>.R
• Run the full suite with devtools::test() or R CMD check

Current state of the test suite

The test suite was overhauled in Stage 1, extended during Stage 2 hardening, and further extended during Stage 3 bug fixes and Stage 5 coverage work (all completed 2026-07-10 to 2026-07-11). It now has 28 test files and 556 assertions covering all 29 exported functions and all S3 print methods, with 82% line coverage. Every file covers at minimum: typical usage, numeric correctness against a reference (base R or hand-computed), and expected errors/warnings.

When adding new tests, the existing files are a reasonable model to follow.

Guidelines for writing tests

• Each test file should cover: typical usage, edge cases, and expected errors (expect_error, expect_warning).
• Use tolerance when comparing floating-point results (e.g., expect_equal(..., tolerance = 1e-4)).
• Do not use snapshots for numeric results; pin exact values with tolerances.
• Tests must pass on R release, devel, and oldrel-1 across macOS, Windows, and Ubuntu (matching the CI matrix in .github/workflows/R-CMD-check.yaml).
• Avoid testing implementation details; test the public interface.

Internal Hardening Guidelines

• Validate inputs early and fail with informative, user-friendly error messages. The audience is introductory statistics students, so messages should be plain English.
• Prefer stop() / warning() over silent coercion that could mask mistakes.
• Do not add new dependencies. All statistical computation should use base R or the packages already listed in Imports (graphics, grDevices, methods, stats).
• Keep changes narrow. If hardening one function, do not refactor adjacent functions in the same PR unless there is a direct dependency.

Hardening work completed (Stages 2 and 3)

All five original targets and four additional groups of issues identified during a full-codebase review were resolved on 2026-07-10. Two further class() == / class() %in% comparisons missed during Stage 2 (in modeOf and bars) were found and fixed during Stage 3 (PR #15, 2026-07-11). See PLAN.md for the complete list. No known hardening issues remain.

Documentation

• Docs are written as roxygen2 comments in the source files.
• Run devtools::document() to regenerate man/ and NAMESPACE.
• Do not edit man/*.Rd files or NAMESPACE by hand.
• The RoxygenNote field in DESCRIPTION must match the installed roxygen2 version after any documentation rebuild.
• The pkgdown site is deployed automatically from main via GitHub Actions. Do not commit to docs/ manually.

Documentation style (Stage 6 conventions, completed 2026-07-11)

All 29 exported functions and their print methods were revised in Stage 6. The conventions established are:

• @description: one clear sentence per function; no "convenience function" or "intended for pedagogical purposes only" hedging.
• @param: plain English; flags described as directives ("Set to TRUE to …"), not questions ("Should R …?").
• @return: describes what the user sees, not "returns an object of class X"; print methods note they are called automatically on display.
• @details: accurate after Stages 1–3; no first-person language; no "future versions will …" promises.
• @seealso: present on every function.
• @examples: self-contained and immediately runnable; consistent style (spaces around =, spaces after commas, no padding inside ()); interactive examples wrapped in if(FALSE){} (not \dontrun{}); no library() calls inside if(FALSE){} for packages not in Suggests (triggers R CMD check dependency warning).

CI / CD

All checks must pass before merging into dev. Do not merge failing PRs.

What Agents Should Not Do

• Do not add new exported functions or change any function signature.
• Do not add packages to Imports or Depends.
• Do not modify NAMESPACE or man/ files directly.
• Do not open PRs against main (reserved for CRAN release merges).
• Do not make broad stylistic refactors unrelated to a specific fix or test.
• Do not change user-visible output formatting unless it is a clear bug.