Package {oes}

Type: Package
Title: Optimal Effect-Size-Based Y-Axis Ranges
Version: 1.0.0
Description: Calculates effect-size-informed y-axis recommendations for visualizations of independent, repeated-measures, and mixed designs. Summarizes selected error bars, estimates conditional standardized contrasts, and generalizes range-expansion rules using constants from single-factor, two-level studies of Cohen's d. Recommendations beyond that studied setting have not been empirically validated. Provides numerical results and 'ggplot2' visualizations, including summary plots and preservation of supplied plot layouts. Confidence-interval adjustment options follow the distinctions in Cousineau (2017) <doi:10.5709/acp-0214-z>, including difference adjustment and combined repeated-measures adjustment. Within-subject base intervals use the normalization of Cousineau (2005) <doi:10.20982/tqmp.01.1.p042> with the bias correction of Morey (2008) <doi:10.20982/tqmp.04.2.p061>. Correlation-only intervals and intervals with both adjustments are separate options. These references support confidence-interval construction, not the range-expansion calibration.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: dplyr (≥ 1.0.0), ggplot2 (≥ 4.0.0), rlang (≥ 1.0.0), rstatix (≥ 0.7.2), stats, utils
Suggests: ggsci, testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-10-09 15:10:21 UTC; root
Author: Shuo Zang ORCID iD [aut, cre, cph] (affiliation: School of Psychology, University of Ottawa), Denis Cousineau [aut, cph] (affiliation: School of Psychology, University of Ottawa)
Maintainer: Shuo Zang <zshuo070@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-21 14:00:02 UTC

oes: Optimal Effect-Size-Based Y-Axis Ranges

Description

Compute effect-size-informed y-axis recommendations and display them with mean/error-bar plots or existing ggplot objects. Calibration constants come from single-factor, two-level comparisons. The implementation supports broader between-subject, within-subject, and mixed factorial designs as computational generalizations.

Details

optimal_graph is the package's sole exported function. Use it for graphical and text output, or request detail = TRUE with graph output and inspect the returned oes component for numeric limits and calculation metadata. Calculation helpers are internal. Recommendations depend on the specified design and effect-size method; explicitly identify repeated measurements and participant IDs.

Confidence-interval options follow the distinctions in Cousineau (2017). Difference adjustment multiplies half-widths by \sqrt{2} (Equation 3). Repeated-measures base intervals use Cousineau's (2005) normalization and Morey's (2008) bias correction. The separate "ci95_corr" option returns these base intervals without \sqrt{2} and is not the 2017 article's combined comparative construction. "ci95_dif_corr" adds \sqrt{2}, combining the adjustments described in Equation 5b. "se" and "sd" use one standard error or standard deviation. These sources support CI construction; the OES expansion rule and calibration constants come from the effect-size manuscript.

Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization (Shuo Zang and Denis Cousineau, 2026, unpublished manuscript) studied single-factor, two-level comparisons across different populations and sample sizes, focusing on Cohen's d. Broader independent, repeated-measures, and mixed factorial support does not constitute empirical validation of the generalized y-axis recommendations. Hedges' g, paired dz, multi-factor maximum-effect selection, and generalized ER use beyond the studied comparisons are unvalidated extensions. Alternative base ranges are exploratory.

The parameter a is taken directly from the effect-size study: 5.723 for X \geq 0.8, 1.575 for 0.5 \leq X < 0.8, and 0.254 for 0.2 \leq X < 0.5. These values may change in later versions as further evidence becomes available. See optimal_graph for the exact implemented expansion, pooling, and fallback rules.

A separate methods paper is planned to explain the package's derivation from the effect-size study. It is not yet published; the package does not supply a citation to that planned paper.

Version 1.0.0 is the first public package version, based on the V1.8 development implementation. The code is available under the MIT license. Run citation("oes") for the software citation.

Public data resources

The effect-size manuscript is associated with Shuo Zang and Denis Cousineau's 2025 OSF resource, Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization, licensed under CC BY 4.0: doi:10.17605/OSF.IO/DRCTA. This DOI identifies the OSF resource, not a published-paper or software DOI.

The supplied Study4_long.csv example data come from Shuo Zang and Denis Cousineau's 2025 OSF project, “When Error Bars Fail to Correct Misleading Charts: Judgments of Lower y-axis Truncation across Layouts and Audiences”, under CC BY 4.0. The project and source-file links are doi:10.17605/OSF.IO/DTYBF and https://osf.io/dtybf/files/ebsh5. This is the error-bar project, not the effect-size calibration dataset. The package's self-contained examples and tests do not download these resources or require their files.

Author(s)

Shuo Zang and Denis Cousineau, School of Psychology, University of Ottawa. Maintainer: Shuo Zang zshuo070@gmail.com. Shuo Zang's ORCID: https://orcid.org/0009-0000-4387-8145.

References

Zang, S., and Cousineau, D. (2026). Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization. Unpublished manuscript.

Cousineau, D. (2017). Varieties of confidence intervals. Advances in Cognitive Psychology, 13(2), 140–155. doi:10.5709/acp-0214-z

Cousineau, D. (2005). Confidence intervals in within-subject designs: A simpler solution to Loftus and Masson's method. Tutorials in Quantitative Methods for Psychology, 1(1), 42–45. doi:10.20982/tqmp.01.1.p042

Morey, R. D. (2008). Confidence intervals from normalized data: A correction to Cousineau (2005). Tutorials in Quantitative Methods for Psychology, 4(2), 61–64. doi:10.20982/tqmp.04.2.p061

Internal Calculation Helper for Effect-Size-Based Y-Axis Ranges

Description

Internal, unexported calculation helper used by optimal_graph. Users should call optimal_graph(detail = TRUE) and inspect the returned oes component for numerical limits and metadata. Compute an Optimal Effect Size (OES) y-axis recommendation from a factorial design, with optional calculation details. The implementation uses constants from a single-factor, two-level empirical calibration; broader factorial and repeated-measures applications are computational generalizations.

Usage

oes(
  data, DV, within = NULL, between = NULL, pooled = TRUE,
  error_bar = c("ci95", "ci95_dif", "ci95_corr", "ci95_dif_corr", "se", "sd"),
  range_type = c("dp", "quantile", "data"), id = NULL,
  effect = c("d", "g"), measurement_range = NULL,
  verbose = TRUE, detail = FALSE
)

Arguments

data

A data frame of raw responses, or one row per design cell. For summary input, DV identifies the cell mean; optional n, sd, and se columns describe cell variability. Raw data are required to estimate the maximum effect in this version.

DV

Response column, supplied as a bare name or character string.

within

Within-subject factor names, as bare names or a character vector. Use c(...) for multiple factors. Default NULL.

between

Between-subject factor names, with the same syntax as within. At least one factor must be supplied.

pooled

Whether error bars use pooled rather than cell-specific variability. The OES expansion always uses a single pooled variability estimate, regardless of this argument.

error_bar

Error-bar method. "ci95" uses ordinary 95 percent confidence intervals; "ci95_dif" multiplies their half-widths by \sqrt{2}. "ci95_corr" uses Cousineau–Morey correlation-adjusted base intervals without \sqrt{2}; "ci95_dif_corr" also applies the \sqrt{2} multiplier. "se" and "sd" use one standard error and one standard deviation, respectively.

range_type

Base range before expansion: "dp" uses the outer error-bar endpoints; "quantile" uses the 2nd and 98th response percentiles; "data" uses the measurement or observed response range. The latter two choices are exploratory.

id

Participant ID column, as a bare name or character string. Required for paired within-subject effects and correlation-adjusted CIs.

effect

"d" uses Cohen's d for between-subject contrasts and paired Cohen's dz for within-subject contrasts. "g" applies Hedges' correction to between-subject contrasts only; within-subject contrasts still use dz. Recommendations using g or paired dz have not been empirically validated; see the evidence and limitations section.

measurement_range

Optional numeric vector c(min, max) giving a finite, strictly increasing theoretical response range. Otherwise the observed range is used. This supplies the "data" base range and the fallback range. It does not clamp OES recommendations.

verbose

Whether to emit optional methodological and fallback warnings. Errors are not suppressed.

detail

If FALSE, return limits only. If TRUE, return calculation details in an object of class oes_result.

Details

The effect search compares levels of each factor while conditioning on the other factors. Within-subject comparisons match observations by participant ID. Specify the experimental design explicitly; grouping variables alone do not identify repeated measurements.

Between-subject contrasts use rstatix::cohens_d(var.equal = FALSE). Their standardized mean difference divides by \sqrt{(s_1^2 + s_2^2)/2}, even when group sample sizes differ; it does not use an n-weighted two-group SD. Hedges' g uses the correction implemented by rstatix. This contrast denominator is separate from the degrees-of-freedom-weighted pooled cell SD used for ER variability.

For maximum absolute effect X \geq 0.20, the expansion on each side is ER = s_p/(X + a), where s_p is pooled within-cell SD for ordinary error bars or pooled transformed SD for Cousineau–Morey intervals. The parameter a uses the inherited calibration constants described below: 5.723 for X \geq 0.8, 1.575 for 0.5 \leq X < 0.8, and 0.254 for 0.2 \leq X < 0.5. These values are retained in this version and may change in later versions as further evidence becomes available. If X is unavailable or smaller than 0.20, the measurement or observed range is returned directly. The default range_type = "dp" and effect = "d" retain the calibration's method choices; selecting them does not establish empirical validity for every supported design. The output phrase “calibrated OES expansion” refers to use of the inherited formula and constants, not to empirical validation of all supported designs or effect estimators.

Correlation-adjusted intervals require raw data, valid participant IDs, at least one within-subject factor, at least two repeated-measures conditions per between-subject stratum, complete within-participant condition profiles, and at least two participants per stratum. Duplicate participant-condition responses are averaged first. Their t critical value uses n - 1 degrees of freedom for both pooling settings. Confidence-interval options follow the distinctions in Cousineau (2017). Difference adjustment multiplies half-widths by \sqrt{2} (Equation 3). Repeated-measures base intervals use Cousineau's (2005) normalization and Morey's (2008) bias correction. The separate "ci95_corr" option returns these base intervals without \sqrt{2} and is not the 2017 article's combined comparative construction. "ci95_dif_corr" adds \sqrt{2}, combining the adjustments described in Equation 5b. "se" and "sd" use one standard error or standard deviation. These sources support CI construction; the OES expansion rule and calibration constants come from the effect-size manuscript.

Value

With detail = FALSE, a one-row data frame with lower and upper. With detail = TRUE, a list of class oes_result containing range (that data frame), res (cell summaries and error bars), dp (maximum absolute effect), effect_info, effect_table (conditional comparisons), pooled_sd, ER, sd_info, error_bar_info, range_info, L, U, and args. On fallback, ER is NA and L/U are the final fallback bounds; otherwise they are the base bounds before expansion. The range_info$calibrated flag is TRUE exactly when range_type = "dp", including on fallback. It identifies the original base-range choice, not empirical validation of a generalized design, effect estimator, or recommendation.

Evidence and limitations

Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization (Shuo Zang and Denis Cousineau, 2026, unpublished manuscript) studied single-factor, two-level comparisons across different populations and sample sizes, focusing on Cohen's d. The package's support for broader independent, repeated-measures, and mixed factorial designs is a computational generalization of that work, not empirical validation of those generalized y-axis recommendations.

Recommendations using Hedges' g, paired Cohen's dz, multi-factor maximum-effect selection, or the generalized ER rule beyond the studied comparisons remain unvalidated extensions. Alternative base ranges "quantile" and "data" are also exploratory. Software tests verify implemented calculations and behavior; they do not validate perceptual outcomes for these extensions.

A separate methods paper is planned to explain the package's derivation from the effect-size study. The planned methods paper is not yet published, and no bibliographic citation for it is included here.

References

Zang, S., and Cousineau, D. (2026). Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization. Unpublished manuscript. The associated OSF resource (Zang and Cousineau, 2025) is licensed under CC BY 4.0: doi:10.17605/OSF.IO/DRCTA. This is the resource DOI, not a published-paper or software DOI.

Cousineau, D. (2017). Varieties of confidence intervals. Advances in Cognitive Psychology, 13(2), 140–155. doi:10.5709/acp-0214-z

Cousineau, D. (2005). Confidence intervals in within-subject designs: A simpler solution to Loftus and Masson's method. Tutorials in Quantitative Methods for Psychology, 1(1), 42–45. doi:10.20982/tqmp.01.1.p042

Morey, R. D. (2008). Confidence intervals from normalized data: A correction to Cousineau (2005). Tutorials in Quantitative Methods for Psychology, 4(2), 61–64. doi:10.20982/tqmp.04.2.p061

See Also

optimal_graph

Plot or Describe an Effect-Size-Based Y-Axis Recommendation

Description

Create a mean and error-bar plot, apply recommended y-axis limits to an existing ggplot, or return a text description of the recommendation. Broader factorial and repeated-measures uses generalize an empirical calibration of single-factor, two-level comparisons.

Usage

optimal_graph(
  plot = NULL, data = NULL, DV = NULL,
  layout = c("summary", "original"), pooled = TRUE,
  error_bar = c("ci95", "ci95_dif", "ci95_corr", "ci95_dif_corr", "se", "sd"),
  range_type = c("dp", "quantile", "data"), id = NULL,
  within = NULL, between = NULL, effect = c("d", "g"),
  measurement_range = NULL, output = c("graph", "y_axis_limit"),
  override_existing_limits = FALSE, verbose = TRUE, detail = FALSE
)

Arguments

plot

Optional ggplot object. If data and DV are also supplied, they drive calculations and the plot supplies the graphical layout. Otherwise accessible source data and mapped columns are used.

data

Optional data frame of raw responses, or one row per design cell. For summary input, DV identifies the cell mean; optional n, sd, and se columns describe cell variability. Raw data are required to estimate the maximum effect in this version.

DV

Response column, as a bare name or character string. Required with explicit data; otherwise inferred from the plot y mapping.

layout

"summary" rebuilds a mean and error-bar plot; "original" retains the supplied plot layers. Without a supplied plot, a summary plot is produced for either choice.

pooled

Whether error bars use pooled variability. OES expansion always uses a single pooled SD, regardless of this setting.

error_bar

One of ordinary 95 percent CIs ("ci95"), difference-adjusted CIs ("ci95_dif"), Cousineau–Morey CIs without the difference multiplier ("ci95_corr"), both adjustments ("ci95_dif_corr"), one standard error ("se"), or one standard deviation ("sd"). Difference adjustment multiplies half-widths by \sqrt{2}. Correlation-adjusted methods require raw data, within-subject factors, and valid participant IDs.

range_type

"dp" uses error-bar endpoints as the base range. Exploratory alternatives "quantile" and "data" use the 2nd–98th percentile or measurement/observed range.

id

Participant ID column, as a bare name or character string. Required for paired effects and correlation-adjusted intervals.

within

Within-subject factor names, as bare names or a character vector, with c(...) for multiple factors. Default NULL.

between

Between-subject factor names, using the same syntax. If neither design argument is supplied, eligible categorical data columns or detected plot factors are treated as between-subject factors.

effect

"d" for between-subject Cohen's d and paired within-subject dz. Exploratory "g" applies Hedges' correction to between-subject contrasts only. Neither g-based nor paired dz-based recommendations have been empirically validated; see the evidence and limitations section.

measurement_range

Optional numeric c(min, max) giving finite, strictly increasing theoretical bounds. Used for the "data" base range and fallback; otherwise the observed response range is used. This is not a clipping restriction.

output

"graph" returns a plot; "y_axis_limit" returns a character string describing calculations and limits.

override_existing_limits

Whether to replace explicit y-axis limits already present in plot. With the default FALSE, a supplied plot with explicit limits is retained, even when a summary layout was requested. With TRUE, the recommended limits replace existing limits. For original-layout output, existing y-scale limits are cleared before the recommended coordinate limits are applied; the rest of the scale configuration is preserved and the supplied graph is unmodified. Text output still reports the recommendation.

verbose

Whether to emit optional OES messages and warnings. Errors and all underlying ggplot warnings are not suppressed.

detail

For graph output, return a list containing the plot and calculation details rather than the plot alone. Does not change the character return type of output = "y_axis_limit".

Details

Always specify within, between, and id for repeated measurements or mixed designs: plot aesthetics cannot establish whether measurements come from the same participant.

The effect search compares levels of each factor while conditioning on the other factors. Within-subject comparisons match observations by ID. Between-subject contrasts use rstatix::cohens_d(var.equal = FALSE), with denominator \sqrt{(s_1^2 + s_2^2)/2} even when group sample sizes differ, rather than an n-weighted two-group SD. Hedges' g uses rstatix's implemented correction. This contrast denominator is separate from the degrees-of-freedom-weighted pooled cell SD used for ER variability.

For maximum absolute effect X \geq 0.20, each side of the base range is expanded by ER = s_p/(X + a). Here s_p is pooled within-cell SD for ordinary error bars or pooled transformed SD for Cousineau–Morey intervals. This variability scale is pooled for both values of pooled. If X is unavailable or smaller than 0.20, the measurement or observed range is returned directly.

Correlation-adjusted intervals require raw data, valid participant IDs, at least one within-subject factor, at least two repeated-measures conditions per between-subject stratum, complete within-participant condition profiles, and at least two participants per stratum. Duplicate participant-condition responses are averaged first. The t critical value uses n - 1 degrees of freedom for both pooling settings. Confidence-interval options follow the distinctions in Cousineau (2017). Difference adjustment multiplies half-widths by \sqrt{2} (Equation 3). Repeated-measures base intervals use Cousineau's (2005) normalization and Morey's (2008) bias correction. The separate "ci95_corr" option returns these base intervals without \sqrt{2} and is not the 2017 article's combined comparative construction. "ci95_dif_corr" adds \sqrt{2}, combining the adjustments described in Equation 5b. "se" and "sd" use one standard error or standard deviation. These sources support CI construction; the OES expansion rule and calibration constants come from the effect-size manuscript.

Summary output uses mapped colour, fill, shape, and linetype to separate series, with an explicit group mapping taking priority. Fill supplies visible colours when colour is absent. Summary output rebuilds layers and does not preserve every styling choice in the original plot.

Graph output requires ggplot2 version 4.0.0 or later. Missing or means-only plot source data cannot establish an OES effect size. The function warns and may return the original plot or an observed-range fallback. Supply explicit raw data and design arguments in those cases.

Value

For output = "graph" and detail = FALSE, a ggplot object. With detail = TRUE, a list with plot and oes; oes is a list of class oes_result, or NULL when a recommendation cannot be calculated from the plot. Its fields are range (a one-row data frame with lower and upper), res (cell summaries and error bars), dp (maximum absolute effect), effect_info, effect_table (conditional comparisons), pooled_sd, ER, sd_info, error_bar_info, range_info, L, U, and args. On fallback, ER is NA and L/U are the final fallback bounds; otherwise they are the base bounds before expansion. range_info$calibrated is TRUE exactly when range_type = "dp", including on fallback. It identifies the original base-range choice, not empirical validity of a generalized design, effect estimator, or recommendation.

For output = "y_axis_limit", a character string, regardless of detail. Numerical metadata are accessed through the oes component of optimal_graph(..., detail = TRUE) with graph output; the underlying numerical helper is not exported.

Evidence and limitations

Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization (Shuo Zang and Denis Cousineau, 2026, unpublished manuscript) examined single-factor, two-level comparisons across different populations and sample sizes, focusing on Cohen's d. Support for broader independent, repeated-measures, and mixed factorial designs is computational; it does not establish the empirical validity of the generalized recommendations.

Hedges' g, paired dz, multi-factor maximum-effect selection, and generalized ER use beyond the studied comparisons are unvalidated extensions. range_type = "quantile" and range_type = "data" are exploratory alternatives. The default settings do not remove these design limitations.

The parameter a in ER = s_p/(X + a) is taken directly from the effect-size study: 5.723 for X \geq 0.8, 1.575 for 0.5 \leq X < 0.8, and 0.254 for 0.2 \leq X < 0.5. These constants may change in later versions with further evidence. Text mentioning “calibrated OES expansion” identifies the inherited formula and constants, not empirical validation of all designs or estimators. A separate methods paper explaining the derivation from the effect-size study is planned but is not yet published.

References

Zang, S., and Cousineau, D. (2026). Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization. Unpublished manuscript. The associated OSF resource (Zang and Cousineau, 2025) is licensed under CC BY 4.0: doi:10.17605/OSF.IO/DRCTA. This is the resource DOI, not a published-paper or software DOI.

Cousineau, D. (2017). Varieties of confidence intervals. Advances in Cognitive Psychology, 13(2), 140–155. doi:10.5709/acp-0214-z

Cousineau, D. (2005). Confidence intervals in within-subject designs: A simpler solution to Loftus and Masson's method. Tutorials in Quantitative Methods for Psychology, 1(1), 42–45. doi:10.20982/tqmp.01.1.p042

Morey, R. D. (2008). Confidence intervals from normalized data: A correction to Cousineau (2005). Tutorials in Quantitative Methods for Psychology, 4(2), 61–64. doi:10.20982/tqmp.04.2.p061

See Also

oes-package

Examples

dat <- data.frame(
  group = factor(rep(c("A", "B"), each = 6)),
  score = c(1, 2, 3, 2, 3, 4, 5, 6, 7, 6, 7, 8)
)
optimal_graph(data = dat, DV = score, between = group)
optimal_graph(data = dat, DV = score, between = group,
              output = "y_axis_limit")
result <- optimal_graph(data = dat, DV = score, between = group,
                        detail = TRUE)
result$oes$range
result$oes$effect_table
p <- ggplot2::ggplot(dat, ggplot2::aes(group, score, fill = group)) +
  ggplot2::geom_boxplot()
optimal_graph(p, layout = "original")