Help for package CircularBoxplots

Title:

Grouped Boxplots for Circular Data

Version:

0.1.2

Description:

Plotting functions to create circular boxplots for grouped data. The primary 2-dimensional version creates concentric circular boxplots for specified groups, scaling the width of each boxplot to adjust for human perception. The 3-dimensional version maps these plots onto a torus which is suitable for periodic circular data such as wind direction over the course of a year. An example dataset of this type is provided for reference. For examples of circular boxplots and additional implementation details, see Berlinski et al. (2026) <doi:10.48550/arXiv.2602.05335>.

License:

GPL-2

Encoding:

UTF-8

RoxygenNote:

7.3.3

Imports:

circular, plotrix, rgl, RColorBrewer, plot3D, grDevices

NeedsCompilation:

Packaged:

2026-05-08 23:08:38 UTC; josh

Author:

Josh Berlinski [aut, cre], Fan Dai [aut]

Maintainer:

Josh Berlinski <jdberlinski@gmail.com>

Depends:

R (≥ 3.5.0)

Repository:

CRAN

Date/Publication:

2026-05-13 08:10:17 UTC

CircularBoxplots: Grouped Boxplots for Circular Data

Description

Author(s)

Maintainer: Josh Berlinski jdberlinski@gmail.com

Authors:

Fan Dai fand@mtu.edu

Create grouped circular boxplot

Description

Given a named list of circular objects, create a grouped circular boxplot.

Usage

GroupedCircularBoxplot(
  data_in,
  template = "degrees",
  place = "none",
  units = "degrees",
  marg = "large",
  shrink = 1,
  H = FALSE,
  stack = FALSE,
  constant = "optimal",
  rad_shift = 0.25,
  lwd = 1,
  plot_cols = RColorBrewer::brewer.pal(8, "Set2"),
  line_cols = RColorBrewer::brewer.pal(8, "Dark2"),
  arrow_cols = line_cols,
  legend_pos = "topleft",
  legend_title = NULL,
  draw_arrow = TRUE,
  ordinal = FALSE,
  template_options = NULL,
  minimal = FALSE,
  scale_widths = FALSE,
  arrow_width = lwd,
  center_point = FALSE,
  cex = 0.5,
  mex = 1
)

Arguments

data_in

List of circular objects to be plotted

template

One of "degrees", "radians", "geographics", or NULL

place

If template is NULL, either "outside" or "inside" denoting where the axis should be drawn

units

If template is NULL, units to use on the drawn axis

marg

character specifying the plot region as either "large" (default) or "small".

shrink

Numeric specifying the factor by which to scale the plot. Numbers less than 1 will increase the size.

H

Logical indicating if each data point should be drawn outside the hinges of the boxplot

stack

Logical indicating if drawn points should be stacked

constant

Numeric specifying the multiplicative factor determining how far whiskers extend from box. A value of "optimal" will choose values based on a von Mises distribution (see Buttarazzi et al. 2018)

rad_shift

Scalar indicating the distance between each boxplot

lwd

Scalar indicating the width of boxplot lines, also impacts other lines, relatively

plot_cols

Vector with the same length as data_in, specifying the color of the boxplot

line_cols

Vector with the same length as data_in, specifying the color of the median lines

arrow_cols

Vector with the same length as data_in, specifying the color of the arrows pointing to the medians. Default value is the same as line_cols

legend_pos

String indicating where the legend should be drawn, or "none" for no legend

legend_title

String indicating legend for title, if necessary

draw_arrow

Logical specifying if arrows pointing to each median should be drawn

ordinal

Logical, if template is NULL and units is "geographics", should the ordinal directions also be drawn?

template_options

If template is "custom", a list containing named elements "ax_labels", "lab_coord", "shift", and "gridlines." ax_labels is a character vector of axis labels to be plotted at the locations lab_coord, a numeric vector in degrees counterclockwise starting from 0. shift is a numeric value that controls how far outside the last boxplot the axis should be drawn, and gridlines is a logical indicating if dashed lines should be drawn at the specified axis labels.

minimal

Logical. If true, a simple colored line and point will replace the box and median line. Radial lines at fence points will also not be drawn

scale_widths

Logical, should the width of each boxplot be scaled based on (the square root of) it's distance from the center?

arrow_width

Numeric controlling the width of the arrow drawn pointing to each median. Defaults to lwd.

center_point

Logical, should a point be drawn at the center of the grouped circular boxplot

cex

numerical, the size of the plotting character, also adjusts other characters relatively

mex

numerical, the size of the character in the margins.

Value

A list of lists containing the circular median, hinges, and whiskers for each of the groups in the dataset, invisibly.

Author(s)

Josh Berlinski

Davide Buttarazzi

Examples

library(circular)
set.seed(123)
data <- list(
    x = rvonmises(100, circular(pi), 5),
    y = rvonmises(100, circular(pi/2), 2.5),
    z = rvonmises(100, circular(7*pi/4), 8)
)
GroupedCircularBoxplot(data)

Create grouped circular boxplots around the 3D torus surface.

Description

Given a named list of circular objects, create a grouped circular boxplot.

Usage

GroupedCircularBoxplot.3D(
  data_in,
  template = "degrees",
  marg = "large",
  shrink = 1,
  H = FALSE,
  constant = "optimal",
  lwd = 2,
  plot_cols = RColorBrewer::brewer.pal(8, "Set2"),
  line_cols = RColorBrewer::brewer.pal(8, "Dark2"),
  arrow_cols = line_cols,
  draw_arrow = TRUE,
  minimal = FALSE,
  scale_widths = FALSE
)

Arguments

data_in

List of circular objects to be plotted

template

One of "degrees" (default), "radians" and "geographics" with eight directions

marg

character specifying the baseline 2D circle region as either "large" (default) or "small"

shrink

Numeric specifying the factor by which to scale the baseline circular plot. Numbers less than 1 will increase the size.

H

Logical indicating if each data point should be drawn outside the hinges of the boxplot

constant

Numeric specifying the multiplicative factor determining how far whiskers extend from box. A value of "optimal" will choose values based on a von Mises distribution (see Buttarazzi et al. 2018)

lwd

Scalar indicating the width of the quartile boxplot lines if minimal = TRUE

plot_cols

Vector with the same length as data_in, specifying the color of the boxplot

line_cols

Vector with the same length as data_in, specifying the color of the median lines

arrow_cols

Vector with the same length as data_in, specifying the color of the arrows pointing to the medians. Default value is the same as line_cols

draw_arrow

Logical specifying if arrows pointing to each median should be drawn

minimal

Logical. If true, a quartile boxplot is created with simple colored line and point will replace the box and median line. Radial lines at fence points will also not be drawn

scale_widths

Logical, should the width of each boxplot be scaled based on (the square root of) it's distance from the center?

Value

A list of lists containing the circular median, hinges, and whiskers for each of the groups in the dataset, invisibly.

Author(s)

Josh Berlinski

Fan Dai

Examples

library(circular)
set.seed(123)
data <- list(
    x = rvonmises(100, circular(pi), 5),
    y = rvonmises(100, circular(pi/2), 2.5),
    z = rvonmises(100, circular(7*pi/4), 8)
)
GroupedCircularBoxplot.3D(data)

Phases of clock genes

Description

Data from an experiment performed on mice to determine compare the peak phase times of circadian clock genes under ad-libitum and time-restricted feeding regimines. The two imported data frames are alf and trf corresponding to ad-libitum and time-restricted results, respectively. The observations are measured in degrees, corresponding to time on a 24-hour zeigeber time clock cycle.

Usage

data(deota)

Format

An object of class list of length 2.

Source

doi:10.1016/j.cmet.2022.12.006

References

Deota S, Lin T, Chaix A, Williams A, Le H, Calligara H, Ramasamy R, Huang L, Panda S (2023) Diurnal transcriptome landscape of a multi-tissue response to time-restricted feeding in mammals. Cell Metabolism 35(1):150-164.e4

Wind direction

Description

Measurements of wind direction from Ames, Iowa, USA and Jamshedpur, India. Data were obtained for over the entire 2023 year. The list contains two data frames, AMW and VEJS, corresponding to Ames and Jamshedpur, respectively. The Ames data were collected every five minutes, while the Jamshedpur data are hourly.

Usage

data(wind_direction)

Format

An object of class list of length 2.

Details

Each datframe contains three columns, the first corresponding to the code of the weather station name, the second valid which contains the time the mesurement was taken, and drct, which is the direction from which the wind was measured in degrees from true north, clockwise.

Note that a direction of 0 degrees indicates no measurable wind, and thus does not contain useful information on the wind direction. A value of 360 degrees corresponds to true north.

Source

Iowa State University's Iowa Environmental Mesonet https://mesonet.agron.iastate.edu/

Package {CircularBoxplots}

CircularBoxplots: Grouped Boxplots for Circular Data

Description

Author(s)

Create grouped circular boxplot

Description

Usage

Arguments

Value

Author(s)

Examples

Create grouped circular boxplots around the 3D torus surface.

Description

Usage

Arguments

Value

Author(s)

Examples

Phases of clock genes

Description

Usage

Format

Source

References

Wind direction

Description

Usage

Format

Details

Source