Type:	Package
Title:	Plot Function for Single-Case Data Frames
Version:	0.7.0
Date:	2026-03-29
Description:	Add-on for the 'scan' package that creates plots from single-case data frames ('scdf'). It includes functions for styling single-case plots, adding phase-based lines to indicate various statistical parameters, and predefined themes for presentations and publications. More information and in depth examples can be found in the online book "Analyzing Single-Case Data with R and 'scan" Jürgen Wilbert (2026) https://jazznbass.github.io/scan-Book/.
Depends:	R (≥ 4.1.0)
Imports:	ggplot2, grid, scan (≥ 0.61.0), stats, utils, rlang, cli
Suggests:	rmarkdown, knitr
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-03-29 13:06:05 UTC; wilbert
Author:	Juergen Wilbert [aut, cre]
Maintainer:	Juergen Wilbert <juergen.wilbert@uni-muenster.de>
Repository:	CRAN
Date/Publication:	2026-03-29 13:20:03 UTC

Single-Case Data Plots

Description

A collection of procedures for visualizing single-case data. It is an add-on package for the scan package.

Author(s)

Juergen Wilbert [aut, cre]

Check theme object

Description

Validates specific properties of a theme object.

Usage

.check_theme(theme)

Arguments

Value

The checked theme object.

Inherit parameter descriptions for scplot objects

Description

This is a dummy function that is not meant to be called directly. It is used to inherit parameter descriptions in other functions related to scplot objects.

Usage

.inherit_scplot(
  object,
  label,
  labels,
  color,
  size,
  linewidth,
  hjust,
  vjust,
  angle,
  width,
  face,
  linetype,
  shape,
  text,
  background,
  case,
  variable,
  point,
  line,
  ...
)

Arguments

Value

No return value.

Merge two theme elements

Description

Merge two theme elements

Usage

.merge_element(new, old)

Arguments

Value

A merged theme element.

Merge two theme lists

Description

Merges two theme lists, updating the old theme with new values from the new theme.

Usage

.merge_theme(new, old)

Arguments

Value

A merged theme list.

Convert relative size to absolute size

Description

Convert relative size to absolute size

Usage

.size(x, base)

Arguments

Value

Absolute size value.

Capitalize first letter of a string

Description

Capitalize first letter of a string

Usage

.upperfirst(x)

Arguments

Value

A character vector with first letter capitalized.

Throws an error

Description

This is a convenience wrapper for internal use.

Usage

abort(..., class = NULL, call = FALSE)

Arguments

Add an arrow to a scplot

Description

Draws an arrow between two points in the scplot.

Usage

add_arrow(
  object,
  case = 1,
  x0,
  y0,
  x1,
  y1,
  color = "black",
  angle = 30,
  length = 5,
  type = "open",
  ends = "last",
  linewidth = 0.7
)

Arguments

Details

The arrow is drawn from point ⁠(x0, y0)⁠ to point ⁠(x1, y1)⁠. The arrow head can be customized with the arguments angle, length, type, and ends. The angle argument specifies the angle of the arrow head, while length specifies the size of the arrow head. The type argument indicates whether the arrow head should be an open or closed triangle, and the ends argument specifies which ends of the line should have arrow heads (last, first, or both). The color and linewidth arguments control the appearance of the arrow line. Note that the length argument can be specified as a numeric value (in points) or as a unit object (e.g., unit(5, "points")).

Value

An object of class scplot (see scplot()) with added element lines.

Examples

data(exampleAB, package = "scan")
p1 <- scplot(exampleAB$Anja)  |>
  add_arrow(case = 1, 2, 70, 6, 55, color = "darkred")

Add grid to an scplot theme

Description

Adds grid line specifications to the theme of an scplot object.

Usage

add_grid(object, ...)

Arguments

Details

The function allows customization of grid lines by passing arguments similar to those used in element_line(), such as color, size, and linetype.

Value

An object of class scplot (seescplot()) with modified theme element to include the specified grid line properties.

See Also

element_line()

Examples

data(exampleAB, package = "scan")
p1 <- scplot(exampleAB$Anja)  |>
  set_theme("minimal")  |>
  add_grid(color = "grey70")

Add value labels to an scplot

Description

This function adds value labels to an existing scplot object. The labels display the values of a specified variable (default is .dvar, which typically represents the main variable being plotted). You can customize the position, rounding, text style, and background style of the labels.

Usage

add_labels(
  object,
  nudge_y = 5,
  nudge_x = 0,
  round = NULL,
  text = list(),
  background = list(),
  variable = ".dvar",
  padding = NULL
)

Arguments

Value

An object of class scplot (seescplot()) with added/changed element labels.

Add a legend to an scplot

Description

This function adds a legend to an scplot object. The legend can include entries for datalines, statlines, and phases. You can customize the position of the legend, as well as the text style for the title and text within the legend.

Usage

add_legend(
  object,
  labels = NULL,
  section_labels = c("Lines", "Phases"),
  position = "right",
  datalines = TRUE,
  statlines = TRUE,
  phases = TRUE,
  title = NULL,
  text = NULL,
  background = NULL
)

Arguments

Details

The position argument allows you to specify where the legend should be placed on the plot. You can also customize the text style for the title and text within the legend using the title and text arguments, respectively. The background argument allows you to set the background style of the legend. Deprecated argument: The labels argument is deprecated. Please set the label argument in the add_statline and set_dataline functions instead. The legend can be customized to include different sections for datalines, statlines, and phases. You can control which sections are included in the legend using the datalines, statlines, and phases arguments.

Value

An object of class scplot (seescplot()) with changed element legend.

Examples

data(exampleAB_add, package = "scan")
scplot(exampleAB_add) |>
  set_dataline("depression") |>
  add_statline("mean") |>
  add_legend()

scplot(exampleAB_add) |>
  set_dataline(label = "Pychological Wellbeing") |>
  set_dataline("depression", color = "darkblue", label = "Depression") |>
  add_statline("mean", label = "Wellbeing mean") |>
  add_statline("mean", variable = "depression", label = "Depression mean") |>
  set_phasenames(color = NA) |>
  set_panel(fill = c("lightblue", "grey80")) |>
  add_legend(
    position = "left",
    section_labels = c("Variables", "Section"),
    title = list(color = "brown", size = 10, face = 2),
    text = list(color = "darkgreen", size = 10, face = 2),
    background = list(color = "lightgrey")
  )

Add line to an scplot object

Description

Draws a line on the scplot. Either a horizontal line (hline), vertical line (vline), or a line defined by its start (x0, y0) and end (x1, y1) points can be drawn.

Usage

add_line(
  object,
  case = 1,
  x0 = NULL,
  y0 = NULL,
  x1 = NULL,
  y1 = NULL,
  hline = NULL,
  vline = NULL,
  color = "black",
  linewidth = 0.7,
  linetype = "solid"
)

Arguments

Value

An object of class scplot (seescplot()) with added element lines.

Examples

data(exampleAB, package = "scan")
p1 <- scplot(exampleAB$Anja)  |>
  add_line(hline = 70, color = "darkred") |>
  add_line(vline = 3, color = "blue") |>
  add_line(x0 = 1, y0 = 70, x1 = 4, y1 = 80, color = "green")

Add marks to an scplot object

Description

Marks specific points in an scplot object.

Usage

add_marks(
  object,
  case = 1,
  positions,
  color = "red",
  size = 1,
  shape = 1,
  variable = ".dvar"
)

Arguments

Details

Marks are visualized as points on top of the existing plot. Multiple marks can be added by calling add_marks() multiple times.

If positions is an object returned from an outlier analysis via outlier(), the corresponding outliers are marked. If positions is a list, marks are added for each case in the list. The variable argument specifies the variable on which the marks are applied. By default, the variable .dvar is used. If multiple cases are plotted, the case argument specifies for which case(s) the marks are added.

Value

An object of class scplot (see scplot()) with changed element marks.

Author(s)

Juergen Wilbert

Examples

library(scan)
p1 <- scplot(exampleA1B1A2B2$Moritz) |> add_marks(positions = c(1,5,10,14))
p1 <- scplot(Huber2014) |> add_marks(positions = outlier(Huber2014))

Add a ridge to an scplot object

Description

Adds a ridge element to an scplot object. Ridges are density plots displayed vertically along the y-axis, often used to show distributions of data points across different categories or groups.

Usage

add_ridge(object, color = "grey98", variable = ".dvar")

Arguments

Value

An object of class scplot (seescplot()) with changed element ridges.

Add a statline to an scplot object

Description

This function adds a statistical line or curve to an existing scplot object. Various statistical functions are available such as mean, median, min, max, quantile, standard deviation, moving average, and trend lines.

Usage

add_statline(
  object,
  stat = c("mean", "median", "min", "max", "quantile", "sd", "mad", "trend",
    "moving mean", "moving median", "loreg", "lowess", "loess", "trendA",
    "trendA theil-sen", "trendA bisplit", "trendA trisplit"),
  phase = NULL,
  color = NULL,
  linewidth = NULL,
  linetype = NULL,
  variable = NULL,
  label = NULL,
  segmented = NULL,
  case = NULL,
  ...
)

Arguments

Details

The phase argument defines the reference phase for some statistical functions (⁠"median", "mean", "min", "max", "quantile", "trend"⁠). The default is NULL which calculates and plots statistics for each phase separately. The arguments takes a numeric vector (phase number(s)) or a character vector (phase name(s)). When more than one phase is defines, statistics are based on the combined values of these phases. phase = all will select all phases. Various methods for a trend line exist that can be set with method argument: The default is based on an OLS regression, "theil-sen" on a nonparametric regression, and "bisplit" / "trisplit" are two median based approaches. Some of the functions defined in stat have additional arguments. The mean() function has a trim argument (e.g. trim = 0.1). quantile() has a proportion argument (e.g. prob = 0.75 for calculating the 75% quantile). ⁠moving mean⁠ and ⁠moving median⁠ have a lag argument (e.g. lag = 2). The local-regression curve function "lowess" (or "loreg") has a proportion argument (e.g. f = 0.5; see lowess()) and the local-regression curve function "loess" has a span argument (e.g. span = 0.75; see loess()).

Value

An object of class scplot (seescplot()) with changed element statlines.

Add test to an scplot object

Description

Adds a text element to an scplot object at specified coordinates.

Usage

add_text(
  object,
  label,
  case = 1,
  x,
  y,
  color = "black",
  size = 1,
  angle = 0,
  hjust = 0.5,
  vjust = 0.5,
  face = 1
)

Arguments

Value

An object of class scplot (seescplot()) with a changed texts element.

Add title and caption to an scplot object

Description

Adds title and caption elements to an scplot object.

Usage

add_title(object, label, ...)

add_caption(object, label, header = "Note:\n", ...)

Arguments

Details

The functions allow customization of title and caption text properties by passing arguments similar to those used in element_text(), such as family, face, colour, size, hjust, vjust, angle, lineheight, and margin.

Value

An object of class scplot (seescplot()) with changed title and caption elements.

Creates a ggplot2 object from an scplot() object

Description

as_ggplot() takes an scplot object as input and returns a ggplot2 object.

Usage

as_ggplot(scplot)

Arguments

Details

as_ggplot() is used directly when you want to return a ggplot2 object for further use with external ggplot functions. It is also used internally when printing an scplot object (see print.scplot()). The function processes the data and theme specifications from the scplot object and constructs a ggplot2 plot accordingly.

Value

A ggplot2 plot object.

Author(s)

Juergen Wilbert

See Also

scplot(), print.scplot()

Create a new scplot theme object

Description

new_theme() creates a new theme object for use with scplot.

extract_theme() extracts the theme from an existing scplot object, allowing users to reuse or modify the theme for other scplot visualizations.

Usage

new_theme()

extract_theme(object)

Arguments

Details

Themes control the overall appearance of scplot visualizations, including colors, fonts, line styles, and layout options. By creating a custom theme, users can ensure consistent styling across multiple plots and tailor the visualizations to their specific needs or branding requirements.

Value

An object of class scplot-theme which can be used with the set_theme() function.

Examples

data(exampleABC, package = "scan")
my_theme <- new_theme() |>
  set_panel(color = "red")  |>
  set_base_text(size = 12, color = "blue")  |>
  set_dataline(color = "darkred", linewidth = 2)
p1 <- scplot(exampleABC)  |> set_theme(my_theme)

Throws a message

Description

Messages can be shown with different levels of detail and as warnings. This is a convenience wrapper for internal use.

Usage

notify(..., type = "!", detail = 1, warning = FALSE)

Arguments

print.scplot - Print an scplot object

Description

Prints an scplot object by converting it to a ggplot2 object using as_ggplot().

Usage

## S3 method for class 'scplot'
print(x, ...)

Arguments

Value

Calls as_ggplot() to create a ggplot2 argument and prints it.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggplot2

element_line, element_point, element_rect, element_text, unit

Forest Plot for Random Effects of Mixed HPLM Models

Description

This function generates a forest plot for the random effects of a mixed hplm model.

Usage

## S3 method for class 'sc_hplm'
scplot(object, effect = "intercept", mark = "fixed", ci = 0.95, ...)

Arguments

Value

A forest plot displaying Tau-U effects.

Examples

model <- scan::hplm(scan::Leidig2018, random.slopes = TRUE)
scplot(model, effect = "level")

Plot Randomization Effects

Description

This function generates plots of randomization test results.

Usage

## S3 method for class 'sc_rand'
scplot(object, type = "hist", add_density_curve = TRUE, ...)

Arguments

Value

A plot displaying the results of the randomization test.

Examples

## Not run: 
res <- scan::rand_test(scan::exampleAB$Anja, limit = 1)
scplot(res, type = "hist")

scplot(res, type = "xy")

## End(Not run)

Plot Tau-U Effects Forest Plot

Description

This function generates a forest plot of Tau-U effects.

Usage

## S3 method for class 'sc_tauu'
scplot(object, effect = 1, ...)

Arguments

Value

A forest plot displaying Tau-U effects.

Examples

res <- scan::tau_u(scan::Leidig2018)
scplot(res, effect = 3)

Plot single-case data from a single-case data-frame

Description

This function provides a plot of a single-case or multiple single-cases. It takes a single-case data-frame (scdf) as input and returns an object of class scplot, which can be further customized using various functions provided in the package.

Usage

## S3 method for class 'scdf'
scplot(object, ...)

Arguments

Details

The function automatically extracts relevant information from the single-case data-frame, such as dependent variable, phase variable, and measurement time variable. It also sets default values for various plot elements, including data lines, statistical lines, ridges, marks, texts, and lines.

Value

An object of class scplot containing the single-case data (element scdf), and information about the plot style (element theme). This object can be further customized using various functions provided in the package.

Author(s)

Juergen Wilbert

See Also

set_dataline(), add_statline, set_theme()

Examples

data(exampleAB, package = "scan")
p1 <- scplot(exampleAB)
p2 <- scplot(exampleAB$Anja)
p3 <- scplot(exampleAB[c("Anja", "Berta")])
print(p1)

Random start position plot Plot of statistics for random phase B start positions

Description

Random start position plot Plot of statistics for random phase B start positions

Usage

scplot_rand(
  scdf,
  statistic = "Mean B-A",
  x_label = "Start phase B",
  color_label = "Compared to\nobserved",
  colors = c(Above = "coral3", Below = "aquamarine4", Observed = "#56B4E9", Equal =
    "black"),
  ...
)

Arguments

Examples

scplot_rand(scan::byHeart2011[1:5])

Set plot and panel background of an scplot object

Description

The set_background() function allows you to customize the plot background of an scplot object by specifying parameters such as fill color, border color, line width, and line type. Similarly, the set_panel() function enables you to set the panel background with the same customizable parameters. These functions enhance the visual appearance of your plots by allowing you to tailor the background styles to your preferences.

Usage

set_background(object, ...)

set_panel(object, ...)

Arguments

Value

An object of class scplot (seescplot()).

Examples

data(exampleAB, package = "scan")
p1 <- scplot(exampleAB)  |>
 set_background(fill = "lightblue", colour = "darkblue", linewidth = 1.5) |>
 set_panel(fill = "deepskyblue", color = "darkblue", linewidth = 0.3)

Set base text parameters of an scplot object

Description

Sets the base text parameters for all text elements in an scplot object.

Usage

set_base_text(object, ...)

Arguments

Details

This function modifies the text element in the theme list of the scplot object, allowing you to define default text properties such as font family, face, color, size, alignment, angle, line height, and margin using parameters similar to those in element_text().

Value

An object of class scplot (seescplot()).

Set casenames of an scplot object

Description

Sets the case names (labels) and their position in an scplot object.

Usage

set_casenames(object, labels = NULL, position = NULL, background = list(), ...)

Arguments

Details

If labels is NULL, the current labels are kept. If position is NULL, the current position is kept.

Value

An object of class scplot (seescplot()) with a changed casenames element.

Set data lines of an scplot object

Description

Either set aesthetics of the default data line or add another data line.

Usage

set_dataline(
  object,
  variable = NULL,
  line,
  point,
  type = "continuous",
  label = NULL,
  show_gaps = FALSE,
  ...
)

add_dataline(...)

Arguments

Details

The function allows customization of data lines by passing arguments such as color, size, and linetype. If variable is left empty or set to ".dvar", the aesthetics of the default data line are changed. Otherwise, a new data line is added for the specified variable.

Value

An object of class scplot (seescplot()) with a changed datalines element.

See Also

element_line(), element_point()

Examples

data(exampleAB_add, package = "scan")
scplot(exampleAB_add)  |>
  set_dataline("depression", color = "darkblue") |>
  set_dataline(color = "darkgreen", point = list(shape = 5, size = 3))

Set phasenames of an scplot object

Description

Set phasenames of an scplot object

Usage

set_phasenames(object, labels = NULL, position = NULL, ...)

Arguments

Details

This function allows to set or modify the phase names displayed above the phases in an scplot object. You can customize the labels and their position (left, center, or none). Additionally, you can adjust various text parameters such as font family, face, color, size, and more using the ... argument.

Value

An object of class scplot (see scplot()) with a changed phasenames element.

Set separator line in an scplot object

Description

This function allows you to customize the appearance of separator lines in an scplot object by specifying parameters such as color, line width, and line type. You can pass these parameters as arguments, similar to those used in element_line(), to modify the visual style of the separator lines in your plot theme.

Usage

set_separator(object, ...)

Arguments

Value

An object of class scplot (seescplot()) with modified theme element.

Add a theme of to an scplot object

Description

Adds a predefined theme or custom theme to an scplot object.

Usage

set_theme(object, theme, ...)

add_theme(...)

Arguments

Details

Possible themes are: ⁠'basic', 'grid', 'default', 'small', 'tiny', 'big', 'minimal', 'dark', 'sienna', 'phase_color', 'phase_shade', 'grid2'⁠. See new_theme() for details on the themes.

Value

An object of class scplot (seescplot()) with a changed theme element.

Set a theme element of an scplot object

Description

Low-level function. Sets specific theme elements of an scplot object.

Usage

set_theme_element(object, ...)

Arguments

Details

Allows customization of individual theme elements by passing them as named arguments.

Usually, you don't need this function. Possible theme elements are: "text", "plot.background", "panel.background", "panel.spacing.y", "dataline", "datapoint", "statline", "axis.expand.x", "axis.expand.y", "axis.line.x", "axis.line.y", "axis.ticks.length", "axis.ticks", "axis.title.y", "axis.title.x", "axis.text.x", "axis.text.y", "plot.title", "plot.caption", "plot.margin", "casenames", "casenames.strip", "casenames.background", "casenames.position", "phasenames", "phasenames.position.x", "separators", "separators.extent", "label.text", "label.background", "label.padding", "grid", "legend.position", "legend.background", "legend.text", "legend.title", "legend.margin".

The elements are of the following classes:

• text = c("element_text", "element"),

• plot.background = c("element_rect", "element"),

• panel.spacing.y = c("simpleUnit", "unit", "unit_v2"),

• dataline = "list",

• datapoint = "list",

• statline = c("element_line", "element" ),

• axis.expand.x = "numeric",

• axis.expand.y = "numeric",

• axis.line.x = c("element_line", "element"),

• axis.line.y = c("element_line", "element"),

• axis.ticks.length = c("simpleUnit", "unit", "unit_v2"),

• axis.ticks = c("element_line", "element"),

• axis.title.y = c("element_text", "element"),

• axis.title.x = c("element_text", "element"),

• axis.text.x = c("element_text", "element"),

• axis.text.y = c("element_text", "element"),

• plot.title = c("element_text", "element"),

• plot.caption = c("element_text", "element"),

• plot.margin = c("margin", "simpleUnit", "unit","unit_v2"),

• casenames = c("element_text", "element"),

• casenames.strip = c("element_rect", "element"),

• casenames.background = c("element_rect", "element"),

• casenames.position = "character",

• phasenames = c("element_text", "element"),

• phasenames.position.x = "character",

• separators = c("element_line", "element"),

• separators.extent = "character",

• label.text = c("element_text", "element"),

• label.background = c("element_rect", "element" ),

• label.padding = "numeric", grid = c("element_line", "element" ),

• legend.position = "character",

• legend.background = c("element_rect", "element"),

• legend.text = c("element_text", "element"),

• legend.title = c("element_text", "element"),

• legend.margin = c("margin", "simpleUnit", "unit", "unit_v2")

Value

An object of class scplot (seescplot()) with a changed theme element. If no arguments are provided, the possible theme elements are printed.

Examples

data(exampleABC, package = "scan")
p1 <- scplot(exampleABC)  |>
  set_theme_element(
    axis.ticks.length = unit(0, "points"),
    axis.line.y = element_line(color = "darkred", linewidth = 2),
    panel.background = element_rect(color = "darkblue", linewidth = 1),
    panel.spacing.y = unit(0, "points"),
    phasenames = element_text(color = "#00000000")
  )

Set axis parameters of an scplot

Description

Sets limits, increments, line and text parameters of x- or y-axis of an scplot object.

Usage

set_xaxis(
  object,
  limits = NULL,
  increment = NULL,
  increment_from = NULL,
  line = NULL,
  expand = NULL,
  ...
)

set_yaxis(
  object,
  limits = NULL,
  increment = NULL,
  increment_from = NULL,
  line = NULL,
  expand = NULL,
  ...
)

Arguments

Value

An object of class scplot (seescplot()) with changed xaxis and yaxis elements. Also, the theme element is changed to reflect line and text parameters.

Set label for axis

Description

Set label for axis

Usage

set_xlabel(object, label = NULL, ...)

set_ylabel(object, label = NULL, ...)

Arguments

Value

An object of class scplot (seescplot()) with a changed xlabel or ylabel element.

Split Treatment Dataline

Description

This function takes a scplot object and adds treatment datalines according to the specified variables.

Usage

split_dataline(
  object,
  tvar,
  dvar = NULL,
  levels = NULL,
  labels = NULL,
  remove_original = TRUE,
  color = NULL,
  ...
)

Arguments

Details

The function identifies unique treatment levels from the specified treatment variable and creates new datalines for each level. The new datalines are added to the scplot object, and the original dependent variable can optionally be removed from cases where the treatment variable matches the level.

Value

The modified scplot object with added datalines.