cmhist: Multi-class Stacked Circular Histogram and Rose Diagram

Description

Function cmhist can be used to plot 2-dimensional histograms and rose diagrams for circular data with multiple classes. The histograms are stacked to avoid any overlap.

Usage

cmhist(
  value,
  class,
  nbins = 36,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  prob = TRUE,
  proportion = FALSE,
  total.area = 1,
  nlabels = 4,
  cols = NULL,
  borders = NULL,
  m = NA,
  xlim = NULL,
  ylim = NULL,
  main = NULL,
  type = c("null", "compass", "clock"),
  x.legend = "bottomright",
  y.legend = NULL
)

Arguments

value

a numeric vector storing angular values between 0 and 2 pi, or an object that can be coerced to.

class

a character vector specifying the group the value belongs to. It needs to have the same length as value, otherwise it is repeated to the length of value. The order of plotting from the innermost to the outermost depends on the order of their appearance in class.

nbins

the number of bins of the circular histogram. Internally, it is rounded to a multiple of 4.

radius

the radius of the reference circle. If radius = 0, a rose diagram is produced; if radius > 0, a circular histogram is produced outside the reference circle.

area.prop

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

prob

logical; if TRUE, the circular histogram graphic is a representation of probability densities; if FALSE, a representation of frequencies.

proportion

logical; if TRUE, the frequencies are scaled by the proportion of each class, so that the total area under bars is unity; if FALSE, each class is considered as a separate distribution and has area of unity.

total.area

a positive number specifying the total area under all the histograms. 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.

nlabels

integer, for the number of levels to be plotted; if 0, no label is plotted. The larger the number is, the more accurate the plot will be.

cols

the colors to fill the bars, with the same order as the class.

borders

the colors of the border around the bars.

the number of points within each bin to plot the circular histogram. The larger the number is, the smoother the plot looks.

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.

x.legend

x coordinate to plot the legend.

y.legend

y coordinate to plot the legend.

Value

No return value

References

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

Examples

Run this code

# NOT RUN {
# Load the dataset
library(circular)
data("pigeons", package = "circular")
x = pigeons[,2] / 180 * pi
y = pigeons[,1]

# stacked circular histograms
cmhist(x, y)             # area-proportional 
cmhist(x, y, area=FALSE) # height-proportional

# }