apa_beeplot: Bee-swarm Plots for Factorial Designs that Conform to APA...

In papaja: Prepare American Psychological Association Journal Articles with R Markdown

Bee-swarm Plots for Factorial Designs that Conform to APA Guidelines

Description

Create one or more beeswarm plots from a data.frame containing data from a factorial design and set APA-friendly defaults.

Usage

apa_beeplot(data, ...)

## Default S3 method:
apa_beeplot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_points = NULL,
  args_swarm = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  jit = 0.3,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  ...
)

## S3 method for class 'afex_aov'
apa_beeplot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

data	A data.frame that contains the data, or an object of class afex_aov.
...	Arguments passed on to apa_factorial_plot
id	Character. Variable name that identifies subjects.
factors	Character. A vector of up to four variable names that is used to stratify the data.
dv	Character. The name of the dependent variable.
tendency	Closure. A function that will be used as measure of central tendency.
dispersion	Closure. A function that will be used to construct error bars (i.e., whiskers). Defaults to conf_int() for 95% between-subjects confidence intervals. See details for more options, especially for within-subjects confidence intervals.
level	Numeric. Defines the width of the interval if confidence intervals are plotted. Defaults to 0.95. for 95% confidence intervals. Ignored if dispersion is not a confidence-interval function. See details.
fun_aggregate	Closure. The function that will be used to aggregate observations within subjects and factors before calculating descriptive statistics for each cell of the design. Defaults to mean.
na.rm	Logical. Specifies if missing values are removed. Defaults to TRUE.
use	Character. Specifies a method to exclude cases if there are missing values after aggregating. Possible options are "all.obs" or "complete.obs".
intercept	Numeric. Adds a horizontal line at height intercept to the plot. Can be either a single value or a matrix. For the matrix case, multiple lines are drawn, where the dimensions of the matrix determine the number of lines to be drawn.
args_x_axis	An optional list that contains further arguments that may be passed to axis() for customizing the x axis.
args_y_axis	An optional list that contains further arguments that may be passed to axis() for customizing the y axis.
args_title	An optional list that contains further arguments that may be passed to title().
args_points	An optional list that contains further arguments that may be passed to points().
args_swarm	An optional list that contains further arguments to customize the points() of the beeswarm.
args_error_bars	An optional list that contains further arguments that may be passed to arrows().
args_legend	An optional list that contains further arguments that may be passed to legend()
jit	Numeric. Determines the amount of horizontal displacement. Defaults to 0.3, defaults to 0.4 if plot = "bars".
xlab	Character or expression. Label for x axis.
ylab	Character or expression. Label for y axis.
main	Character or expression. For up to two factors, simply specify the main title. If you stratify the data by more than two factors, either specify a single value that will be added to automatically generated main title, or specify an array of multiple titles, one for each plot area.

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), and apa_beeplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_barplot(), apa_factorial_plot(), apa_lineplot()

Examples

apa_beeplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N")
)

apa_beeplot(
  data = npk
 , id = "block"
 , dv = "yield"
 , factors = c("N", "P")
 , args.legend = list(x = "center")
)

apa_beeplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P", "K")
   , ylim = c(0, 80)
   , level = .34
   , las = 1
)

papaja documentation built on Sept. 29, 2023, 9:07 a.m.