cmdensity {cplots}

Multi-class Circular Density Curve

Description

Function cmdensity can be used to plot 2-dimensional density curves for circular data with multiple classes. The density curves are stacked to avoid any overlap.

Usage

cmdensity(
  funlist,
  funprop = 1,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  total.area = 1,
  n = 500,
  nlabels = 4,
  cols = NULL,
  borders = NULL,
  xlim = NULL,
  ylim = NULL,
  main = NULL,
  type = c("null", "compass", "clock"),
  add = FALSE,
  x.legend = "bottomright",
  y.legend = NULL,
  fill = TRUE,
  lty = 1,
  lwd = 1
)

Arguments

funlist

a list of functions which can be used to calculate the density values for each class, evaluated at given points defined by the first argument of the functions. The set of points is a sequence from 0 to 2\pi, with length n.

funprop

proportions for functions. It is 1 by default. A user can choose different proportions for the functions so as to represent different numbers of observations. If they do not add up to the number of functions (k), it will be normalised so that sum(classprop) = k.

radius

the radius of the reference circle.

area.prop

logical; if TRUE, an area-proportional transformation is applied; if FALSE, a height-proportional transformationis applied.

total.area

a positive number specifying the total area under all the density curves. If total.area = NULL, no scaling is applied, the plot is in the original scale. If area.prop = TRUE, the total area is automatically unity without scaling.

n

the number of points used to plot each density curve. The larger the number is, the more accurate the curve is.

nlabels

integer, for the number of levels to be plotted; if 0, no label is plotted.

cols

the colors to fill the area under each density curve, with the same order as the class.

borders

the colors of the borders.

xlim

numeric vectors of length 2, giving the x coordinates ranges.

ylim

numeric vectors of length 2, giving the y coordinates ranges.

main

the main title (on top)

type

the type of circular data, one of the values "null", "compass" or "clock". If "null", no special lables plotted for directions. If "compass", the four cardinal directions are printed inside the reference circle. If "clock", labels for 24 hours are printed inside the reference circle.

add

logical; if TRUE, density curves are superimposed to the current plot, for example, the circular histograms, rose diagrams and stacked dot plots.

x.legend

x coordinate to plot the legend.

y.legend

y coordinate to plot the legend.

fill

logical. If TRUEt, fills the regions with colors under/between the density curves. If FALSE, only the density curves are plotted.

lty

line width

lwd

line width

Value

No return value

Author(s)

Danli Xu <[e-mail]>, Yong Wang <[e-mail]>

References

Xu, D. and Wang, Y. (2020). Area-proportional Visualization for Circular Data. Journal of Computational and Graphical Statistics, 29, 351-357.

See Also

cdensity, cmhist

Examples

# Load and pre-process the dataset
library(circular)
data("pigeons", package = "circular")
x = pigeons[,2] / 180 * pi                  # bearing
y = pigeons[,1]                             # treatment
vs = split(x, factor(y, unique(y)))    # list of classified value
prop = sapply(vs, length) / length(x)  # proportion of each class

# Define the kde function for each class using von Mises kernels
dvm = function(x, mu=0, kappa=1)  # von Mises density
  exp(kappa * cos(x - mu)) * (2 * pi * besselI(kappa, 0))^(-1)
kdevm = function(x, x0, bw=0.3) 
  rowMeans(outer(x, x0, dvm, 0.5 / (1 - exp(-bw^2 / 2))))
fs = list(function(x) kdevm(x, x0=vs[[1]]),
          function(x) kdevm(x, x0=vs[[2]]),
          function(x) kdevm(x, x0=vs[[3]]))

# stacked density curves for 3 classes
cmdensity(fs)                         # 1:1:1
cmdensity(fs, prop)                   # using proportions for functions