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)
Optimal Effect-Size-Based Y-Axis Ranges
Authors: Shuo Zang and Denis Cousineau, School of Psychology, University of Ottawa. Maintainer: Shuo Zang [email protected].
This package uses the V1.8 implementation with official version number 1.0.0. It computes numerical y-axis recommendations and applies them to ggplot2 visualizations. The package is undergoing release checks before publication.
Visualizing Standardized Effect Sizes Using the Framework of Graph Perception and Data Visualization, by Shuo Zang and Denis Cousineau (2026, unpublished manuscript), studied single-factor, two-level comparisons across different populations and sample sizes. The effect-size study focused on Cohen's d. Those studies do not establish empirical validity for every design and option supported by this package.
The package generalizes the calculation to independent, repeated-measures, and mixed designs, including multiple factors and more than two levels. These are computational extensions. The generalized ER calculation, selection of the largest conditional effect, paired Cohen's dz, and alternative Hedges' g option have not been empirically validated as OES recommendation rules beyond the effect-size study setting. Alternative base ranges are also exploratory. Passing software tests verifies implementation behavior; it does not establish the intended perceptual judgments in these additional settings.
The current expansion is ER = pooled_sd / (X + a), with a taken directly
from the effect-size study: 5.723 when X >= 0.8, 1.575 when 0.5 <= X < 0.8, and 0.254 when
0.2 <= X < 0.5. The constants are reused in the generalized calculation and
may be updated after further research. For unavailable effects or X < 0.2,
the implementation uses the measurement or observed range.
A separate methods paper is planned to explain how the package was derived and generalized from the effect-size study. It is not yet a published reference. The current methods guide documents the implementation, examples, and limitations for review.
Confidence-interval options follow the distinctions in Cousineau (2017),
Varieties of confidence intervals. The difference adjustment
(ci95_dif) multiplies ordinary CI half-widths by √2 (Equation 3).
Repeated-measures base intervals use Cousineau's (2005) normalization
and Morey's (2008) correction. The separate ci95_corr option returns
those base intervals without the √2 multiplier; it is not the combined
comparative construction in the 2017 article. The ci95_dif_corr option
adds √2, combining the two adjustments described in Equation 5b.
The se and sd options use one standard error or standard deviation.
These references support CI construction; the OES expansion rule and
calibration constants come from the effect-size manuscript:
Cousineau, D. (2017). Varieties of confidence intervals. Advances in Cognitive Psychology, 13(2), 140–155. https://doi.org/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. https://doi.org/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. https://doi.org/10.20982/tqmp.04.2.p061.
Extract the project ZIP and open oes/oes.Rproj in RStudio.
Use R >= 4.1.0. Install the runtime dependencies first:
install.packages(c("dplyr", "ggplot2", "rlang", "rstatix"))
The package requires ggplot2 >= 4.0.0. Optional ggsci supplies summary-plot
palettes. testthat is needed to run package tests.
From the parent directory of the extracted oes/ folder:
install.packages("oes", repos = NULL, type = "source")
library(oes)
Alternatively, install the supplied source archive using its actual path:
install.packages("oes_1.0.0.tar.gz", repos = NULL, type = "source")
d <- data.frame(
group = factor(rep(c("A", "B"), each = 5)),
score = c(1:5, 3:7)
)
result <- optimal_graph(data = d, DV = score, between = group, detail = TRUE)
result$plot
result$oes$range
optimal_graph(data = d, DV = score, between = group, output = "y_axis_limit")
optimal_graph() is the only exported function. It returns a graph or a
text recommendation; detail = TRUE also supplies numerical results under
result$oes. The calculation engine oes() and other helpers are internal.
See ?optimal_graph and the methods guide for design requirements.
Use oes to obtain recommended y-axis ranges and choose the graphing
workflow that suits your needs:
| Workflow | Recommendation |
|---|---|
| oes + superb | Use optimal_graph() to obtain the y-axis ranges, then use superb::superb() to generate graphs with different error-bar settings appropriate to the design and comparison purpose. Apply the recommended lower and upper limits to the resulting graph. |
| ggplot2 + oes | Build a custom graph with ggplot2, then use optimal_graph() with layout = "original" to apply the recommended y-axis range while retaining its layers and error bars. Supply the raw data and design arguments explicitly. |
| oes alone | Use optimal_graph() directly to generate a mean and error-bar graph with a recommended y-axis range, choosing from the package's supported error_bar options. |
With detail = TRUE, numerical limits are available in
result$oes$range$lower and result$oes$range$upper.
For an existing superb or ggplot2 graph, layout = "original" retains its
plotted layers; the default layout = "summary" rebuilds the summary graph.
Existing explicit y-axis limits are retained by default. With
override_existing_limits = TRUE, the recommended limits replace existing
limits. For original-layout output, OES clears existing y-scale limits before
applying its coordinate limits, preserving the rest of the scale configuration
and leaving the supplied graph unmodified.
Use the same raw data and experimental design for the range calculation and
the graph. For error-bar methods supported by oes, align the error-bar
and pooling settings with those used in the graph. The default
range_type = "dp" uses error-bar endpoints for its base bounds, so changing
those settings requires a corresponding range calculation.
superb is a separate package for the optional first workflow. Install it
separately with install.packages("superb"). See its
function documentation
and the framework paper:
Cousineau, D., Goulet, M.-A., & Harding, B. (2021). Summary plots with adjusted error bars: The superb framework with an implementation in R. Advances in Methods and Practices in Psychological Science, 4(3). https://doi.org/10.1177/25152459211035109.
citation("oes")
toBibtex(citation("oes"))
Shuo Zang's ORCID: https://orcid.org/0009-0000-4387-8145.
Package code is licensed under MIT. LICENSE accompanies the source archive;
the project ZIP also includes the full license text in LICENSE.md.
The software citation is separate from the effect-size manuscript and its
associated OSF resource:
The DRCTA DOI identifies the effect-size OSF resource, not a published-paper or package DOI. The separate package-methods paper is planned; its citation can be added when its bibliographic details are finalized.
The supplied error-bar study example uses Study4_long.csv from a separate
public OSF resource:
The resource is When Error Bars Fail to Correct Misleading Charts: Judgments of Lower y-axis Truncation across Layouts and Audiences, by Shuo Zang and Denis Cousineau, hosted on OSF. The data are licensed under CC BY 4.0, separately from the MIT license for package code. See error-bar data provenance in the project ZIP. The ZIP includes an unmodified copy for the manual study example; the installable source archive excludes these development inputs.
This dataset demonstrates study-data usage. It does not validate the package's extensions beyond the effect-size study setting. Automated tests use self-contained data and do not access OSF or require the CSV.
The ZIP includes a development/ folder with the original V1.8 script,
standalone regression script, original supplied examples, and a corrected
manual error-bar Study 4B example, development/example-error-bar-study4b.R.
Historical scripts are retained as inputs; the
installed-package tests in tests/testthat/ are the automated suite.
The automated tests cover effect sizes, error bars, pooling, input handling,
fallbacks, plot grouping, layout preservation, and y-axis limits. Applicable
examples have been adapted to self-contained data; misleading design
examples and internal debugging calls are excluded from public tutorials.
Optional superb examples are outside the mandatory package tests.
After installing testthat, run the tests from the project directory:
testthat::test_dir("tests/testthat", stop_on_failure = TRUE)
Release checks across operating systems and CRAN-specific checks must be completed before publication.