| Title: | Utilities and Helpers for Single Case Experimental Design (SCED) using 'ggplot2' |
|---|---|
| Description: | Provides specialized visualization tools for Single-Case Experimental Design (SCED) research using 'ggplot2'. SCED studies are a crucial methodology in behavioral and educational research where individual participants serve as their own controls through carefully designed experimental phases. This package extends 'ggplot2' to create publication-ready graphics with professional phase change lines, support for multiple baseline designs, and styling functions that follow SCED visualization conventions. Key functions include adding phase change demarcation lines to existing plots and formatting axes with broken axis appearance commonly used in single-case research. |
| Authors: | Shawn Gilroy [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-1097-8366>) |
| Maintainer: | Shawn Gilroy <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.1.6 |
| Built: | 2026-05-22 05:54:17 UTC |
| Source: | https://github.com/miyamot0/ggsced |
Core exported function to facilitate the drawing of phase change lines atop a ggplot object. Primarily designed to be used *after* the plot is finalized, with the lines being the last element drawn at the highest z index (i.e., atop all elements).
ggsced(plt, legs, offs = NULL, print = TRUE, verbose = FALSE)ggsced(plt, legs, offs = NULL, print = TRUE, verbose = FALSE)
plt |
ggplot object as typically designed/printed in userspace |
legs |
list of 'legs' to be drawn |
offs |
mapping of lines that require minor offset |
print |
output result directly to graphical device (default = TRUE) |
verbose |
Optional ability to view process output (debugging primarily) |
Finalized figure with respective phase change lines embedded.
Optional helper class to prepare condition labels (e.g., Baseline, Intervention) based on the grouping of an existing ggplot object
ggsced_condition_labels(plt, y = NULL)ggsced_condition_labels(plt, y = NULL)
plt |
ggplot object |
y |
ordinate of respective label (Default = last tick from plot object) |
a data frame that can be used with a geom_text layer
Internal helper to pull respective panel parameters and assert validity.
ggsced_extract_domain(panel_params)ggsced_extract_domain(panel_params)
panel_params |
respective parameters of panel grob |
numeric vector specifying size in min-max units
Optional helper class to prepare facet labels (e.g., Participant names) based on the faceting of an existing ggplot object
ggsced_facet_labels(plt, y = 0, x = NULL)ggsced_facet_labels(plt, y = 0, x = NULL)
plt |
ggplot object |
y |
ordinate of respective label (typically very low or very high) |
x |
position on the x-axis (Default = last tick from plot object) |
a data frame that can be used with a geom_text layer
Honestly, a bit of a 'hackish' solution to extract grobs that are associated with data to be drawn. Probably fragile and specific to modern gg implementations, but probably the close we'll get. Subject to change.
ggsced_get_panels(ggplot_grobs)ggsced_get_panels(ggplot_grobs)
ggplot_grobs |
list of grobs prepared by ggplotGrob |
filtered list of grobs restricted to faceted levels
Internal helper class to draw a conventional x-axis per SCED publication suggestions.
ggsced_internal_x_axis(expansion = 0, lwd = 2, col = "black")ggsced_internal_x_axis(expansion = 0, lwd = 2, col = "black")
expansion |
Percentage of axis to pad (left/right) to break axis (Note: normalized parent units) |
lwd |
Width of axis line |
col |
Color of axis drawn (default = 'black') |
Rendering of customized x axis across facets
Internal helper class to draw a conventional y-axis per SCED publication suggestions.
ggsced_internal_y_axis(expansion = 0, lwd = 2, col = "black")ggsced_internal_y_axis(expansion = 0, lwd = 2, col = "black")
expansion |
Percentage of axis to pad (top/bottom) to break axis (Note: normalized parent units) |
lwd |
Width of axis line |
col |
Color of axis drawn (default = 'black') |
Rendering of customized y axis across facets
Grobs need to have unique names lest they get accidentally overwritten. This is a convenience naming function for the 'main' phase break within a facet level.
ggsced_name_dogleg(panel, index, n_leg)ggsced_name_dogleg(panel, index, n_leg)
panel |
name of the parent grob |
index |
index of the phase change in sequence |
n_leg |
leg in the phase change |
a name corresponding with unique phase-change grob element
Grobs need to have unique names lest they get accidentally overwritten. This is a convenience naming function for the 'lateral' part of a phase break within a facet level.
ggsced_name_dogleg_lateral(panel, index, n_leg)ggsced_name_dogleg_lateral(panel, index, n_leg)
panel |
name of the parent grob |
index |
index of the phase change in sequence |
n_leg |
leg in the phase change |
a name corresponding with unique phase-change grob element
Optional output function to support debugging (mainly for testing)
ggsced_output_console(msg, output)ggsced_output_console(msg, output)
msg |
Message to be output to console |
output |
Boolean to discern whether or not to output message |
Internal helper to discern exactly where a vertical would need to be placed within a specific grob (i.e., panel grob). Uses the domain and phase change location as a reference to convert to npc units for gtable and grid.
ggsced_scale_units(session_value, domain_size)ggsced_scale_units(session_value, domain_size)
session_value |
Session associated with phase-change line |
domain_size |
Total size of domain per panel specification |
A proportional value given value in a panel domain
This is a convenience element designed to support a more complete interpretation of SCED-specific style conventions through ggplot. Specifically, an axis is drawn with a specific manner of expansion to support the broken axis (i.e., non-connected x/y) expected of SCED-specific publication guidelines.
ggsced_style_x(expansion = 0, lwd = 2, col = "black")ggsced_style_x(expansion = 0, lwd = 2, col = "black")
expansion |
Percentage of axis to pad (left/right) to break axis (Note: normalized parent units) |
lwd |
Width of axis line |
col |
Color of axis drawn (default = 'black') |
Annotation to simulate a disconnected y-axis via expansion
This is a convenience element designed to support a more complete interpretation of SCED-specific style conventions through ggplot. Specifically, an axis is drawn with a specific manner of expansion to support the broken axis (i.e., non-connected x/y) expected of SCED-specific publication guidelines.
ggsced_style_y(expansion = 0, lwd = 2, col = "black")ggsced_style_y(expansion = 0, lwd = 2, col = "black")
expansion |
Percentage of axis to pad (top/bottom) to break axis (Note: normalized parent units) |
lwd |
Width of axis line |
col |
Color of axis drawn (default = 'black') |
Annotation to simulate a disconnected y-axis via expansion
This is data either extracted or included (with permission) to assist with illustrating and replicating the functionality of the package. Specifically, this data is used to illustrate conventions regarding a multiple probe design and how that may be constructed in this package.
Gilroyetal2015Gilroyetal2015
A data frame with 40 rows and 6 variables:
Participant name
Session number
Condition name
Responding rates
Phase number
Offset for phase line
<doi:https://doi.org/10.1016/j.rasd.2015.04.004>
Treatment data from Gilroy et al. (2021)
Gilroyetal2021Gilroyetal2021
A data frame with 69 rows and 7 variables:
Participant name
Session number
Functional analysis condition
Rates of responding
Reinforcer deliveries
Sequenced phase number
Offset of phase line
<doi:https://doi.org/10.1002/jaba.826>
This is a helper class to standardize drawing grobs
sced_phase_change_complex_lateral_grob(x0, x1, segment_name)sced_phase_change_complex_lateral_grob(x0, x1, segment_name)
x0 |
value corresponding to respective domain in npc units |
x1 |
value corresponding to respective domain in npc units |
segment_name |
name associated with object |
graphical object
This is a helper class to standardize drawing grobs
sced_phase_change_complex_lateral_post_grob(x, segment_name)sced_phase_change_complex_lateral_post_grob(x, segment_name)
x |
value corresponding to respective domain in npc units |
segment_name |
name associated with object |
graphical object
This is a helper class to standardize drawing grobs
sced_phase_change_complex_lateral_pre_grob(x, segment_name)sced_phase_change_complex_lateral_pre_grob(x, segment_name)
x |
value corresponding to respective domain in npc units |
segment_name |
name associated with object |
graphical object
This is a helper class to standardize drawing grobs
sced_phase_change_main_panel_grob(x, segment_name)sced_phase_change_main_panel_grob(x, segment_name)
x |
value corresponding to respective domain in npc units |
segment_name |
name associated with object |
graphical object
This is a helper class to standardize drawing grobs
sced_phase_change_simple_lateral_grob(x0, x1, segment_name)sced_phase_change_simple_lateral_grob(x0, x1, segment_name)
x0 |
value corresponding to respective domain in npc units |
x1 |
value corresponding to respective domain in npc units |
segment_name |
name associated with object |
graphical object