# cmhist: Multi-class Stacked Circular Histogram and Rose Diagram In cplots: Plots for Circular Data

 cmhist R Documentation

## 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,
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. `m` 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.

No return value

### Author(s)

Danli Xu <dxu452@aucklanduni.ac.nz>, Yong Wang <yongwang@auckland.ac.nz>

### References

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

`chist`, `cmdensity`

### Examples

```# 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

```

cplots documentation built on March 24, 2022, 9:05 a.m.