Package {colleyRstats}

Type:	Package
Title:	Functions to Streamline Statistical Analysis and Reporting
Version:	0.1.2
Description:	Built upon popular R packages such as 'ggstatsplot' and 'ARTool', this collection offers a wide array of tools for simplifying reproducible analyses, generating high-quality visualizations, and producing 'APA'-compliant outputs. The primary goal of this package is to significantly reduce repetitive coding efforts, allowing you to focus on interpreting results. Whether you're dealing with ANOVA assumptions, reporting effect sizes, or creating publication-ready visualizations, this package makes these tasks easier.
URL:	https://github.com/M-Colley/colleyRstats
BugReports:	https://github.com/M-Colley/colleyRstats/issues
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	8.0.0
Language:	en-US
Depends:	R (≥ 4.2.0), ggplot2 (≥ 3.4.0)
Imports:	dplyr (≥ 1.1.0), effectsize, ggpmisc (≥ 0.5.0), ggsignif, ggstatsplot (≥ 1.0.0), purrr, rlang, see, stats, statsExpressions (≥ 2.0.0), stringr, tidyr, utils
Suggests:	afex, ARTool (≥ 0.11.0), BayesFactor, bayestestR, Cairo, car, clipr, conflicted, dunn.test, DT, emmeans, emoa, flexdashboard, FSA, ggtext, glmmTMB, Hmisc, knitr, lme4, moocore, nparLD, ordinal, parameters, patchwork, pkgload, psych, readxl, report, reporttools, rmarkdown, rstantools, rstatix, scales, sjPlot, stargazer, styler, testthat (≥ 3.3.0), tibble, writexl, xtable
Config/testthat/edition:	3
Config/Needs/check:	anthonynorth/roxyglobals
Config/roxyglobals/unique:	TRUE
Config/testthat/parallel:	false
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-07-06 08:27:46 UTC; Mark
Author:	Mark Colley [aut, cre, cph]
Maintainer:	Mark Colley <mark.colley@yahoo.de>
Repository:	CRAN
Date/Publication:	2026-07-06 08:50:02 UTC

Add PARETO_EMOA Column to a Data Frame

Description

This function calculates the Pareto front using emoa for a given set of objectives in a data frame and adds a new column, PARETO_EMOA, which indicates whether each row in the data frame belongs to the Pareto front.

Usage

add_pareto_emoa_column(data, objectives)

Arguments

Value

A data frame with the same columns as data, along with an additional column, PARETO_EMOA, which is TRUE for rows that are on the Pareto front and FALSE otherwise.

Examples

# Define objective columns
objectives <- c("trust", "predictability", "perceivedSafety", "Comfort")

# Example data frame
main_df <- data.frame(
  trust = runif(10),
  predictability = runif(10),
  perceivedSafety = runif(10),
  Comfort = runif(10)
)

# Add the Pareto front column
main_df <- add_pareto_emoa_column(data = main_df, objectives)
head(main_df)

Add PARETO_MOOCORE Column to a Data Frame

Description

This function calculates the Pareto front using moocore for a given set of objectives in a data frame and adds a new column, PARETO_MOOCORE, which indicates whether each row in the data frame belongs to the Pareto front.

Usage

add_pareto_moocore_column(data, objectives)

Arguments

Value

A data frame with the same columns as data, along with an additional column, PARETO_MOOCORE, which is TRUE for rows that are on the Pareto front and FALSE otherwise.

Examples

# Define objective columns
objectives <- c("trust", "predictability", "perceivedSafety", "Comfort")

# Example data frame
main_df <- data.frame(
  trust = runif(10),
  predictability = runif(10),
  perceivedSafety = runif(10),
  Comfort = runif(10)
)

# Add the Pareto front column
main_df <- add_pareto_moocore_column(data = main_df, objectives)
head(main_df)

Analyze one dependent variable and produce everything a paper needs

Description

One-call pipeline for a single dependent variable: checks the assumptions (producing a ready-made methods sentence via assumption_methods_text()), builds the matching ggstatsplot figure with automatic parametric/non-parametric selection, reports the omnibus test via reportggstatsplot(), and – for more than two groups – reports the significant post-hoc comparisons via reportggstatsplotPostHoc().

Usage

analyze_and_report(
  data,
  dv,
  iv,
  design = c("between", "within"),
  ylab = dv,
  xlabels = NULL,
  plotType = "boxviolin",
  sink_to = NULL
)

Arguments

Value

Invisibly returns a list with components plot (the ggplot), methods (assumption-check sentence), text (omnibus result), posthoc (post-hoc sentences, or NULL for two groups), and sentences (all text combined, in manuscript order).

Examples

result <- analyze_and_report(mtcars, dv = "mpg", iv = "cyl")
result$plot

Methods-section sentence justifying the test selection

Description

Runs the group-wise Shapiro-Wilk normality check (and optionally Levene's test for homogeneity of variances) and turns the outcome into a ready-made methods-section sentence, including the relevant statistics. This is the justification reviewers expect next to the choice of a parametric or non-parametric test.

Usage

assumption_methods_text(data, x, y, include_homogeneity = FALSE)

Arguments

Value

Invisibly returns the sentence(s) as a single string; the text is also emitted via message().

Examples

set.seed(1)
d <- data.frame(g = rep(c("A", "B"), each = 20), v = rnorm(40))
assumption_methods_text(d, x = "g", y = "v")

Check the assumptions for an ANOVA with a variable number of factors: Normality and Homogeneity of variance assumption.

Description

Check the assumptions for an ANOVA with a variable number of factors: Normality and Homogeneity of variance assumption.

Usage

checkAssumptionsForAnova(data, y, factors)

check_assumptions_anova(data, y, factors)

Arguments

Value

A message indicating whether to use parametric or non-parametric ANOVA

Examples

set.seed(123)

main_df <- data.frame(
  tlx_mental      = rnorm(40),
  Video           = factor(rep(c("A", "B"), each = 20)),
  DriverPosition  = factor(rep(c("Left", "Right"), times = 20))
)

checkAssumptionsForAnova(
  data    = main_df,
  y       = "tlx_mental",
  factors = c("Video", "DriverPosition")
)

Check homogeneity of variances across groups

Description

Check homogeneity of variances across groups

Usage

check_homogeneity_by_group(data, x, y)

Arguments

Value

TRUE if Levene's test is non-significant (p >= .05), FALSE otherwise. The Levene test result (columns df1, df2, statistic, p) is attached in the "test" attribute, e.g. for use in a methods section via assumption_methods_text().

Check normality for groups

Description

Check normality for groups

Usage

check_normality_by_group(data, x, y)

Arguments

Value

TRUE if all groups are normal, FALSE otherwise. The per-group Shapiro-Wilk statistics are attached as a data frame in the "tests" attribute (columns: group, W, p_value), e.g. for use in a methods section via assumption_methods_text(). For groups with more than 5000 non-missing values, Shapiro-Wilk is computed on a random sample of 5000 observations (a warning is emitted); the returned value still reflects that sampled test. Because the sample is drawn randomly, results for such large groups are not reproducible unless a seed is set beforehand.

Citations and methods boilerplate for the analyses used

Description

Prints a ready-made methods phrase plus the BibTeX entries for the R packages behind the requested analysis methods, so a manuscript's methods section and bibliography can be filled in one step.

Usage

cite_methods(methods = c("ggstatsplot", "effectsize"), bibtex = TRUE)

Arguments

Value

Invisibly returns the generated lines as a character vector; the text is also emitted via message(). Methods whose package is not installed are skipped with a message.

Examples

cite_methods("ggstatsplot", bibtex = FALSE)

Classify the measurement scale of an outcome variable

Description

Decides how a dependent variable should be modelled by inspecting its type and distribution of values. The measurement scale is the first branch of a principled model choice: it dictates the family (Gaussian, binomial, Poisson, cumulative-link) before any distributional assumption is checked.

Usage

classify_outcome(y, ordinal_max_levels = 7L)

Arguments

Details

The rules are deliberately simple and transparent:

• ordered factor \rightarrow "ordinal";

• logical, a two-level factor, or a numeric/character with exactly two distinct values \rightarrow "binary";

• unordered factor/character with more than two levels \rightarrow "nominal";

• integer-valued numeric with at most ordinal_max_levels distinct values (a Likert-type item) \rightarrow "ordinal";

• non-negative integer-valued numeric with more distinct values \rightarrow "count";

• any other numeric \rightarrow "continuous".

The heuristics can never be perfect (a 1–7 Likert item and a small count are genuinely ambiguous); pass an explicit outcome_type to recommend_test() when you want to override them.

Value

A single string, one of "continuous", "ordinal", "binary", "count", or "nominal".

Examples

classify_outcome(rnorm(50)) # "continuous"
classify_outcome(factor(sample(1:5, 50, TRUE), ordered = TRUE)) # "ordinal"
classify_outcome(sample(0:1, 50, TRUE)) # "binary"
classify_outcome(rpois(50, 3)) # "count"

Configure Global R Environment for colleyRstats

Description

Sets ggplot2 themes and conflict preferences to match the standards used in the colleyRstats workflow.

Usage

colleyRstats_setup(
  set_options = FALSE,
  set_theme = TRUE,
  set_conflicts = TRUE,
  print_citation = TRUE,
  verbose = TRUE
)

Arguments

Value

Invisibly returns NULL.

Examples

# Runs everywhere, no extra packages, no session side effects
colleyRstats::colleyRstats_setup(
  set_options = FALSE,
  set_theme = FALSE,
  set_conflicts = FALSE,
  print_citation = FALSE,
  verbose = FALSE
)


# Full setup (requires suggested packages; changes session defaults)
if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("see", quietly = TRUE)) {
  local({
    old_theme <- ggplot2::theme_get()
    on.exit(ggplot2::theme_set(old_theme), add = TRUE)

    colleyRstats::colleyRstats_setup(
      set_options = FALSE,
      set_conflicts = FALSE,   # avoid persisting conflict prefs in checks
      print_citation = FALSE,
      verbose = TRUE
    )

    ggplot2::ggplot(mtcars, ggplot2::aes(mpg, wt)) +
      ggplot2::geom_point()
  })
}

Replace values across a data frame

Description

Replace all occurrences of given values in all columns of a data frame.

The data data frame contains a collection of records, with attributes organized in columns. It may include various types of values, such as numerical, categorical, or textual data.

Usage

replace_values(data, to_replace, replace_with)

Arguments

Value

Modified data frame with specified values replaced.

Examples

data <- data.frame(
  q1 = c("neg2", "neg1", "0"),
  q2 = c("1", "neg2", "neg1")
)

replace_values(
  data,
  to_replace = c("neg2", "neg1"),
  replace_with = c("-2", "-1")
)

Debug contrast errors in ANOVA-like models

Description

Debug contrast errors in ANOVA-like models

Usage

debug_contr_error(dat, subset_vec = NULL)

Arguments

Value

A list with two elements:

nlevels

Integer vector giving the number of levels for each factor variable in dat.

levels

List of factor level labels for each factor variable in dat.

Examples

dat <- data.frame(
  group = factor(rep(letters[1:3], each = 3)),
  score = rnorm(9)
)

debug_contr_error(dat = dat)

Define a named LaTeX macro for a single result (single source of truth)

Description

Emits \newcommand{\<name>}{<value>} so you can write \<name> in your prose and have it always reflect the latest analysis – re-run the R code and the number updates everywhere it is referenced, the gold standard for reproducible manuscripts. The name is sanitised to a valid letters-only LaTeX command name.

Usage

define_result_macro(name, value, path = NULL)

Arguments

Value

Invisibly, a named character scalar: the \newcommand line, named by the generated command. Also emitted via message().

Examples

define_result_macro("tlx_mental_omnibus", "F(2, 57) = 4.50, p = .02")

Generate \newcommand stubs for variable/factor names

Description

The report functions can emit variable and factor-level names as LaTeX commands (e.g. \Video) so their typography is controlled centrally. This writes the matching \newcommand definitions so those commands are never undefined – the classic "Undefined control sequence" that stops an Overleaf build. Only names that are valid LaTeX command names (letters only) get a macro; others are reported as skipped (the reporters emit those as escaped plain text instead).

Usage

emit_name_macros(vars, path = NULL, labels = NULL)

Arguments

Value

Invisibly, the \newcommand lines as a character vector; also emitted via message().

Examples

emit_name_macros(c("Video", "DriverPosition"))
emit_name_macros(c(tlxMental = "TLX Mental Demand"))

Bundle an analysis into an Overleaf-ready folder

Description

Writes everything a manuscript needs into one directory you can drag into Overleaf and compile immediately: a main.tex that already \inputs the results, one .tex per result section, the figures, a references.bib, and – unless macros are expanded inline – colleyRstats.sty. This is the one-call end of the "R analysis to compiled PDF" pipeline.

Usage

emit_overleaf(
  x,
  dir,
  figures = TRUE,
  methods = c("ggstatsplot", "effectsize"),
  title = "Results",
  plain = NULL,
  columns = 1,
  overwrite = FALSE
)

Arguments

Value

Invisibly, a list with the paths written (dir, main, results, sections, figures, bib, sty).

Examples

out <- report_all(mtcars, dvs = c("mpg", "disp"), iv = "cyl")
emit_overleaf(out, dir = file.path(tempdir(), "paper"), overwrite = TRUE)

Expand the colleyRstats LaTeX macros to plain standard LaTeX

Description

The report functions normally emit compact custom macros (\F, \p, \m, \sd, \df, \chisq, \padj, \padjminor, \pminor, \rankbiserial, \effectsize) that require latex_preamble() definitions. This expands them into equivalent plain math (e.g. \F{2}{57}{4.50} becomes $F(2, 57) = 4.50$) so the text compiles in any document with no custom preamble – the "zero-setup Overleaf" path. It is applied automatically by the sink_to/emit_overleaf() writers when options(colleyRstats.macros = FALSE).

Usage

expand_latex_macros(x)

Arguments

Value

The text with the macros expanded to standard LaTeX math.

Examples

expand_latex_macros("A significant effect (\\F{2}{57}{4.50}, \\p{0.012}).")

Function to define a plot, either showing the main or interaction effect in bold.

Description

Function to define a plot, either showing the main or interaction effect in bold.

Usage

generateEffectPlot(
  data,
  x,
  y,
  fillColourGroup,
  ytext = "testylab",
  xtext = "testxlab",
  legendPos = c(0.1, 0.23),
  legendHeading = NULL,
  shownEffect = "main",
  effectLegend = FALSE,
  effectDescription = NULL,
  xLabelsOverwrite = NULL,
  useLatexMarkup = FALSE,
  numberColors = 6
)

plot_effect(
  data,
  x,
  y,
  fillColourGroup,
  ytext = "testylab",
  xtext = "testxlab",
  legendPos = c(0.1, 0.23),
  legendHeading = NULL,
  shownEffect = "main",
  effectLegend = FALSE,
  effectDescription = NULL,
  xLabelsOverwrite = NULL,
  useLatexMarkup = FALSE,
  numberColors = 6
)

Arguments

Value

a plot

Examples

set.seed(123)
main_df <- data.frame(
  strategy    = factor(rep(c("A", "B"), each = 20)),
  Emotion     = factor(rep(c("Happy", "Sad"), times = 20)),
  trust_mean  = rnorm(40, mean = 5, sd = 1)
)

generateEffectPlot(
  data = main_df,
  x = "strategy",
  y = "trust_mean",
  fillColourGroup = "Emotion",
  ytext = "Trust",
  xtext = "Strategy",
  legendPos = c(0.1, 0.23)
)

Generate a Multi-objective Optimization Plot

Description

This function generates a multi-objective optimization plot using ggplot2. The plot visualizes the relationship between the x and y variables, grouping and coloring by a fill variable, with the option to customize legend position, labels, and annotation of sampling and optimization phases.

Usage

generateMoboPlot(
  data,
  x,
  y,
  fillColourGroup = "ConditionID",
  ytext,
  legendPos = c(0.65, 0.85),
  numberSamplingSteps = 5,
  labelPosFormulaY = "top",
  verticalLinePosY = 0.75
)

plot_mobo(
  data,
  x,
  y,
  fillColourGroup = "ConditionID",
  ytext,
  legendPos = c(0.65, 0.85),
  numberSamplingSteps = 5,
  labelPosFormulaY = "top",
  verticalLinePosY = 0.75
)

Arguments

Value

A ggplot object representing the multi-objective optimization plot, ready to be rendered.

Examples

library(ggplot2)
library(ggpmisc)

# Example with numeric x-axis
df <- data.frame(
  x = 1:20,
  y = rnorm(20),
  ConditionID = rep(c("A", "B"), 10)
)
generateMoboPlot(df, x = "x", y = "y")

# Example with factor x-axis
df <- data.frame(
  x = factor(rep(1:5, each = 4)),
  y = rnorm(20),
  ConditionID = rep(c("A", "B"), 10)
)
generateMoboPlot(df, x = "x", y = "y", numberSamplingSteps = 3)

Generate a Multi-objective Optimization Plot

Description

This function generates a multi-objective optimization plot using ggplot2. The plot visualizes the relationship between the x and y variables, grouping and coloring by a fill variable, with the option to customize legend position, labels, and annotation of sampling and optimization phases. Appropriate if you use https://github.com/Pascal-Jansen/Bayesian-Optimization-for-Unity in version 1.1.0 or higher.

Usage

generateMoboPlot2(
  data,
  x = "Iteration",
  y,
  phaseCol = "Phase",
  fillColourGroup = "ConditionID",
  ytext,
  legendPos = c(0.65, 0.85),
  labelPosFormulaY = "top",
  labelPosFormulaX = "left",
  horizontalLinePosY = 0.75,
  horizontalLineDistToText = 0.3,
  fillLabels = NULL,
  annotationTextSize = 5
)

plot_mobo2(
  data,
  x = "Iteration",
  y,
  phaseCol = "Phase",
  fillColourGroup = "ConditionID",
  ytext,
  legendPos = c(0.65, 0.85),
  labelPosFormulaY = "top",
  labelPosFormulaX = "left",
  horizontalLinePosY = 0.75,
  horizontalLineDistToText = 0.3,
  fillLabels = NULL,
  annotationTextSize = 5
)

Arguments

Value

A ggplot object representing the multi-objective optimization plot, ready to be rendered.

Examples

library(ggplot2)
library(ggpmisc)

# Example with numeric x-axis
df <- data.frame(
  x = 1:20,
  y = rnorm(20),
  ConditionID = rep(c("A", "B"), 10),
  Phase = rep(c("Sampling", "Optimization"), 10)
)
generateMoboPlot2(data = df, x = "x", y = "y")

Check the data's distribution. If non-normal, take the non-parametric variant of ggbetweenstats. x and y have to be in parentheses, e.g., "ConditionID".

Description

Check the data's distribution. If non-normal, take the non-parametric variant of ggbetweenstats. x and y have to be in parentheses, e.g., "ConditionID".

Usage

ggbetweenstatsWithPriorNormalityCheck(
  data,
  x,
  y,
  ylab,
  xlabels = NULL,
  showPairwiseComp = TRUE,
  plotType = "boxviolin"
)

plot_between_stats(
  data,
  x,
  y,
  ylab,
  xlabels = NULL,
  showPairwiseComp = TRUE,
  plotType = "boxviolin"
)

Arguments

Value

A ggplot object produced by ggstatsplot::ggbetweenstats, which can be printed or further modified with +.

Examples

set.seed(123)

# Toy within-subject style data
main_df <- data.frame(
  Participant = factor(rep(1:20, each = 3)),
  CondID      = factor(rep(c("A", "B", "C"), times = 20)),
  tlx_mental  = rnorm(60, mean = 50, sd = 10)
)

# Custom x-axis labels
labels_xlab <- c("Condition A", "Condition B", "Condition C")


ggbetweenstatsWithPriorNormalityCheck(
  data = main_df,
  x = "CondID",
  y = "tlx_mental", ylab = "Mental Demand",
  xlabels = labels_xlab,
  showPairwiseComp = TRUE
)

Check the data's distribution. If non-normal, take the non-parametric variant of ggbetweenstats. x and y have to be in parentheses, e.g., "ConditionID".

Description

Check the data's distribution. If non-normal, take the non-parametric variant of ggbetweenstats. x and y have to be in parentheses, e.g., "ConditionID".

Usage

ggbetweenstatsWithPriorNormalityCheckAsterisk(
  data,
  x,
  y,
  ylab,
  xlabels,
  plotType = "boxviolin"
)

plot_between_stats_asterisk(data, x, y, ylab, xlabels, plotType = "boxviolin")

Arguments

Value

A ggplot object produced by ggstatsplot::ggbetweenstats with additional significance annotations, which can be printed or modified.

Examples

set.seed(123)

# Toy within-subject style data
main_df <- data.frame(
  Participant = factor(rep(1:20, each = 3)),
  CondID      = factor(rep(c("A", "B", "C"), times = 20)),
  tlx_mental  = rnorm(60, mean = 50, sd = 10)
)

# Custom x-axis labels
labels_xlab <- c("Condition A", "Condition B", "Condition C")


ggbetweenstatsWithPriorNormalityCheckAsterisk(
  data = main_df,
  x = "CondID", y = "tlx_mental", ylab = "Mental Demand", xlabels = labels_xlab
)

Check the data's distribution. If non-normal, take the non-parametric variant of ggwithinstats. x and y have to be in parentheses, e.g., "ConditionID".

Description

Check the data's distribution. If non-normal, take the non-parametric variant of ggwithinstats. x and y have to be in parentheses, e.g., "ConditionID".

Usage

ggwithinstatsWithPriorNormalityCheck(
  data,
  x,
  y,
  ylab,
  xlabels = NULL,
  showPairwiseComp = TRUE,
  plotType = "boxviolin"
)

plot_within_stats(
  data,
  x,
  y,
  ylab,
  xlabels = NULL,
  showPairwiseComp = TRUE,
  plotType = "boxviolin"
)

Arguments

Value

A ggplot object produced by ggstatsplot::ggwithinstats with additional significance annotations, which can be printed or modified.

Examples

#'   set.seed(123)

# Toy within-subject style data
main_df <- data.frame(
  Participant = factor(rep(1:20, each = 3)),
  CondID      = factor(rep(c("A", "B", "C"), times = 20)),
  tlx_mental  = rnorm(60, mean = 50, sd = 10)
)

# Custom x-axis labels
labels_xlab <- c("Condition A", "Condition B", "Condition C")


ggwithinstatsWithPriorNormalityCheck(
  data = main_df,
  x = "CondID", y = "tlx_mental",
  ylab = "Mental Demand",
  xlabels = labels_xlab,
  showPairwiseComp = TRUE
)

Check the data's distribution. If non-normal, take the non-parametric variant of ggwithinstats. x and y have to be in parentheses, e.g., "ConditionID". Add Asterisks instead of p-values.

Description

Check the data's distribution. If non-normal, take the non-parametric variant of ggwithinstats. x and y have to be in parentheses, e.g., "ConditionID". Add Asterisks instead of p-values.

Usage

ggwithinstatsWithPriorNormalityCheckAsterisk(
  data,
  x,
  y,
  ylab,
  xlabels,
  plotType = "boxviolin"
)

plot_within_stats_asterisk(data, x, y, ylab, xlabels, plotType = "boxviolin")

Arguments

Value

A ggplot object produced by ggstatsplot::ggwithinstats with additional significance annotations, which can be printed or modified.

Examples

set.seed(123)

# Toy within-subject style data
main_df <- data.frame(
  Participant = factor(rep(1:20, each = 3)),
  CondID      = factor(rep(c("A", "B", "C"), times = 20)),
  tlx_mental  = rnorm(60, mean = 50, sd = 10)
)

# Custom x-axis labels
labels_xlab <- c("Condition A", "Condition B", "Condition C")


ggwithinstatsWithPriorNormalityCheckAsterisk(
  data = main_df,
  x = "CondID", y = "tlx_mental",
  ylab = "Mental Demand", xlabels = labels_xlab
)

Escape LaTeX special characters in plain text

Description

Makes an arbitrary string safe to drop into a LaTeX document by escaping the characters that would otherwise be interpreted as markup (\ { } $ & # _ % ~ ^ < >). Use it on variable names, factor-level labels, captions – anything user-supplied that reaches the .tex. This is what prevents a dependent variable called tlx_mental from producing an un-compilable tlx_mental (a subscript error) in Overleaf.

Usage

latex_escape(x)

Arguments

Value

A character vector with LaTeX specials escaped; NA is preserved.

Examples

latex_escape("tlx_mental")
latex_escape("cost (%) & margin")

LaTeX preamble required by the report functions

Description

All report functions emit LaTeX text that relies on a small set of custom commands. This helper prints the complete set, ready to paste into a manuscript preamble, or writes it to a file that can be included with \input{} (or renamed to .sty and loaded via \usepackage).

Usage

latex_preamble(path = NULL)

Arguments

Value

Invisibly returns the macro definitions as a character vector; the text is also emitted via message().

Examples

latex_preamble()

Transform text from report::report() into LaTeX-friendly output.

Description

This function transforms the text output from report::report() by performing several substitutions to prepare the text for LaTeX typesetting. In particular, it replaces instances of R2, ⁠%⁠, and ~ with the corresponding LaTeX code. Additionally, it provides options to:

• Omit bullet items marked as "non-significant" (when only_sig = TRUE).

• Remove a concluding note about standardized parameters (when remove_std = TRUE).

• Wrap bullet items in a LaTeX itemize environment or leave them as plain text (controlled by itemize).

Usage

latexify_report(
  x,
  print_result = TRUE,
  only_sig = FALSE,
  remove_std = FALSE,
  itemize = TRUE
)

Arguments

Value

A single string with the LaTeX-friendly formatted report text.

Examples

if (requireNamespace("report", quietly = TRUE)) {
  # Simple linear model on the iris dataset
  model <- stats::lm(
    Sepal.Length ~ Sepal.Width + Petal.Length,
    data = datasets::iris
  )

  # Format the report output, showing only significant items, removing the
  # standard note, and wrapping bullet items in an itemize environment.
  report_text <- try(report::report(model), silent = TRUE)
  if (!inherits(report_text, "try-error")) {
    latexify_report(
      report_text,
      only_sig = TRUE,
      remove_std = TRUE,
      itemize = TRUE
    )
  }
}

Build a median/size label for plot annotations

Description

Build a median/size label for plot annotations

Usage

n_fun(x)

Arguments

Value

A data frame with the median and label.

Replace NA values with zero

Description

Replace NA values with zero

Usage

na.zero(x)

Arguments

Value

A vector with NAs replaced by zeros.

Examples

na.zero(c(NA, 1, NA, 2))

This function normalizes the values in a vector to the range [new_min, new_max] based on their original range [old_min, old_max].

Description

This function normalizes the values in a vector to the range [new_min, new_max] based on their original range [old_min, old_max].

Usage

normalize(x_vector, old_min, old_max, new_min, new_max)

Arguments

Value

A numeric vector with the normalized values.

Examples

normalize(c(1, 2, 3, 4, 5), 1, 5, 0, 1)

Ensure input is not empty

Description

Stops execution if x is NULL, empty, or contains only NAs.

Usage

not_empty(x, msg = "Input must not be empty.")

Arguments

Value

Invisible TRUE if valid.

Negate %in% membership

Description

Negate %in% membership

Usage

not_in(x, y)

x %!in% y

Arguments

Value

Logical vector indicating non-membership.

Convert Windows paths to R-friendly format

Description

Convert Windows paths to R-friendly format

Usage

pathPrep(path = "clipboard", read_fn = NULL, write_fn = NULL)

Arguments

Value

A normalized path string.

Calculation based on Rosenthal's formula (1994). N stands for the number of measurements. Necessary command:

Description

Calculation based on Rosenthal's formula (1994). N stands for the number of measurements. Necessary command:

Usage

rFromNPAV(pvalue, N)

Arguments

Value

Invisibly returns a list with components:

• r: effect size as a numeric scalar.

• z: corresponding z-statistic.

• text: LaTeX-formatted character string that is also sent to the console.

Examples

rFromNPAV(0.02, N = 180)

Calculation based on Rosenthal's formula (1994). N stands for the number of measurements.

Description

Calculation based on Rosenthal's formula (1994). N stands for the number of measurements.

Usage

rFromWilcox(wilcoxModel, N)

Arguments

Value

Invisibly returns a list with components:

• r: effect size as a numeric scalar.

• z: corresponding z-statistic.

• text: character string that is also sent to the console.

Examples

set.seed(1)
d <- data.frame(
  group = rep(c("A", "B"), each = 10),
  value = rnorm(20)
)
w <- stats::wilcox.test(value ~ group, data = d, exact = FALSE)
rFromWilcox(w, N = nrow(d))

rFromWilcoxAdjusted

Description

rFromWilcoxAdjusted

Usage

rFromWilcoxAdjusted(wilcoxModel, N, adjustFactor)

Arguments

Value

Invisibly returns a list with components:

• r: adjusted effect size as a numeric scalar.

• z: adjusted z-statistic.

• text: character string that is also sent to the console.

Examples

set.seed(1)
d <- data.frame(
  group = rep(c("A", "B"), each = 10),
  value = rnorm(20)
)
w <- stats::wilcox.test(value ~ group, data = d, exact = FALSE)
rFromWilcoxAdjusted(w, N = nrow(d), adjustFactor = 2)

Recommend a principled analysis for one outcome

Description

Works out, from the data alone, which statistical model is appropriate for a given outcome and set of predictors, and – crucially – why. The decision follows a transparent three-question tree:

1. What is the outcome's measurement scale? (via classify_outcome(): continuous, ordinal, binary, count, nominal.) This fixes the model family.

2. Are the observations independent or clustered? A repeated-measures / clustered design (a cluster id is supplied, or design = "within") needs random effects, i.e. a mixed model.

3. For a continuous outcome, do the parametric assumptions hold? Group-wise normality (Shapiro–Wilk) and, for between-subjects designs, homogeneity of variance (Levene) decide between a parametric test and a non-parametric / rank-based alternative.

Usage

recommend_test(
  data,
  outcome,
  predictors = NULL,
  cluster = NULL,
  design = c("auto", "between", "within"),
  outcome_type = c("auto", "continuous", "ordinal", "binary", "count", "nominal"),
  ordinal_max_levels = 7L
)

recommend_analysis(
  data,
  outcome,
  predictors = NULL,
  cluster = NULL,
  design = c("auto", "between", "within"),
  outcome_type = c("auto", "continuous", "ordinal", "binary", "count", "nominal"),
  ordinal_max_levels = 7L
)

Arguments

Details

The recommendation therefore ranges over ordinary ANOVA / t-tests, rank-based methods (Kruskal–Wallis + Dunn, Wilcoxon, the Aligned Rank Transform, nparLD), generalized linear models, cumulative link models, and their mixed-model counterparts – linear mixed models (LMM), generalized linear mixed models (GLMM, lme4/glmmTMB) and cumulative link mixed models (CLMM, ordinal).

Value

An object of class "colley_recommendation" (a list) with components including outcome_type, clustered, family, recommendation (human-readable label), model_function (the R function to call, e.g. "ordinal::clmm"), reporter (the matching colleyRstats reporter), fit_call (a ready-to-edit call as a string), alternatives, rationale, and methods_text (an APA-style sentence). A print method summarises it.

Examples

set.seed(1)
d <- data.frame(
  id    = factor(rep(1:20, each = 3)),
  cond  = factor(rep(c("A", "B", "C"), times = 20)),
  score = rnorm(60),
  rating = factor(sample(1:5, 60, TRUE), ordered = TRUE)
)
# Ordinal outcome measured repeatedly within subject -> CLMM
recommend_test(d, outcome = "rating", predictors = "cond", cluster = "id")
# Continuous, between-subjects -> ANOVA or its rank-based fallback
recommend_test(d, outcome = "score", predictors = "cond")

Flag suspicious survey responses via the Response Entropy Index (REI)

Description

This function takes a data frame, optional header information, variables to consider, and a range for a Likert scale. It then calculates the Response Entropy Index (REI) and flags suspicious entries based on percentiles. Note that no rows are removed; entries are only flagged via the Suspicious column.

Usage

remove_outliers_REI(df, header = FALSE, variables = "", range = c(1, 5))

Arguments

Details

Missing responses are ignored when tallying answers. Responses outside the declared Likert range trigger a warning (they often indicate mis-coded data) but are still included in the REI computation.

For more information on the REI method, refer to: Response Entropy Index Method

Value

A data frame with calculated REI, percentile, and a 'Suspicious' flag.

Examples

df <- data.frame(var1 = c(1, 2, 3), var2 = c(2, 3, 4))
result <- remove_outliers_REI(df, TRUE, "var1,var2", c(1, 5))

Generate the Latex-text based on the ARTool (see https://github.com/mjskay/ARTool). The ART result must be piped into an anova(). Only significant main and interaction effects are reported. P-values are rounded for the third digit. Attention: Effect sizes are not calculated! Attention: the independent variables of the formula and the term specifying the participant must be factors (i.e., use as.factor()).

Description

To easily copy and paste the results to your manuscript, the following commands must be defined in Latex: \newcommand{\F}[3]{$F({#1},{#2})={#3}$} \newcommand{\p}{\textit{p=}} \newcommand{\pminor}{\textit{p$<$}}

Usage

reportART(
  model,
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

report_art(
  model,
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("ARTool", quietly = TRUE)) {
  set.seed(123)

  main_df <- data.frame(
    tlx_mental = stats::rnorm(80),
    Video      = factor(rep(c("A", "B"), each = 40)),
    gesture    = factor(rep(c("G1", "G2"), times = 40)),
    eHMI       = factor(rep(c("On", "Off"), times = 40)),
    UserID     = factor(rep(1:20, each = 4))
  )

  art_model <- ARTool::art(
    tlx_mental ~ Video * gesture * eHMI +
      Error(UserID / (gesture * eHMI)),
    data = main_df
  )

  model_anova <- stats::anova(art_model)
  reportART(model_anova, dv = "mental demand")
}

Report significant ART contrasts (art.con) as LaTeX text

Description

Companion to reportDunnTest() for aligned-rank-transform (ART) models. It extracts the significant pairwise comparisons produced by ARTool::art.con() (an emmeans contrast grid), computes the mean and standard deviation of the groups involved from the raw data, and prints LaTeX-formatted sentences.

Usage

reportArtCon(
  ac,
  data,
  iv = "testiv",
  dv = "testdv",
  paired = FALSE,
  id = NULL,
  sink_to = NULL
)

report_art_con(
  ac,
  data,
  iv = "testiv",
  dv = "testdv",
  paired = FALSE,
  id = NULL,
  sink_to = NULL
)

Arguments

Details

The p-values are taken as-is from the contrast object, i.e. they are already adjusted by whatever adjust was passed to art.con() (e.g. "holm"). The effect size is the rank-biserial correlation computed from the raw data. ART is most often used for within-subjects designs; pass paired = TRUE together with id (the subject column) to obtain the paired rank-biserial effect size.

Attention: ac must be a pairwise contrast over a single factor iv (e.g. art.con(model, ~ interaction_mode, adjust = "holm")).

Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("ARTool", quietly = TRUE) &&
  requireNamespace("emmeans", quietly = TRUE)) {
  set.seed(123)
  n <- 20
  df <- data.frame(
    UserID = factor(rep(seq_len(n), times = 3)),
    mode   = factor(rep(c("Hand", "Eye", "Both"), each = n)),
    prime  = factor(rep(rep(c("A", "B"), each = n / 2), times = 3))
  )
  df$score <- as.numeric(df$mode) * 2 + stats::rnorm(nrow(df))

  m  <- ARTool::art(score ~ mode * prime + Error(UserID / mode), data = df)
  ac <- ARTool::art.con(m, ~ mode, adjust = "holm")
  reportArtCon(ac, data = df, iv = "mode", dv = "score", paired = TRUE, id = "UserID")
}

Report ART contrasts (art.con) as a LaTeX table. Customizable with sensible defaults. Companion to reportDunnTestTable().

Description

Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Usage

reportArtConTable(
  ac,
  data,
  iv = "testiv",
  dv = "testdv",
  paired = FALSE,
  id = NULL,
  orderByP = FALSE,
  numberDigitsForPValue = 4,
  latexSize = "small",
  orderText = TRUE,
  style = c("hline", "booktabs"),
  sink_to = NULL
)

report_art_con_table(
  ac,
  data,
  iv = "testiv",
  dv = "testdv",
  paired = FALSE,
  id = NULL,
  orderByP = FALSE,
  numberDigitsForPValue = 4,
  latexSize = "small",
  orderText = TRUE,
  style = c("hline", "booktabs"),
  sink_to = NULL
)

Arguments

Value

Invisibly returns the rendered LaTeX table as a string (or NULL when xtable is unavailable); the table is also printed.

Examples

if (requireNamespace("ARTool", quietly = TRUE) &&
  requireNamespace("emmeans", quietly = TRUE)) {
  set.seed(123)
  n <- 20
  df <- data.frame(
    UserID = factor(rep(seq_len(n), times = 3)),
    mode   = factor(rep(c("Hand", "Eye", "Both"), each = n)),
    prime  = factor(rep(rep(c("A", "B"), each = n / 2), times = 3))
  )
  df$score <- as.numeric(df$mode) * 2 + stats::rnorm(nrow(df))

  m  <- ARTool::art(score ~ mode * prime + Error(UserID / mode), data = df)
  ac <- ARTool::art.con(m, ~ mode, adjust = "holm")
  reportArtConTable(ac, data = df, iv = "mode", dv = "score", paired = TRUE, id = "UserID")
}

Report a cumulative link (mixed) model in LaTeX/APA style

Description

Reporter for ordinal proportional-odds models fitted with ordinal: cumulative link mixed models (ordinal::clmm) and their fixed-effects counterpart (ordinal::clm). Each location (predictor) effect is reported as an odds ratio – the multiplicative change in the odds of being in a higher outcome category for a one-unit increase in the predictor – with its confidence interval, z statistic and p-value. The threshold (cut-point) coefficients are omitted, as is conventional.

Usage

reportCLMM(
  model,
  dv = "Testdependentvariable",
  exponentiate = "auto",
  conf_level = 0.95,
  write_to_clipboard = FALSE,
  sink_to = NULL
)

report_clmm(
  model,
  dv = "Testdependentvariable",
  exponentiate = "auto",
  conf_level = 0.95,
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Details

The threshold (cut-point) parameters are never reported, so unlike reportGLMM() this reporter has no include_intercept argument.

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("ordinal", quietly = TRUE) &&
  requireNamespace("parameters", quietly = TRUE)) {
  m <- ordinal::clmm(rating ~ temp + contact + (1 | judge), data = ordinal::wine)
  reportCLMM(m, dv = "wine rating")
}

Report dunnTest as text. Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Description

Report dunnTest as text. Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Usage

reportDunnTest(d, data, iv = "testiv", dv = "testdv", sink_to = NULL)

report_dunn_test(d, data, iv = "testiv", dv = "testdv", sink_to = NULL)

Arguments

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("FSA", quietly = TRUE)) {
  # Use built-in iris data
  data(iris)

  # Dunn test on Sepal.Length by Species
  d <- FSA::dunnTest(Sepal.Length ~ Species,
    data   = iris,
    method = "holm"
  )

  # Report the Dunn test
  reportDunnTest(d,
    data = iris,
    iv   = "Species",
    dv   = "Sepal.Length"
  )
}

report Dunn test as a table. Customizable with sensible defaults. Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Description

report Dunn test as a table. Customizable with sensible defaults. Required commands in LaTeX: \newcommand{\padjminor}{\textit{p$_{adj}<$}} \newcommand{\padj}{\textit{p$_{adj}$=}} \newcommand{\rankbiserial}[1]{$r_{rb} = #1$}

Usage

reportDunnTestTable(
  d = NULL,
  data,
  iv = "testiv",
  dv = "testdv",
  orderByP = FALSE,
  numberDigitsForPValue = 4,
  latexSize = "small",
  orderText = TRUE,
  style = c("hline", "booktabs"),
  sink_to = NULL
)

report_dunn_test_table(
  d = NULL,
  data,
  iv = "testiv",
  dv = "testdv",
  orderByP = FALSE,
  numberDigitsForPValue = 4,
  latexSize = "small",
  orderText = TRUE,
  style = c("hline", "booktabs"),
  sink_to = NULL
)

Arguments

Value

Invisibly returns the rendered LaTeX table as a string (or NULL when xtable is unavailable); the table is also printed.

Examples

if (requireNamespace("FSA", quietly = TRUE)) {
  # Use built-in iris data
  data(iris)

  # Dunn test on Sepal.Length by Species
  d <- FSA::dunnTest(Sepal.Length ~ Species,
    data   = iris,
    method = "holm"
  )

  # Report the Dunn test
  reportDunnTestTable(d,
    data = iris,
    iv   = "Species",
    dv   = "Sepal.Length"
  )
}

Report a (generalized) linear mixed model in LaTeX/APA style

Description

Turns a fitted mixed model into ready-to-paste manuscript sentences, one per fixed-effect term, with the coefficient (or odds/incidence-rate ratio for non-Gaussian families), its confidence interval, the test statistic, and the p-value. Works with linear mixed models (lme4::lmer), generalized linear mixed models (lme4::glmer, glmmTMB::glmmTMB) and, for convenience, ordinary lm/glm fits. Coefficients are exponentiated automatically for binomial (odds ratios) and Poisson/negative- binomial (incidence-rate ratios) families.

Usage

reportGLMM(
  model,
  dv = "Testdependentvariable",
  exponentiate = "auto",
  include_intercept = FALSE,
  conf_level = 0.95,
  write_to_clipboard = FALSE,
  sink_to = NULL
)

report_glmm(
  model,
  dv = "Testdependentvariable",
  exponentiate = "auto",
  include_intercept = FALSE,
  conf_level = 0.95,
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Details

The reported statistics rely on the parameters package. The LaTeX output uses the \p/\pminor macros from latex_preamble().

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("lme4", quietly = TRUE) &&
  requireNamespace("parameters", quietly = TRUE)) {
  m <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy)
  reportGLMM(m, dv = "reaction time")
}

Report the mean and standard deviation of a dependent variable for all levels of an independent variable rounded to the 2nd digit.

Description

#' To easily copy and paste the results to your manuscript, the following commands must be defined in Latex: \newcommand{\m}{\textit{M=}} \newcommand{\sd}{\textit{SD=}}

Usage

reportMeanAndSD(data, iv = "testiv", dv = "testdv", sink_to = NULL)

report_mean_sd(data, iv = "testiv", dv = "testdv", sink_to = NULL)

Arguments

Value

Invisibly returns the formatted lines as a character vector; the text is also emitted via message().

Examples

example_data <- data.frame(Condition = rep(c("A", "B", "C"),
each = 10), TLX1 = stats::rnorm(30))

reportMeanAndSD(example_data, iv = "Condition", dv = "TLX1")

Generate the Latex-text based on the NPAV by Lüpsen (see https://www.uni-koeln.de/~luepsen/R/). Only significant main and interaction effects are reported. P-values are rounded for the third digit and partial eta squared values are provided when possible. Attention: the independent variables of the formula and the term specifying the participant must be factors (i.e., use as.factor()).

Description

Deprecated: reportNPAV() will be removed in a future release. Use reportART() with ARTool instead.

Usage

reportNPAV(
  model,
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Details

To easily copy and paste the results to your manuscript, the following commands must be defined in Latex: \newcommand{\F}[3]{$F({#1},{#2})={#3}$} \newcommand{\p}{\textit{p=}} \newcommand{\pminor}{\textit{p$<$}}

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

model <- data.frame(
  Df = c(1, 1, 10),
  `F value` = c(6.12, 5.01, NA),
  `Pr(>F)` = c(0.033, 0.045, NA),
  check.names = FALSE
)
rownames(model) <- c("Video", "gesture:eHMI", "Residuals")
reportNPAV(model, dv = "mental workload")

Report the model produced by nparLD. The model provided must be the model generated by the command 'nparLD' nparLD (see https://CRAN.R-project.org/package=nparLD).

Description

#' Only significant main and interaction effects are reported. P-values are rounded for the third digit and relative treatment effects (RTE) are included when available. Attention: the independent variables of the formula and the term specifying the participant must be factors (i.e., use as.factor()).

Usage

reportNparLD(
  model,
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

report_nparld(
  model,
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Details

#' To easily copy and paste the results to your manuscript, the following commands must be defined in Latex: \newcommand{\F}{\textit{F=}} \newcommand{\df}{\textit{df=}} \newcommand{\p}{\textit{p=}} \newcommand{\pminor}{\textit{p$<$}}

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

if (requireNamespace("nparLD", quietly = TRUE)) {
  # Small toy data set for nparLD
  set.seed(123)
  example_data <- data.frame(
    Subject = factor(rep(1:10, each = 3)),
    Time    = factor(rep(c("T1", "T2", "T3"), times = 10)),
    TLX1    = stats::rnorm(30, mean = 50, sd = 10)
  )

  # Fit nparLD model
  model <- nparLD::nparLD(
    TLX1 ~ Time,
    data        = example_data,
    subject     = "Subject",
    description = FALSE
  )

  # Report the nparLD result
  reportNparLD(model, dv = "TLX1")
  }

Analyze and report several dependent variables at once

Description

Runs analyze_and_report() for each dependent variable (e.g., all questionnaire scales of a study) and additionally returns a summary table of the omnibus tests with Holm-adjusted p-values across the dependent variables, plus – when patchwork is installed – a combined figure.

Usage

report_all(
  data,
  dvs,
  iv,
  design = c("between", "within"),
  labels = NULL,
  xlabels = NULL,
  plotType = "boxviolin",
  sink_dir = NULL
)

Arguments

Value

Invisibly returns a list with components results (named list of analyze_and_report() results), summary (data frame with one row per dv: method, statistic, p.value, and Holm-adjusted p.holm), and combined_plot (a patchwork figure, or NULL when patchwork is not installed).

Examples

out <- report_all(mtcars, dvs = c("mpg", "disp"), iv = "cyl")
out$summary

Report statistical details for ggstatsplot.

Description

Report statistical details for ggstatsplot.

Usage

reportggstatsplot(
  p,
  iv = "independent",
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

report_ggstatsplot(
  p,
  iv = "independent",
  dv = "Testdependentvariable",
  write_to_clipboard = FALSE,
  sink_to = NULL
)

Arguments

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

Examples

library(ggstatsplot)
library(dplyr)

# Generate a plot
plt <- ggbetweenstats(mtcars, am, mpg)

reportggstatsplot(plt, iv = "am", dv = "mpg")

Report significant post-hoc pairwise comparisons

Description

This function extracts significant pairwise comparisons from a ggstatsplot object, calculates the mean and standard deviation for the groups involved using the raw data, and prints LaTeX-formatted sentences reporting the results.

Usage

reportggstatsplotPostHoc(
  data,
  p,
  iv = "testiv",
  dv = "testdv",
  label_mappings = NULL,
  sink_to = NULL
)

report_ggstatsplot_posthoc(
  data,
  p,
  iv = "testiv",
  dv = "testdv",
  label_mappings = NULL,
  sink_to = NULL
)

Arguments

Value

Invisibly returns the reported sentence(s) as a character vector; the text is also emitted via message().

LaTeX Requirements

To easily copy and paste the results to your manuscript, the following commands (or similar) must be defined in your LaTeX preamble, as the function outputs commands taking arguments (e.g., ⁠\m{value}⁠):

  \newcommand{\m}[1]{\textit{M}=#1}
  \newcommand{\sd}[1]{\textit{SD}=#1}
  \newcommand{\padj}[1]{$p_{adj}=#1$}
  \newcommand{\padjminor}[1]{$p_{adj}<#1$}

Examples

library(ggstatsplot)
library(dplyr)

# Generate a plot
plt <- ggbetweenstats(mtcars, am, mpg)

# Report stats
reportggstatsplotPostHoc(
  data = mtcars,
  p = plt,
  iv = "am",
  dv = "mpg",
  label_mappings = list("0" = "Automatic", "1" = "Manual")
)

Reshape Excel Data Based on Custom Markers and Include Custom ID Column

Description

This function takes an Excel file with data in a wide format and transforms it to a long format. It includes a customizable "ID" column in the first position and repeats it for each slice. The function identifies sections of columns between markers that start with a user-defined string (default is "videoinfo") and appends those sections under the first section, aligning by column index.

Usage

reshape_data(
  input_filepath,
  sheetName = "Results",
  marker = "videoinfo",
  id_col = "ID",
  output_filepath
)

Arguments

Details

Relevant if you receive data in wide-format but cannot use built-in functionality due to naming (e.g., in LimeSurvey)

Value

None, writes the reshaped data to an Excel file specified by output_filepath.

Examples

if (requireNamespace(c("write_xlsx", "readxl"), quietly = TRUE)) {
  tmp_in  <- tempfile(fileext = ".xlsx")
  tmp_out <- tempfile(fileext = ".xlsx")

  # Minimal toy input that includes your required pieces:
  # an ID column and something that contains the marker value.
  toy <- data.frame(
    ID = c(1, 1, 2, 2),
    section = c("videoinfo", "videoinfo", "videoinfo", "videoinfo"),
    key = c("fps", "duration_s", "fps", "duration_s"),
    value = c(30, 12.3, 25, 9.8),
    stringsAsFactors = FALSE
  )

  writexl::write_xlsx(toy, tmp_in)

  reshape_data(
    input_filepath = tmp_in,
    marker = "videoinfo",
    id_col = "ID",
    output_filepath = tmp_out
  )

  out <- readxl::read_excel(tmp_out)
  print(out)
}

Save a plot with publication-ready defaults

Description

Saves a ggplot with sizes matching common two-column conference/journal layouts (e.g., ACM): a single-column figure is 3.33 in wide, a full-width figure 7 in. On Windows and Linux, PDFs are rendered with grDevices::cairo_pdf so that fonts are embedded and unicode glyphs survive; on macOS the default pdf device is used instead, because R's cairo on macOS is known to crash some setups (e.g., GitHub Actions runners) and the macOS device handles fonts well on its own.

Usage

save_paper_figure(
  plot = ggplot2::last_plot(),
  filename,
  columns = 1,
  width = NULL,
  height = NULL,
  dpi = 300,
  device = NULL
)

Arguments

Value

Invisibly returns filename.

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(factor(cyl), mpg)) +
  ggplot2::geom_boxplot()
save_paper_figure(p, file.path(tempdir(), "cyl-mpg.pdf"), columns = 1)

Generating the sum and adding a crossbar.

Description

Generating the sum and adding a crossbar.

Usage

stat_sum_df(fun, geom = "crossbar", ...)

Arguments

Value

A ggplot2 layer that can be added to a ggplot object.

Examples

  # Simple summary function: use the mean as y, ymin, and ymax
  mean_fun <- function(x) {
    m <- mean(x, na.rm = TRUE)
    data.frame(y = m, ymin = m, ymax = m)
  }

  ggplot2::ggplot(mtcars, ggplot2::aes(x = factor(cyl), y = mpg)) +
    stat_sum_df(mean_fun)

Write colleyRstats.sty into a project (for Overleaf)

Description

Copies the colleyRstats LaTeX macro package next to your manuscript so the report output compiles with a single \usepackage{colleyRstats} – no need to paste latex_preamble() into the preamble. Upload the written colleyRstats.sty to your Overleaf project (or keep it in the same folder as main.tex).

Usage

use_colleyrstats_sty(dir = ".", overwrite = FALSE)

Arguments

Value

Invisibly, the path to the written .sty file.

Examples

use_colleyrstats_sty(tempdir(), overwrite = TRUE)