Package {ggcircular}

Signed angular difference

Description

Computes the signed difference x - y on a periodic scale. With the default period, values are returned in ⁠[-pi, pi)⁠.

Usage

angular_difference(x, y, period = 2 * pi)

Arguments

Value

A numeric vector following R recycling rules.

See Also

Other angle utilities: angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Examples

angular_difference(0, 3 * pi / 2)

Circular angular distance

Description

Computes the non-negative angular distance between x and y. With the default period, values are returned in ⁠[0, pi]⁠.

Usage

angular_distance(x, y, period = 2 * pi)

Arguments

Value

A non-negative numeric vector.

See Also

Other angle utilities: angular_difference(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Examples

angular_distance(0, 3 * pi / 2)

Simulated animal movement steps

Description

Simulated tracks for three individuals with derived step length, bearing and turn angle features.

Usage

animal_steps

Format

A tibble with 600 rows and 8 variables:

id

Animal identifier.

time

Step index.

x, y

Cartesian coordinates.

step_length

Euclidean step length.

bearing

Movement bearing in radians under the mathematical convention.

turn_angle

Signed turn angle in radians.

state

Latent movement state label.

Source

Simulated for package examples.

Convert posterior draws to circular draws

Description

Converts objects supported by posterior::as_draws_df() into a long tibble of normalized angular draws.

Usage

as_circular_draws(draws, variables = NULL, period = 2 * pi, origin = 0)

Arguments

Value

A tibble with draw identifiers, .variable and .angle.

See Also

Other posterior helpers: autoplot_circular_draws(), summarise_circular_draws()

Coerce to step data

Description

Thin wrapper around mutate_directional_features() for pipelines where a more explicit movement-data verb is useful.

Usage

as_step_data(
  data,
  x,
  y,
  id = NULL,
  time = NULL,
  angle_convention = c("mathematical", "bearing")
)

Arguments

Value

A tibble with movement features.

See Also

Other movement helpers: augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Circular model helper generics

Description

Lightweight generics reserved for future integration with angular regression packages. The default methods fail with an explicit message rather than silently returning incomplete output.

Usage

augment_circular(x, ...)

tidy_circular(x, ...)

glance_circular(x, ...)

Arguments

Value

Method-dependent tibble output.

See Also

Other circular model helpers: circular_model_diagnostics(), circular_residuals()

Augment momentuHMM fits with angular states

Description

Extracts an angle column and inferred states from a fitted momentuHMM model. The function uses momentuHMM::viterbi() by default and adds state probabilities when momentuHMM::stateProbs() is available.

Usage

augment_momentuHMM_angles(
  object,
  data = NULL,
  angle = NULL,
  state_method = c("viterbi", "stateProbs"),
  ...
)

Arguments

Value

A tibble with .angle, .state and optional state probabilities.

See Also

Other movement helpers: as_step_data(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Autoplot circular data

Description

Creates a quick diagnostic plot for a numeric vector of circular angles.

Usage

autoplot_circular(
  theta,
  bins = 24,
  density = TRUE,
  mean = TRUE,
  axial = FALSE,
  ...
)

Arguments

Value

A ggplot object.

Examples

autoplot_circular(wind_directions$direction)

Autoplot circular posterior draws

Description

Autoplot circular posterior draws

Usage

autoplot_circular_draws(
  draws,
  variables = NULL,
  type = c("density", "interval"),
  axial = FALSE,
  ...
)

Arguments

Value

A ggplot object.

See Also

Other posterior helpers: as_circular_draws(), summarise_circular_draws()

Simulated axial orientations

Description

Simulated axial orientation data, such as fiber or fault orientations, stored modulo pi.

Usage

axial_orientations

Format

A tibble with 300 rows and 3 variables:

sample

Sample identifier.

orientation

Axial orientation in radians, modulo pi.

group

Group label.

Source

Simulated for package examples.

Convert Cartesian coordinates to spherical coordinates

Description

Convert Cartesian coordinates to spherical coordinates

Usage

cartesian_to_spherical(
  x,
  y,
  z,
  convention = c("azimuth_colatitude", "azimuth_elevation")
)

Arguments

Value

A tibble with theta, phi and radius.

See Also

Other spherical helpers: spherical_summary(), spherical_to_cartesian()

Check an angle vector

Description

Check an angle vector

Usage

check_angle(x, allow_na = TRUE)

Arguments

Value

Invisibly returns x if the check succeeds.

See Also

Other angle utilities: angular_difference(), angular_distance(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Confidence interval for a circular mean

Description

Computes an approximate confidence interval for a circular mean. The large sample method uses a normal approximation on the mean direction, while the bootstrap method resamples angles and forms an interval from angular deviations around the sample mean. These intervals are exploratory; they are not reliable when the mean resultant length is close to zero and the mean direction is weakly identified.

Usage

circular_mean_ci(
  x,
  level = 0.95,
  method = c("large_sample", "bootstrap"),
  R = 999,
  axial = FALSE,
  na.rm = TRUE,
  seed = NULL
)

Arguments

Value

A tibble with mean, lower, upper, level, method, n and Rbar.

See Also

Other circular summaries: circular_sd(), circular_summary(), circular_variance(), estimate_kappa(), mean_direction(), mean_resultant_length(), resultant_length()

Circular model diagnostics

Description

Summarizes circular residual diagnostics for supported angular model objects.

Usage

circular_model_diagnostics(object, data = NULL, ...)

Arguments

Value

A tibble with residual mean direction, resultant length, circular variance and maximum absolute circular residual.

See Also

Other circular model helpers: augment_circular(), circular_residuals()

Circular residuals for angular models

Description

Extracts observed angles, fitted angles and signed circular residuals from supported angular model objects. The function currently supports objects produced by the optional CircularRegression package when their fitted values are stored in a mui component.

Usage

circular_residuals(object, data = NULL, ...)

Arguments

Value

A tibble with .observed, .fitted, .resid, .abs_resid, .index and .model_class.

See Also

Other circular model helpers: augment_circular(), circular_model_diagnostics()

Examples

fit <- structure(
  list(y = c(0, 0.2, 0.4), mui = c(0.05, 0.15, 0.5)),
  class = "angular"
)
circular_residuals(fit)

Circular standard deviation

Description

Uses the common descriptive statistic sqrt(-2 * log(Rbar)).

Usage

circular_sd(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

Circular standard deviation in radians.

See Also

Other circular summaries: circular_mean_ci(), circular_summary(), circular_variance(), estimate_kappa(), mean_direction(), mean_resultant_length(), resultant_length()

Summarize circular data

Description

Computes grouped circular summaries for an angle column. Existing dplyr groups are respected, and additional grouping variables can be supplied in ....

Usage

circular_summary(data, angle, ..., axial = FALSE, na.rm = TRUE)

Arguments

Value

A tibble with columns n, mean, R, Rbar, variance, sd and kappa. The returned object also has class ggcircular_summary.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_variance(), estimate_kappa(), mean_direction(), mean_resultant_length(), resultant_length()

Examples

tibble::tibble(group = c("a", "a", "b"), theta = c(0, pi / 2, pi)) |>
  dplyr::group_by(group) |>
  circular_summary(theta)

Circular variance

Description

Circular variance

Usage

circular_variance(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

The circular variance 1 - Rbar.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_summary(), estimate_kappa(), mean_direction(), mean_resultant_length(), resultant_length()

Convert compass labels to radians

Description

Converts the eight standard compass labels N, NE, E, SE, S, SW, W and NW to bearing angles in radians, where zero is north and angles increase clockwise.

Usage

compass_to_rad(x)

Arguments

Value

Numeric vector of bearing angles in radians.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Examples

compass_to_rad(c("N", "E", "S", "W"))

Compute bearings

Description

Compute bearings

Usage

compute_bearing(x, y, angle_convention = c("mathematical", "bearing"))

Arguments

Value

Numeric vector of bearings in radians. The first value is NA.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_step_length(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Compute step lengths

Description

Compute step lengths

Usage

compute_step_length(x, y)

Arguments

Value

Numeric vector of Euclidean step lengths. The first value is NA.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Compute turn angles

Description

Compute turn angles

Usage

compute_turn_angle(bearing, period = 2 * pi)

Arguments

Value

Numeric vector of signed turn angles. The first value is NA.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Circular coordinate system

Description

Convenience wrapper around ggplot2::coord_polar() with arguments expressed in circular-data language.

Usage

coord_circular(
  zero = c("east", "north", "west", "south"),
  direction = c("counterclockwise", "clockwise"),
  start = NULL,
  clip = "on"
)

Arguments

Details

zero = "east" and direction = "counterclockwise" gives the usual mathematical convention: zero points east and positive angles rotate toward north. zero = "north" and direction = "clockwise" gives the usual bearing convention used for compass directions.

Value

A ggplot2 coordinate object.

See Also

Other circular scales: scale_x_circular_radians()

Examples

coord_circular()
coord_circular(zero = "north", direction = "clockwise")

Convert degrees to radians

Description

Convert degrees to radians

Usage

deg_to_rad(x)

Arguments

Value

Numeric vector in radians.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Estimate von Mises concentration

Description

Estimates the von Mises concentration parameter from the mean resultant length using the standard piecewise approximation described by Fisher (1993). This is a descriptive approximation and does not apply small-sample bias corrections or uncertainty quantification.

Usage

estimate_kappa(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

Estimated concentration parameter kappa.

References

Fisher, N. I. (1993). Statistical Analysis of Circular Data. Cambridge University Press.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_summary(), circular_variance(), mean_direction(), mean_resultant_length(), resultant_length()

Fit a mixture of von Mises distributions

Description

Fits a finite mixture of von Mises components using an expectation maximization algorithm. For axial data, the algorithm fits doubled angles and returns component means on the original modulo-pi scale.

Usage

fit_vonmises_mixture(
  x,
  k = 2,
  weights = NULL,
  axial = FALSE,
  init = c("kmeans", "spaced"),
  nstart = 1,
  init_params = NULL,
  kappa_max = 10000,
  min_component_weight = 1e-08,
  max_iter = 200,
  tol = 1e-08,
  na.rm = TRUE,
  seed = NULL
)

Arguments

Value

An object of class ggcircular_vonmises_mixture.

See Also

Other circular distributions: stat_vonmises(), stat_vonmises_fit(), stat_vonmises_mixture()

Examples

fit <- fit_vonmises_mixture(wind_directions$direction, k = 2)
tidy_circular(fit)

Circular density layer

Description

Draws a circular density estimate as a line. This is a convenience wrapper around stat_circular_density().

Usage

geom_circular_density(
  mapping = NULL,
  data = NULL,
  stat = "circular_density",
  position = "identity",
  ...,
  method = c("kernel", "vonmises"),
  bw = NULL,
  adjust = 1,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other circular density layers: stat_circular_density()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  geom_circular_density()

Circular point and rug helpers

Description

Convenience layers for plotting angular observations at a fixed radius.

Usage

geom_circular_point(
  mapping = NULL,
  data = NULL,
  ...,
  radius = 1,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_circular_rug(
  mapping = NULL,
  data = NULL,
  ...,
  radius = 1,
  rug_length = 0.05,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_direction_arrow(), mutate_directional_features(), plot_state_angles()

Circular confidence arc

Description

Draws angular intervals as arcs at a fixed radius. Intervals crossing zero are split into two path segments.

Usage

geom_confidence_arc(
  mapping = NULL,
  data = NULL,
  ...,
  radius = 1,
  n = 200,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_circular_interval(
  mapping = NULL,
  data = NULL,
  ...,
  radius = 1,
  n = 200,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

Examples

tibble::tibble(lower = 5.5, upper = 0.5) |>
  ggplot2::ggplot(ggplot2::aes(xmin = lower, xmax = upper)) +
  geom_confidence_arc()

Direction arrows

Description

Draws directional arrows from Cartesian coordinates and an angle.

Usage

geom_direction_arrow(
  mapping = NULL,
  data = NULL,
  ...,
  length = 1,
  arrow_length = grid::unit(0.15, "cm"),
  angle_convention = c("mathematical", "bearing"),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_circular_point(), mutate_directional_features(), plot_state_angles()

Examples

ggplot2::ggplot(animal_steps, ggplot2::aes(x = x, y = y, angle = bearing)) +
  geom_direction_arrow()

Mean direction layer

Description

Draws a radial segment at the circular mean direction. The segment length can be fixed or proportional to the mean resultant length.

Usage

geom_mean_direction(
  mapping = NULL,
  data = NULL,
  stat = "mean_direction",
  position = "identity",
  ...,
  length = c("resultant", "fixed"),
  radius = NULL,
  conf.int = FALSE,
  level = 0.95,
  axial = FALSE,
  arrow = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other mean direction layers: stat_mean_direction()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  geom_rose(bins = 16) +
  geom_mean_direction()

Rose diagram layer

Description

geom_rose() is a convenience wrapper around stat_rose() using a bar geometry. It is designed to be used with coord_circular() or ggplot2::coord_polar().

Usage

geom_rose(
  mapping = NULL,
  data = NULL,
  stat = "rose",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  boundary = 0,
  closed = TRUE,
  area = FALSE,
  normalize = c("count", "density", "proportion"),
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other rose diagram layers: stat_rose()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  geom_rose(bins = 16) +
  coord_circular()

Convert hours to radians

Description

Convert hours to radians

Usage

hour_to_rad(x)

Arguments

Value

Numeric vector in radians.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Simulated hourly activity

Description

A reproducible simulated dataset of hourly activity converted to circular angles.

Usage

hourly_activity

Format

A tibble with 240 rows and 5 variables:

id

Individual identifier.

hour

Hour of day.

angle

Hour converted to radians.

activity

Activity level.

group

Group label.

Source

Simulated for package examples.

Test whether an object can represent angles

Description

Test whether an object can represent angles

Usage

is_angle(x)

Arguments

Value

TRUE when x is numeric and contains only finite values or NA.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), normalize_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Circular mean direction

Description

Computes the sample mean direction. For axial data, angles are doubled before computing the mean and the result is transformed back to the axial scale.

Usage

mean_direction(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

A single angle in radians, or NA_real_ when the mean is undefined.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_summary(), circular_variance(), estimate_kappa(), mean_resultant_length(), resultant_length()

Examples

mean_direction(c(0, pi / 4, pi / 2))

Mean resultant length

Description

Mean resultant length

Usage

mean_resultant_length(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

The mean resultant length Rbar, between 0 and 1 when defined.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_summary(), circular_variance(), estimate_kappa(), mean_direction(), resultant_length()

Add directional movement features

Description

Computes step length, bearing and turn angle from track coordinates. When id and time are supplied, records are sorted by individual and time before features are computed.

Usage

mutate_directional_features(
  data,
  x,
  y,
  id = NULL,
  time = NULL,
  angle_convention = c("mathematical", "bearing")
)

Arguments

Value

A tibble with added step_length, bearing and turn_angle.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), plot_state_angles()

Examples

tibble::tibble(id = 1, time = 1:3, x = 0:2, y = 0) |>
  mutate_directional_features(x = x, y = y, id = id, time = time)

Normalize angles to a periodic interval

Description

normalize_angle() maps numeric angles to ⁠[origin, origin + period)⁠. The default period is 2 * pi, which is appropriate for directional circular data measured in radians.

Usage

normalize_angle(x, period = 2 * pi, origin = 0)

Arguments

Value

A numeric vector with the same length as x.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), rad_to_compass(), rad_to_deg(), rad_to_hour()

Examples

normalize_angle(c(-pi, 0, 3 * pi))

Plot angular distributions by state

Description

Convenience function for visualizing angles by observed or inferred states.

Usage

plot_state_angles(
  data,
  angle,
  state,
  type = c("rose", "density", "mean"),
  bins = 24,
  axial = FALSE
)

Arguments

Value

A ggplot object.

See Also

Other movement helpers: as_step_data(), augment_momentuHMM_angles(), compute_bearing(), compute_step_length(), compute_turn_angle(), geom_circular_point(), geom_direction_arrow(), mutate_directional_features()

Convert radians to compass labels

Description

Converts angles to the nearest label among labels. Angles are interpreted as bearings by default: zero is north and angles increase clockwise.

Usage

rad_to_compass(x, labels = c("N", "NE", "E", "SE", "S", "SW", "W", "NW"))

Arguments

Value

Character vector of labels.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_deg(), rad_to_hour()

Examples

rad_to_compass(c(0, pi / 2, pi))

Convert radians to degrees

Description

Convert radians to degrees

Usage

rad_to_deg(x)

Arguments

Value

Numeric vector in degrees.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_hour()

Convert radians to hours

Description

Convert radians to hours

Usage

rad_to_hour(x)

Arguments

Value

Numeric vector in hours on a 24-hour clock.

See Also

Other angle utilities: angular_difference(), angular_distance(), check_angle(), compass_to_rad(), deg_to_rad(), hour_to_rad(), is_angle(), normalize_angle(), rad_to_compass(), rad_to_deg()

Rayleigh test for circular uniformity

Description

Performs the one-sample Rayleigh test for non-uniformity. The test is most sensitive to unimodal departures from circular uniformity. The returned object follows the base htest structure.

Usage

rayleigh_test(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

An object of class htest.

See Also

Other circular tests: stat_circular_test(), watson_williams_test()

Resultant length

Description

Resultant length

Usage

resultant_length(x, axial = FALSE, na.rm = TRUE)

Arguments

Value

The sample resultant length R.

See Also

Other circular summaries: circular_mean_ci(), circular_sd(), circular_summary(), circular_variance(), estimate_kappa(), mean_direction(), mean_resultant_length()

Circular x scales

Description

These scales label angular x axes in radians, degrees, hours or compass directions.

Usage

scale_x_circular_radians(
  breaks = ggplot2::waiver(),
  labels = ggplot2::waiver(),
  limits = c(0, 2 * pi),
  ...
)

scale_x_circular_degrees(
  breaks = ggplot2::waiver(),
  labels = ggplot2::waiver(),
  limits = c(0, 2 * pi),
  ...
)

scale_x_circular_hours(
  breaks = ggplot2::waiver(),
  labels = ggplot2::waiver(),
  limits = c(0, 2 * pi),
  ...
)

scale_x_circular_compass(
  breaks = ggplot2::waiver(),
  labels = ggplot2::waiver(),
  limits = c(0, 2 * pi),
  ...
)

Arguments

Value

A ggplot2 scale.

See Also

Other circular scales: coord_circular()

Examples

scale_x_circular_radians()

Summarize spherical directions

Description

Computes the mean direction vector and mean spherical coordinates.

Usage

spherical_summary(
  theta,
  phi,
  weights = NULL,
  convention = c("azimuth_colatitude", "azimuth_elevation"),
  na.rm = TRUE
)

Arguments

Value

A tibble with sample size, mean spherical coordinates and resultant length.

See Also

Other spherical helpers: cartesian_to_spherical(), spherical_to_cartesian()

Convert spherical coordinates to Cartesian coordinates

Description

Convert spherical coordinates to Cartesian coordinates

Usage

spherical_to_cartesian(
  theta,
  phi,
  radius = 1,
  convention = c("azimuth_colatitude", "azimuth_elevation")
)

Arguments

Value

A tibble with x, y and z.

See Also

Other spherical helpers: cartesian_to_spherical(), spherical_summary()

Circular density statistic

Description

Estimates a smooth circular density using a von Mises kernel. The density wraps around the origin, avoiding the boundary artifacts of a linear kernel density estimate. When bw is not supplied, the concentration is chosen from a simple resultant-length heuristic; it should be treated as an exploratory smoothing choice rather than an inferential bandwidth selector.

Usage

stat_circular_density(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  method = c("kernel", "vonmises"),
  bw = NULL,
  adjust = 1,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer. Computed variables are x, density, scaled, count, n, bw and kappa.

See Also

Other circular density layers: geom_circular_density()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  stat_circular_density()

Annotate circular tests

Description

Adds a text annotation with the p-value from a Rayleigh or Watson-Williams test.

Usage

stat_circular_test(
  mapping = NULL,
  data = NULL,
  geom = "text",
  position = "identity",
  ...,
  test = c("rayleigh", "watson_williams"),
  x = 0,
  y = 1,
  digits = 3,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other circular tests: rayleigh_test(), watson_williams_test()

Mean direction statistic

Description

Computes one mean direction per group, with resultant length and an optional approximate confidence arc.

Usage

stat_mean_direction(
  mapping = NULL,
  data = NULL,
  geom = "segment",
  position = "identity",
  ...,
  length = c("resultant", "fixed"),
  radius = NULL,
  conf.int = FALSE,
  level = 0.95,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer. Computed variables include x, xend, y, yend, mean, R, Rbar, n, kappa, ci_low and ci_high.

See Also

Other mean direction layers: geom_mean_direction()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  stat_mean_direction()

Rose diagram statistic

Description

Bins circular angles over a full period and returns counts, densities and proportions for rose diagrams.

Usage

stat_rose(
  mapping = NULL,
  data = NULL,
  geom = "col",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  boundary = 0,
  closed = TRUE,
  area = FALSE,
  normalize = c("count", "density", "proportion"),
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer. Computed variables are xmin, xmax, x, count, density, proportion, width and y.

See Also

Other rose diagram layers: geom_rose()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  stat_rose(bins = 16) +
  coord_circular()

Theoretical von Mises density

Description

Adds a theoretical von Mises density to a circular plot.

Usage

stat_vonmises(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  mu = 0,
  kappa = 1,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

stat_wrapped_normal(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  mu = 0,
  sigma = 1,
  terms = 5,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

stat_uniform_circular(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

Arguments

Value

A ggplot2 layer.

See Also

Other circular distributions: fit_vonmises_mixture(), stat_vonmises_fit(), stat_vonmises_mixture()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) +
  stat_vonmises(mu = pi / 2, kappa = 3)

Fitted von Mises density

Description

Estimates mu with mean_direction() and kappa with estimate_kappa(), then draws the fitted von Mises density.

Usage

stat_vonmises_fit(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other circular distributions: fit_vonmises_mixture(), stat_vonmises(), stat_vonmises_mixture()

Examples

ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) +
  geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) +
  stat_vonmises_fit()

Von Mises mixture density layer

Description

Fits or draws a mixture of von Mises densities.

Usage

stat_vonmises_mixture(
  mapping = NULL,
  data = NULL,
  geom = "line",
  position = "identity",
  ...,
  fit = NULL,
  k = 2,
  nstart = 1,
  seed = NULL,
  kappa_max = 10000,
  n = 512,
  axial = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer.

See Also

Other circular distributions: fit_vonmises_mixture(), stat_vonmises(), stat_vonmises_fit()

Summarize circular posterior draws

Description

Summarize circular posterior draws

Usage

summarise_circular_draws(
  draws,
  variables = NULL,
  level = 0.95,
  axial = FALSE,
  ...
)

Arguments

Value

A tibble with posterior circular summaries.

See Also

Other posterior helpers: as_circular_draws(), autoplot_circular_draws()

Circular plot themes

Description

Lightweight themes for circular plots. They keep a restrained grid and avoid imposing a strong visual identity.

Usage

theme_circular(base_size = 12, base_family = "")

theme_rose(base_size = 12, base_family = "")

theme_compass(base_size = 12, base_family = "")

Arguments

Value

A ggplot2 theme.

Examples

theme_circular()

Watson-Williams test for equal circular means

Description

Wrapper around circular::watson.williams.test() with explicit optional dependency handling. The Watson-Williams test assumes von Mises-like groups with comparable concentrations and should be used cautiously for small samples or weakly concentrated data.

Usage

watson_williams_test(x, group, ...)

Arguments

Value

An object returned by circular::watson.williams.test().

See Also

Other circular tests: rayleigh_test(), stat_circular_test()

Simulated wind directions

Description

A reproducible simulated dataset of wind directions with station, speed and season variables. Angles are stored in radians.

Usage

wind_directions

Format

A tibble with 500 rows and 4 variables:

station

Station identifier.

direction

Wind direction in radians.

speed

Wind speed in arbitrary units.

season

Season label.

Source

Simulated for package examples.