Package 'cplots' reference manual

Package 'cplots'

Title:	Plots for Circular Data
Description:	Provides functions to produce some circular plots for circular data, in a height- or area-proportional manner. They include bar plots, smooth density plots, stacked dot plots, histograms, multi-class stacked smooth density plots, and multi-class stacked histograms.
Authors:	Danli Xu [aut], Yong Wang [aut, cre]
Maintainer:	Yong Wang <[email protected]>
License:	GPL (>= 2)
Version:	0.5-0
Built:	2025-01-22 02:39:42 UTC
Source:	https://github.com/cran/cplots

Title:

Plots for Circular Data

Description:

Provides functions to produce some circular plots for circular data, in a height- or area-proportional manner. They include bar plots, smooth density plots, stacked dot plots, histograms, multi-class stacked smooth density plots, and multi-class stacked histograms.

Authors:

Danli Xu [aut], Yong Wang [aut, cre]

Maintainer:

Yong Wang <[email protected]>

License:

GPL (>= 2)

Version:

0.5-0

Built:

2025-01-22 02:39:42 UTC

Source:

https://github.com/cran/cplots

Help Index

Circular Bar Plot

Description

Function cbarplot can be used to plot 2-dimensional circular bar plots. The circular bar plots can only adopt the height-proportional transformation because of the white space between bars.

Usage

cbarplot(
  x,
  nbins = 36,
  radius = 1/sqrt(base::pi),
  prob = TRUE,
  nlabels = 4,
  col = NULL,
  border = NULL,
  m = NA,
  xlim = NULL,
  ylim = NULL,
  main = NULL
)
cbarplot(
  x,
  nbins = 36,
  radius = 1/sqrt(base::pi),
  prob = TRUE,
  nlabels = 4,
  col = NULL,
  border = NULL,
  m = NA,
  xlim = NULL,
  ylim = NULL,
  main = NULL
)

Arguments

`x`	a numeric vector storing angular values between 0 and 2 pi, or an object that can be coerced to.
`nbins`	the number of bins of the circular bar plot. Internally, it is rounded to a multiple of 4.
`radius`	the radius of the reference circle.
`prob`	logical; if `TRUE`, the circular histogram graphic is a representation of probability densities; if `FALSE`, a representation of frequencies.
`nlabels`	integer, for the number of levels to be plotted; if `0`, no label is plotted
`col`	the color to fill the bars.
`border`	the color of the border around the bars.
`m`	the number of points within each bin to plot the top of a bar. 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)

Value

No return value

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))

cbarplot(x)                     
cbarplot(x, prob=FALSE)
cbarplot(x, radius=1, nlabels=0, col="lightblue")
cbarplot(x, radius=1, col="lightblue", border="skyblue4")

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))

cbarplot(x)                     
cbarplot(x, prob=FALSE)
cbarplot(x, radius=1, nlabels=0, col="lightblue")
cbarplot(x, radius=1, col="lightblue", border="skyblue4")

Circular Density Curve

Description

Function cdensity can be used to plot 2-dimensional density curves for circular data.

Usage

cdensity(
  f,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  total.area = 1,
  nlabels = 4,
  add = FALSE,
  n = 500,
  col = "red",
  xlim = NULL,
  ylim = NULL,
  main = NULL
)
cdensity(
  f,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  total.area = 1,
  nlabels = 4,
  add = FALSE,
  n = 500,
  col = "red",
  xlim = NULL,
  ylim = NULL,
  main = NULL
)

Arguments

`f`	an R function that is to be plotted as a circular density or frequency.
`radius`	the radius of the reference circle. If `radius = 0`, no reference circle is produced, and the centre presents the point with zero density.
`area.prop`	logical; if `TRUE`, an area-proportional transformation is applied; if `FALSE`, a height-proportional transformation is applied.
`total.area`	a positive number specifying the total area under the density curve. 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.
`add`	logical; if `TRUE`, the density curve is superimposed to the current plot, for example, a circular histogram, a rose diagram or a stacked dot plot that has been produced in a similar manner.
`n`	the number of points to plot the density curve.
`col`	the color of the density line.
`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)

Value

No return value

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))
dvm = function(x, mu=0, kappa=1)   # von Mises density
  exp(kappa * cos(x - mu)) * (2 * pi * besselI(kappa, 0))^(-1)
f = function(x) 1/3 * dvm(x, pi/4, 5) + 2/3 * dvm(x, pi, 20)

cdensity(f)                # plot the density in an area-proportional manner

chist(x)                   # circular histogram
cdensity(f, add=TRUE)      # superimpose the density curve
chist(x, area=FALSE)       # height-proportional circular histogram
cdensity(f, area=FALSE, add=TRUE)   # superimpose the density curve

chist(x, radius=0)                          # rose diagrams
cdensity(f, radius=0, add=TRUE)
chist(x, radius=0, area=FALSE)
cdensity(f, radius=0, area=FALSE, add=TRUE)

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))
dvm = function(x, mu=0, kappa=1)   # von Mises density
  exp(kappa * cos(x - mu)) * (2 * pi * besselI(kappa, 0))^(-1)
f = function(x) 1/3 * dvm(x, pi/4, 5) + 2/3 * dvm(x, pi, 20)

cdensity(f)                # plot the density in an area-proportional manner

chist(x)                   # circular histogram
cdensity(f, add=TRUE)      # superimpose the density curve
chist(x, area=FALSE)       # height-proportional circular histogram
cdensity(f, area=FALSE, add=TRUE)   # superimpose the density curve

chist(x, radius=0)                          # rose diagrams
cdensity(f, radius=0, add=TRUE)
chist(x, radius=0, area=FALSE)
cdensity(f, radius=0, area=FALSE, add=TRUE)

Circular Stacked Dot Plot

Description

Function cdotplot can be used to plot 2-dimensional stacked dot plot for circular data.

Usage

cdotplot(
  x,
  nbins = 36,
  radius = 1,
  unit = NA,
  area.prop = TRUE,
  total.area = 1,
  m = NA,
  col = "lightblue",
  border = "skyblue4",
  xlim = NULL,
  ylim = NULL,
  main = NULL,
  x.legend = "bottomright",
  y.legend = NULL
)
cdotplot(
  x,
  nbins = 36,
  radius = 1,
  unit = NA,
  area.prop = TRUE,
  total.area = 1,
  m = NA,
  col = "lightblue",
  border = "skyblue4",
  xlim = NULL,
  ylim = NULL,
  main = NULL,
  x.legend = "bottomright",
  y.legend = NULL
)

Arguments

`x`	a circular data object that is fully defined by the user.
`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.
`unit`	the number of observations represented by each dot. If `unit > 1`, it means that each dot represents multiple observations.
`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 the density curve. 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.
`m`	the number of points within each bin to plot the circular dot plot. The larger the number is, the smoother the plot looks.
`col`	the color to fill the bars.
`border`	the color of the border around the bars.
`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)
`x.legend`	x coordinate to plot the legend.
`y.legend`	y coordinate to plot the legend.

Details

If the number of observations is relatively small, the usual circular stacked dot plot can be used with unit = 1. If the dataset is large, the dots may become too dense to visualize or count. Setting unit to be any positive integer to allow each dot to represent more than one observation. If the number of observations in one bin is not a multiple of the specified unit, a partial dot can be used to represent the remainder at the top of the bin.

Value

No return value

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

# 30 observations from two von Mises distributions
library(circular)
x = c(rvonmises(10, circular(pi/4), 5), rvonmises(20, circular(pi), 20))
cdotplot(x)                 # area-proportional dot plot
cdotplot(x, area = FALSE)   # height-proportional dot plot

# 900 observations from two von Mises distributions
y = c(rvonmises(300, circular(pi/4), 5), rvonmises(600, circular(pi), 20))
cdotplot(y, nbins=76, unit = 10)      # area-proportional (partial) dot plot 
cdotplot(y, nbins=76, unit = 10, area = FALSE) # height-proportional

# 30 observations from two von Mises distributions
library(circular)
x = c(rvonmises(10, circular(pi/4), 5), rvonmises(20, circular(pi), 20))
cdotplot(x)                 # area-proportional dot plot
cdotplot(x, area = FALSE)   # height-proportional dot plot

# 900 observations from two von Mises distributions
y = c(rvonmises(300, circular(pi/4), 5), rvonmises(600, circular(pi), 20))
cdotplot(y, nbins=76, unit = 10)      # area-proportional (partial) dot plot 
cdotplot(y, nbins=76, unit = 10, area = FALSE) # height-proportional

Circular Histogram and Rose Diagram

Description

Function chist can be used to plot 2-dimensional histograms and rose diagrams for circular data.

Usage

chist(
  x,
  nbins = 36,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  prob = TRUE,
  total.area = 1,
  nlabels = 4,
  col = "lightblue",
  border = "skyblue4",
  m = NA,
  xlim = NULL,
  ylim = NULL,
  main = NULL
)
chist(
  x,
  nbins = 36,
  radius = 1/sqrt(base::pi),
  area.prop = TRUE,
  prob = TRUE,
  total.area = 1,
  nlabels = 4,
  col = "lightblue",
  border = "skyblue4",
  m = NA,
  xlim = NULL,
  ylim = NULL,
  main = NULL
)

Arguments

`x`	a numeric vector storing angular values between 0 and 2 pi, or an object that can be coerced to.
`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.
`total.area`	a positive number specifying the total area under the density curve. 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 for the density/frequency values to be plotted; if `0`, no label is plotted
`col`	the color to fill the bars.
`border`	the color 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)

Value

No return value

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))

chist(x)                           # area-proportional circular histgram
chist(x, area = FALSE)             # height-proportional circular histgram
chist(x, radius=0)                 # area-proportional rose diagram
chist(x, radius=0, area=FALSE)     # height-proportional rose diagram

chist(x, prob=FALSE)               # labels for frequency
chist(x, nlabels=0)                # no label
chist(x, xlim=c(-1.7,1))           # use xlim
chist(x, area=FALSE, total=2)      # with scaling
chist(x, area=FALSE, total=NULL)   # without scaling

# 600 observations from two von Mises distributions
library(circular)
x = c(rvonmises(200, circular(pi/4), 5), rvonmises(400, circular(pi), 20))

chist(x)                           # area-proportional circular histgram
chist(x, area = FALSE)             # height-proportional circular histgram
chist(x, radius=0)                 # area-proportional rose diagram
chist(x, radius=0, area=FALSE)     # height-proportional rose diagram

chist(x, prob=FALSE)               # labels for frequency
chist(x, nlabels=0)                # no label
chist(x, xlim=c(-1.7,1))           # use xlim
chist(x, area=FALSE, total=2)      # with scaling
chist(x, area=FALSE, total=NULL)   # without scaling

Circular Transformation Formula

Description

The function performs circular transformation of density or frequency, in an area-proportional or height-proportional manner.

Usage

circtrans(x, radius = 0, area.prop = TRUE, factor = 1)
circtrans(x, radius = 0, area.prop = TRUE, factor = 1)

Arguments

`x`	a numeric vector storing angular values between 0 and 2 pi, or an object that can be coerced to.
`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.
`factor`	a positive number representing the scale factor to scale the entire plot.

Value

A numerical vector of the transformed values

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

library(circular)
x = as.vector(rvonmises(20, circular(pi), 10))
circtrans(x)                            # area-proportional transformation
circtrans(x, area.prop = FALSE)         # height-proportional transformation
circtrans(x, factor = 2)                # with a scaling factor

library(circular)
x = as.vector(rvonmises(20, circular(pi), 10))
circtrans(x)                            # area-proportional transformation
circtrans(x, area.prop = FALSE)         # height-proportional transformation
circtrans(x, factor = 2)                # with a scaling factor

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
)
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 <[email protected]>, Yong Wang <[email protected]>

References

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

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

# 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

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
)
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.
`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.

Value

No return value

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

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

# 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

Scaling Factor

Description

The function calculates the scaling factor so that after scaling the original density curve (before transformation), the total area after transformation (excluding the reference circle) has the specified value.

Usage

scalefactor(x, radius = 0, total.area = 1, area.prop = TRUE)
scalefactor(x, radius = 0, total.area = 1, area.prop = TRUE)

Arguments

`x`	a numeric vector storing the heights of a density curve or a histogram.
`radius`	the radius of the reference circle.
`total.area`	a positive number specifying the total area.
`area.prop`	logical; if `TRUE`, an area-proportional transformation is applied; if `FALSE`, a height-proportional transformationis applied.

Details

Each value in x is a density value before transformation, for points equally-spaced on $[0,2\pi)$ . For a smooth density curve, use a reasonably large number of points, equally-spaced on $[0,2\pi)$ . The area under the density curve after transformation is then approximated by that of the corresponding sectors. Note if area.prop = TRUE, the scale factor is simply the value of total.area.

Value

A numerical value for the scaling factor

Author(s)

Danli Xu <[email protected]>, Yong Wang <[email protected]>

References

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

Examples

dvm = function(x, mu=0, kappa=1)   # von Mises density
exp(kappa * cos(x - mu)) * (2 * pi * besselI(kappa, 0))^(-1)
x = dvm(seq(0, 2 * pi, len = 100), pi, 10)

scalefactor(x)                            # area-proportional transformation
scalefactor(x, area.prop = FALSE)         # height-proportional transformation
scalefactor(x, total.area = 2)            # total area of 2
scalefactor(x, area.prop = FALSE, total.area = 2)

dvm = function(x, mu=0, kappa=1)   # von Mises density
exp(kappa * cos(x - mu)) * (2 * pi * besselI(kappa, 0))^(-1)
x = dvm(seq(0, 2 * pi, len = 100), pi, 10)

scalefactor(x)                            # area-proportional transformation
scalefactor(x, area.prop = FALSE)         # height-proportional transformation
scalefactor(x, total.area = 2)            # total area of 2
scalefactor(x, area.prop = FALSE, total.area = 2)

Package 'cplots'

Help Index

Circular Bar Plot

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Circular Density Curve

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Circular Stacked Dot Plot

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Circular Histogram and Rose Diagram

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Circular Transformation Formula

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Multi-class Circular Density Curve

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Multi-class Stacked Circular Histogram and Rose Diagram

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Scaling Factor

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples