Package {BagWhiskerPlot}

Type: Package
Title: Bag-and-Whisker Plot
Version: 0.1.0
Depends: MASS
Description: Implementation of the Bag-and-Whisker Plot for bivariate data. Provides a single user-facing function bag_whisker() that wraps the computation and plotting helpers in this package. For more details, please refer to the paper "The Bag-and-Whisker Plot: A New Bagplot for Bivariate Data" by Qin, Gang, Tong and Cui (2025) <doi:10.48550/arXiv.2512.06314>.
Encoding: UTF-8
RoxygenNote: 7.3.3
Imports: ggplot2, parallel
License: GPL-3
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-05-10 01:52:22 UTC; sean
Author: Shenghao Qin [aut, cre]
Maintainer: Shenghao Qin <seanqin31@outlook.com>
Repository: CRAN
Date/Publication: 2026-05-13 20:00:15 UTC

Bag-and-whisker plot implementation, with outlier detection under different type-I error controls

Description

Compute and draw a bag-and-whisker plot of bivariate data that highlights outliers under different type-I error controls. This is a thin user-facing wrapper around the internal computation and ggplot2-based plotting helpers in this package.

Usage

bag_whisker(
  x,
  y,
  type1 = "unadjusted",
  q = 0.1,
  normal_inlier = FALSE,
  normal_outter = FALSE,
  asymp_dist_pv = "chisq",
  center_type = "hdepth",
  factor = 3,
  na.rm = FALSE,
  approx.limit = 300,
  show.outlier = TRUE,
  show.whiskers = TRUE,
  show.looppoints = TRUE,
  show.bagpoints = TRUE,
  show.loophull = FALSE,
  show.baghull = TRUE,
  create.plot = TRUE,
  add = FALSE,
  pch = 1,
  cex = 0.6,
  naive_bag = FALSE,
  dkmethod = 1,
  precision = 1,
  n_cores = 1,
  verbose = FALSE,
  debug.plots = "no",
  timing = FALSE,
  col.loophull = "#aaccff",
  col.looppoints = "#3355ff",
  col.baghull = "#D3D3D3",
  col.bagpoints = "#000088",
  transparency = FALSE,
  show.center = TRUE,
  show.fence_mag_bag = TRUE,
  ...
)

Arguments

x, y

Numeric vectors giving the coordinates of the bivariate sample. You can either supply both x and y, or a two-column matrix / data frame via x and leave y missing.

type1

Character string specifying the type-I error control used in the multiple-testing step. One of "unadjusted", "FWER", "FDR", or "PFER", default "unadjusted".

q

Numeric, the control level for the multiple testing procedure, default 0.1.

normal_inlier

Logical; if TRUE, the bag is calculated based on a normal reference distribution instead of a depth-based bag, default FALSE.

normal_outter

Logical; if TRUE, the fence is calculated based on a normal reference distribution, otherwise it is obtained by magnifying the bag, default FALSE.

asymp_dist_pv

Character string; asymptotic distribution used for p-value calculation, default "chisq".

center_type

Character string; center definition, default "hdepth".

factor

Numeric; the factor lambda for "unadjusted" that controls how far the bag is magnified to obtain the fence, default 3.

na.rm

Logical; if TRUE, rows with missing values are removed, otherwise medians are used to impute, default FALSE.

approx.limit

Integer; threshold above which a subsample is used for approximating the bag-plot computation, default 300.

show.outlier

Logical; if TRUE, identified outliers are shown in the plot, default TRUE.

show.whiskers

Logical; if TRUE, whisker segments are added to the plot, default TRUE.

show.looppoints

Logical; if TRUE, data points classified as belonging to the loop are shown, default TRUE.

show.bagpoints

Logical; if TRUE, data points classified as inside the bag are shown, default TRUE.

show.loophull

Logical; if TRUE, the convex hull of the loop is drawn, default FALSE.

show.baghull

Logical; if TRUE, the convex hull of the bag is drawn, default TRUE.

create.plot

Logical; if TRUE, a plot is created for the computed bag-and-whisker representation, default TRUE.

add

Logical; if TRUE, graphical elements are added to the current plot; otherwise a new plot is started, default FALSE.

pch, cex

Graphical parameters forwarded to the plotting method to control point character and expansion.

naive_bag

Logical; if TRUE, the bag is computed without expansion, default FALSE.

dkmethod

Integer in 1:2; depth kernel method, default 1.

precision

Numeric; controls precision of hull expansion, default 1.

n_cores

Integer or NULL. If greater than 1 or NULL, uses a parallel backend (via parallel::makeCluster()) for some calculation intensive loops. If NULL, uses parallel::detectCores() - 1 cores (minimum 1). Default 1.

verbose

Logical; if TRUE, progress messages from the computational engine are printed, default FALSE.

debug.plots

Character string; controls generation of additional diagnostic plots for debugging, default no.

timing

Logical; if TRUE, prints a simple timing summary and adds a timings component (named numeric vector, elapsed seconds) to the returned object, default FALSE.

col.loophull

Fill colour used for the loop hull.

col.looppoints

Point colour used for the loop points.

col.baghull

Fill colour used for the bag hull.

col.bagpoints

Point colour used for the bag points.

transparency

Logical; if TRUE, semi-transparent fills are used for the bag and loop hulls, default FALSE.

show.center

Logical; if TRUE, the chosen center of the data is highlighted in the plot, default TRUE.

show.fence_mag_bag

Logical; if TRUE, the fence by magnifying the bag is visualised, default TRUE.

...

Passed on to the S3 method plot.bagWhiskerPlot() when create.plot = TRUE.

Details

This function is the only exported user-facing entry point of the package. It calls the internal computational engine compute.bagWhiskerPlot() and then, by default, plots the resulting object using a ggplot2-based implementation of the S3 method plot.bagWhiskerPlot().

Value

An object of class "bagWhiskerPlot" containing the bag-plot decomposition and outlier information. When show = TRUE, the object is returned invisibly after drawing the plot.

Build ggplot2 layers for a bag-whisker plot

Description

Low-level helper that converts a bagWhiskerPlot object (as produced by bag_whisker() or compute.bagWhiskerPlot()) into a list of ggplot2 layers. This is mainly intended for advanced composition; typical users should call plot.bagWhiskerPlot() via bag_whisker().

Usage

bp_build_layers(
  x,
  show.outlier = TRUE,
  show.whiskers = TRUE,
  show.looppoints = TRUE,
  show.bagpoints = TRUE,
  show.loophull = FALSE,
  show.baghull = TRUE,
  show.fence_mag_bag = TRUE,
  pch = 16,
  cex = 0.4,
  col.loophull = "#aaccff",
  col.looppoints = "#3355ff",
  col.baghull = "#7799ff",
  col.bagpoints = "#000088",
  col.fence_mag_bag = "#CC33CC",
  transparency = FALSE,
  show.center = TRUE,
  whisker.fade = TRUE,
  whisker.n = 10,
  whisker.alpha.start = 0.4,
  whisker.alpha.end = 0,
  whisker.end.prop = 0.7
)

Arguments

x

A bagWhiskerPlot object.

show.outlier

Logical; if TRUE, identified outliers are shown in the plot.

show.whiskers

Logical; if TRUE, whisker segments are added to the plot.

show.looppoints

Logical; if TRUE, data points classified as belonging to the loop are shown.

show.bagpoints

Logical; if TRUE, data points classified as inside the bag are shown.

show.loophull

Logical; if TRUE, the convex hull of the loop is drawn.

show.baghull

Logical; if TRUE, the convex hull of the bag is drawn.

show.fence_mag_bag

Logical; if TRUE, the fence obtained by magnifying the bag (data-adaptive threshold) is visualised.

pch

Plotting character (shape) used for points.

cex

Numeric scaling factor for point sizes and (in 2D) whisker line width.

col.loophull

Fill color for the loop hull polygon.

col.looppoints

Color for loop-region points.

col.baghull

Fill color for the bag hull polygon.

col.bagpoints

Color for bag-region points.

col.fence_mag_bag

Color for the magnified fence polygon.

transparency

Logical; if TRUE, semi-transparent versions of the hull colors are used.

show.center

Logical; if TRUE, the chosen center of the data is highlighted in the plot.

whisker.fade

Logical; if TRUE, whisker segments are drawn as multiple short segments with fading alpha towards their ends.

whisker.n

Integer; number of subsegments used per whisker when whisker.fade = TRUE.

whisker.alpha.start

Numeric in [0, 1] giving the starting alpha for faded whiskers (near the outer point).

whisker.alpha.end

Numeric in [0, 1] giving the ending alpha for faded whiskers (near the bag or center).

whisker.end.prop

Numeric in [0, 1] controlling how far along the whisker the fade is applied; values close to 1 fade along most of the whisker.

Value

A list of ggplot2 layers.

Plot a bag-whisker plot using ggplot2

Description

Produce a bag-whisker plot from a bagWhiskerPlot object using ggplot2. This is the plotting backend used by bag_whisker() to render the bag, loop, fence, and whisker elements, with optional highlights for outliers and the center.

Usage

## S3 method for class 'bagWhiskerPlot'
plot(
  x,
  show.outlier = TRUE,
  show.whiskers = TRUE,
  show.looppoints = TRUE,
  show.bagpoints = TRUE,
  show.loophull = FALSE,
  show.baghull = TRUE,
  show.fence_mag_bag = TRUE,
  add = FALSE,
  pch = 16,
  cex = 0.4,
  verbose = FALSE,
  col.loophull = "#aaccff",
  col.looppoints = "#3355ff",
  col.baghull = "#7799ff",
  col.bagpoints = "#000088",
  col.fence_mag_bag = "#CC33CC",
  transparency = FALSE,
  show.center = TRUE,
  whisker.fade = TRUE,
  whisker.n = 10,
  whisker.alpha.start = 0.4,
  whisker.alpha.end = 0,
  whisker.end.prop = 0.7,
  main = NULL,
  ...
)

Arguments

x

A bagWhiskerPlot object as returned by bag_whisker (or related constructors).

show.outlier

Logical; if TRUE, identified outliers are shown in the plot.

show.whiskers

Logical; if TRUE, whisker segments are added to the plot.

show.looppoints

Logical; if TRUE, data points classified as belonging to the loop are shown.

show.bagpoints

Logical; if TRUE, data points classified as inside the bag are shown.

show.loophull

Logical; if TRUE, the convex hull of the loop is drawn.

show.baghull

Logical; if TRUE, the convex hull of the bag is drawn.

show.fence_mag_bag

Logical; if TRUE, the fence obtained by magnifying the bag (data-adaptive threshold) is visualised.

add

Logical; if TRUE, graphical elements are added to an existing ggplot object supplied via ... (see Details). If FALSE, a new plot is created and printed.

pch

Plotting character (shape) used for points.

cex

Numeric scaling factor for point sizes and (in 2D) whisker line width.

verbose

Logical; currently unused, reserved for possible diagnostic messages.

col.loophull

Fill color for the loop hull polygon.

col.looppoints

Color for loop-region points.

col.baghull

Fill color for the bag hull polygon.

col.bagpoints

Color for bag-region points.

col.fence_mag_bag

Color for the magnified fence polygon.

transparency

Logical; if TRUE, semi-transparent versions of the hull colors are used.

show.center

Logical; if TRUE, the chosen center of the data is highlighted in the plot.

whisker.fade

Logical; if TRUE, whisker segments are drawn as multiple short segments with fading alpha towards their ends.

whisker.n

Integer; number of subsegments used per whisker when whisker.fade = TRUE.

whisker.alpha.start

Numeric in [0, 1] giving the starting alpha for faded whiskers (near the outer point).

whisker.alpha.end

Numeric in [0, 1] giving the ending alpha for faded whiskers (near the bag or center).

whisker.end.prop

Numeric in [0, 1] controlling how far along the whisker the fade is applied; values close to 1 fade along most of the whisker.

main

Optional main title for the plot.

...

Additional arguments passed on to the underlying ggplot2 scales or base plot. In particular, xlim and ylim can be supplied to control axis limits. When add = TRUE, gg or base_gg can be supplied as an existing ggplot object to which the layers are added.

Details

The function is a plot method for bagWhiskerPlot objects and relies on ggplot2 for rendering.

Value

A ggplot object representing the bag-whisker plot, returned invisibly. The plot is drawn as a side effect when add = FALSE or when add = TRUE with an existing ggplot object.

See Also

bag_whisker, bp_build_layers, ggplot2