CircularViolinPlot: Circular Violin Plot
In bpDir: Boxplots for Directional Data

CircularViolinPlot

R Documentation

Circular Violin Plot

Description

The CircularViolinPlot function produces a violin plot for circular data, with support for full, outer, inner, and two-halves representations. It provides options for displaying confidence intervals, notches, outliers, and additional graphical elements.

Usage

CircularViolinPlot(
    data,
    data2 = NULL,
    type = c("full", "outer", "inner", "two_halves"),
    notch = FALSE,
    beans = c("none", "all", "inliers", "outliers", "outlier_points"),
    outlier_point_color = "red",
    outlier_point_size = 2,
    outlier_point_alpha = 0.8,
    show_ci_interval = TRUE,
    show_notch_cutout = TRUE,
    show_notch_guides = FALSE,
    r0 = 1,
    density_scale = 0.3,
    vonMises_grid = NULL,
    bw = NULL,
    bw2 = NULL,
    kernel = "vonmises",
    fill = "skyblue",
    fill2 = "darkorange",
    alpha = 0.75,
    alpha2 = 0.75,
    fill_outlier = NULL,
    fill2_outlier = NULL,
    alpha_outlier = 0.2,
    alpha2_outlier = 0.2,
    arc_color = "black",
    arc_color2 = "black",
    ci_color = "white",
    ci_color2 = "white",
    arc_thickness = 0.06,
    ci_thickness = 0.012,
    box_width_factor = 1,
    density_threshold = 0,
    cutoff = NULL,
    cutoff2 = NULL,
    n_boot = 1000,
    ci_level = 0.95,
    notch_factor = 0.9,
    notch_guide_linetype = "solid",
    notch_guide_linewidth = 0.4,
    bean_length = 0.035,
    bean_min_size = 0.15,
    bean_max_size = 0.6,
    circle_color = "grey70",
    circle_linewidth = 0.7,
    center_point = TRUE,
    center_point_color = "black",
    center_point_size = 1.8,
    title = "",
    xlim = c(-1.5, 1.5),
    ylim = c(-1.5, 1.5)
)

Arguments

`data`	Numeric vector of class `circular`, containing the primary circular observations. The data should have units specified as degrees or radians.
`data2`	Optional numeric vector of class `circular`, containing a second set of circular observations. Required when `type = "two_halves"`.
`type`	Character string specifying the plot representation. Options are `"full"` (default), `"outer"`, `"inner"`, and `"two_halves"`.
`notch`	Logical; whether to display notches in the plot. Default is `FALSE`.
`beans`	Character string specifying which observations or groups should be represented by beans. Options are `"none"`, `"all"`, `"inliers"`, `"outliers"`, and `"outlier_points"`.
`outlier_point_color`	Character string specifying the color of individual outlier points. Default is `"red"`.
`outlier_point_size`	Numeric; size of individual outlier points. Default is 2.
`outlier_point_alpha`	Numeric; transparency of individual outlier points, between 0 and 1. Default is 0.8.
`show_ci_interval`	Logical; whether to display the confidence interval. Default is `TRUE`.
`show_notch_cutout`	Logical; whether to display the notch cutout. Default is `TRUE`.
`show_notch_guides`	Logical; whether to display guide lines associated with the notches. Default is `FALSE`.
`r0`	Numeric; radius of the reference circle. Default is 1.
`density_scale`	Numeric; scaling factor applied to the normalized density to determine the width of the violin. Default is 0.3.
`vonMises_grid`	An optional data frame containing a precomputed calibration grid generated by `generate_vonmises_grid`. If supplied, this grid is used for estimating the von Mises concentration parameter without regenerating the calibration grid. If `NULL` (default), the grid is generated automatically when required.
`bw`	Numeric; smoothing bandwidth used to estimate the density of `data`. By default, when `kernel` is `"vonmises"`, the bandwidth is determined automatically.
`bw2`	Numeric; smoothing bandwidth used to estimate the density of `data2`. Default is `NULL`, allowing automatic selection.
`kernel`	Character string specifying the smoothing kernel used for density estimation. Supported options are `"vonmises"` and `"wrappednormal"`, corresponding to kernels of type "K" in `density.circular` from the circular package.
`fill`	Character string specifying the fill color of the primary violin. Default is `"skyblue"`.
`fill2`	Character string specifying the fill color of the second violin or half. Default is `"darkorange"`.
`alpha`	Numeric; transparency of the primary violin fill, between 0 and 1. Default is 0.75.
`alpha2`	Numeric; transparency of the second violin fill, between 0 and 1. Default is 0.75.
`fill_outlier`	Character string specifying the fill color used for outliers in the primary data. Default is `NULL`.
`fill2_outlier`	Character string specifying the fill color used for outliers in the second data set. Default is `NULL`.
`alpha_outlier`	Numeric; transparency of the primary outlier fill, between 0 and 1. Default is 0.2.
`alpha2_outlier`	Numeric; transparency of the second outlier fill, between 0 and 1. Default is 0.2.
`arc_color`	Character string specifying the color of the arcs of the primary violin. Default is `"black"`.
`arc_color2`	Character string specifying the color of the arcs of the second violin or half. Default is `"black"`.
`ci_color`	Character string specifying the color used to display the confidence interval for the primary data. Default is `"white"`.
`ci_color2`	Character string specifying the color used to display the confidence interval for the second data set. Default is `"white"`.
`arc_thickness`	Numeric; thickness of the violin arcs. Default is 0.06.
`ci_thickness`	Numeric; thickness of the confidence interval elements. Default is 0.012.
`box_width_factor`	Numeric; scaling factor controlling the width of the box or summary-statistic component. Default is 1.
`density_threshold`	Numeric; density threshold below which density values are set to zero, resulting in a narrower violin. Default is zero, meaning no additional shrinking.
`cutoff`	Numeric; cutoff threshold for the outlier detection rule applied to the primary data, used to clip the density. Default is `NULL`.
`cutoff2`	Numeric; cutoff threshold for the outlier detection rule applied to the second data set. Default is `NULL`.
`n_boot`	Integer; number of bootstrap iterations used to estimate confidence intervals. Default is 1000.
`ci_level`	Numeric; confidence level used for confidence interval estimation. Default is 0.95.
`notch_factor`	Numeric; scaling factor controlling the size of the notches. Default is 0.9.
`notch_guide_linetype`	Character string specifying the line type of the notch guide lines. Default is `"solid"`.
`notch_guide_linewidth`	Numeric; line width of the notch guide lines. Default is 0.4.
`bean_length`	Numeric; parameter controlling the length of the bean elements. Default is 0.035.
`bean_min_size`	Numeric; minimum size of the bean elements. Default is 0.15.
`bean_max_size`	Numeric; maximum size of the bean elements. Default is 0.6.
`circle_color`	Character string specifying the color of the reference circle. Default is `"grey70"`.
`circle_linewidth`	Numeric; line width of the reference circle. Default is 0.7.
`center_point`	Logical; whether to display the center point. Default is `TRUE`.
`center_point_color`	Character string specifying the color of the center point. Default is `"black"`.
`center_point_size`	Numeric; size of the center point. Default is 1.8.
`title`	Character string specifying the plot title. Default is an empty string.
`xlim`	Numeric vector of length two specifying the horizontal axis limits. Default is `c(-1.5, 1.5)`.
`ylim`	Numeric vector of length two specifying the vertical axis limits. Default is `c(-1.5, 1.5)`.

Value

outliers: A vector of class circular in radians, containing observations classified as outliers as lying in the outlying region.
cutoff: The cutoff threshold used by the outlier detection rule to clip the density. The violin plot is truncated at the furthest non-outliers.
statistics: A data frame containing circular summary statistics including the circular median, first and third quartiles.

Author(s)

Davide Buttarazzi, Houyem Demni Demni et al. (2026), Robust measures of dispersion for circular data with an anomaly detection rule. Under review. Demni et al. (2026), Notched violin plots for circular data. In: Martella, F., Arima, S., Marino, M.F., Mollica, C. (eds) Statistical Science: From Theory to Applied Research I. SIS-FENStatS 2026. Italian Statistical Society Series on Advances in Statistics. Springer, Cham. https://doi.org/10.1007/978-3-032-30873-3 10.

Examples

require(circular)
x <- rvonmises(50, circular(pi/2), 5)
v = generate_vonmises_grid(rho_seq = seq(0.01, 0.99, by = 0.05))
CircularViolinPlot(x, vonMises_grid = v)

# Specify a plot representation explicitly
CircularViolinPlot(x, vonMises_grid = v, type = "full")

# Example with two data sets
y <- rvonmises(50, circular(pi), 5)
CircularViolinPlot(x, data2 = y, vonMises_grid = v, type = "two_halves")

bpDir documentation built on Nov. 9, 2026, 9:07 a.m.