Type:	Package
Title:	Plot Function for Single-Case Data Frames
Version:	0.6.0
Date:	2025-06-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 (2025) https://jazznbass.github.io/scan-Book/.
Depends:	R (≥ 4.1.0)
Imports:	ggplot2, scan (≥ 0.61.0), stats, utils, mblm
Suggests:	rmarkdown, knitr
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-06-29 12:22:03 UTC; wilbert
Author:	Juergen Wilbert [aut, cre]
Maintainer:	Juergen Wilbert <juergen.wilbert@uni-muenster.de>
Repository:	CRAN
Date/Publication:	2025-06-29 12:50:02 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]

Dummy function to inherit global descriptions of parameters

Description

Dummy function to inherit global descriptions of parameters

Usage

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

Arguments

Add arrrows to an scplot

Description

Add arrrows to an scplot

Usage

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

Arguments

Value

An object of class scplot (seescplot()) 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

Description

Add grid to an scplot

Usage

add_grid(object, ...)

Arguments

Value

An object of class scplot (seescplot()).

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

Add value labels to an scplot

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

Add a legend to an scplot

Usage

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

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

Description

Add line to an scplot

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

Description

Add marks to an scplot

Usage

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

Arguments

Details

If positions is an object returned from an outlier analysis outlier(), the corresponding outliers are marked.

Value

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

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

Description

Add a ridge to an scplot

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

Description

Add a statline to an scplot

Usage

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

Arguments

Details

The phase argument defines the reference phase for some statistical functions (⁠"median", "mean", "min", "max", "quantile"⁠). 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. Various methods for an extrapolated trendA line exist: "trendA" is based on an OLS regression, "trendA theil-sen" on a nonparametric regression, and "trendA bisplit" / "trendA trisplit" are two median based approaches. Some of the functions defined in stats 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

Description

Add test to an scplot

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

Description

Add title and caption to an scplot

Usage

add_title(object, label, ...)

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

Arguments

Value

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

Creates a ggplot2 object from an scplot() object

Description

Creates a ggplot2 object from an scplot() object

Usage

as_ggplot(scplot)

Arguments

Details

as_ggplot() is used when you want to return a ggplot2 object for further use with external ggplot functions.

Value

A ggplot2 plot object.

Point element

Description

In conjunction with ggplot an object to represent point attributes.

Usage

element_point(colour = NULL, size = NULL, shape = NULL, color = NULL)

Arguments

Value

An object of class c("element_point", "element").

Create a new scplot theme

Description

Create a new scplot theme

Usage

new_theme()

extract_theme(object)

Arguments

Value

An scplot-theme object

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)

print.scplot

Description

print.scplot

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_rect, element_text, unit

scan

%>%

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

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 a forest plot of Tau-U effects.

Usage

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

Arguments

Value

A forest plot displaying Tau-U effects.

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

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

Description

This function provides a plot of a single-case or multiple single-cases.

Usage

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

Arguments

Value

An object of class scplot containing the single-case data (element scdf), and information about the plot style (element theme).

Author(s)

Juergen Wilbert

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

Description

Set plot and panel background of an scplot

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

Description

Set base text parameters of an scplot

Usage

set_base_text(object, ...)

Arguments

Value

An object of class scplot (seescplot()).

Set casenames of an scplot

Description

Set casenames of an scplot

Usage

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

Arguments

Value

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

Set data lines of an scplot

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,
  ...
)

add_dataline(...)

Arguments

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 phasenames of an scplot

Description

Set phasenames of an scplot

Usage

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

Arguments

Value

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

Set separator line in an scplot

Description

Set separator line in an scplot

Usage

set_separator(object, ...)

Arguments

Value

An object of class scplot (seescplot()).

Add a theme of to an scplot

Description

Possible themes are: ⁠'basic', 'grid', 'default', 'small', 'tiny', 'big', 'minimal', 'dark', 'sienna', 'phase_color', 'phase_shade', 'grid2'⁠.

Usage

set_theme(object, theme, ...)

add_theme(...)

Arguments

Value

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

Set a theme element

Description

Set a theme element

Usage

set_theme_element(object, ...)

Arguments

Details

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.

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

Set axis parameters of an scplot

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.

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.