| Title: | A 'ggplot2' Extension for Circular, Cylindrical and Toroidal Data |
|---|---|
| Description: | Provides a 'ggplot2' grammar for circular, axial and directional data, including rose diagrams, circular densities, mean directions, confidence arcs, theoretical circular distributions, movement data visualizations, and displays for circular-linear and circular-circular dependence on cylinders and tori. |
| Authors: | Aurélien Nicosia [aut, cre] |
| Maintainer: | Aurélien Nicosia <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-09-19 09:14:35 UTC |
| Source: | https://github.com/aureliennicosiaulaval/ggcircular |
Computes |mean(exp(i * (phi - theta)))|, a scalar summary of circular
alignment between two angular variables.
alignment_index(theta, phi)alignment_index(theta, phi)
theta |
First angle in radians. |
phi |
Second angle in radians. |
A numeric scalar between 0 and 1.
Other directional dependence indicators:
conditional_variation_index(),
local_circ_moment()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) alignment_index(dat$theta, dat$phi)dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) alignment_index(dat$theta, dat$phi)
Computes the signed difference x - y on a periodic scale. With the default
period, values are returned in [-pi, pi).
angular_difference(x, y, period = 2 * pi)angular_difference(x, y, period = 2 * pi)
x, y
|
Numeric vectors of angles. |
period |
Positive numeric period. |
A numeric vector following R recycling rules.
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()
angular_difference(0, 3 * pi / 2)angular_difference(0, 3 * pi / 2)
Computes the non-negative angular distance between x and y. With the
default period, values are returned in [0, pi].
angular_distance(x, y, period = 2 * pi)angular_distance(x, y, period = 2 * pi)
x, y
|
Numeric vectors of angles. |
period |
Positive numeric period. |
A non-negative numeric vector.
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()
angular_distance(0, 3 * pi / 2)angular_distance(0, 3 * pi / 2)
Simulated tracks for three individuals with derived step length, bearing and turn angle features.
animal_stepsanimal_steps
A tibble with 600 rows and 8 variables:
Animal identifier.
Step index.
Cartesian coordinates.
Euclidean step length.
Movement bearing in radians under the mathematical convention.
Signed turn angle in radians.
Latent movement state label.
Simulated for package examples.
Converts objects supported by posterior::as_draws_df() into a long tibble
of normalized angular draws.
as_circular_draws(draws, variables = NULL, period = 2 * pi, origin = 0)as_circular_draws(draws, variables = NULL, period = 2 * pi, origin = 0)
draws |
Posterior draws object. |
variables |
Optional variables to keep. |
period |
Angular period. |
origin |
Lower bound of the normalized interval. |
A tibble with draw identifiers, .variable and .angle.
Other posterior helpers:
autoplot_circular_draws(),
summarise_circular_draws()
Thin wrapper around mutate_directional_features() for pipelines where a
more explicit movement-data verb is useful.
as_step_data( data, x, y, id = NULL, time = NULL, angle_convention = c("mathematical", "bearing") )as_step_data( data, x, y, id = NULL, time = NULL, angle_convention = c("mathematical", "bearing") )
data |
A data frame. |
x, y
|
Coordinate columns. |
id |
Optional individual identifier column. |
time |
Optional time column used for sorting within individual. |
angle_convention |
Angle convention passed to |
A tibble with movement features.
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()
Lightweight generics reserved for future integration with angular regression packages. The default methods fail with an explicit message rather than silently returning incomplete output.
augment_circular(x, ...) tidy_circular(x, ...) glance_circular(x, ...)augment_circular(x, ...) tidy_circular(x, ...) glance_circular(x, ...)
x |
A model or circular object. |
... |
Additional arguments passed to methods. |
Method-dependent tibble output.
Other circular model helpers:
circular_model_diagnostics(),
circular_residuals()
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.
augment_momentuHMM_angles( object, data = NULL, angle = NULL, state_method = c("viterbi", "stateProbs"), ... )augment_momentuHMM_angles( object, data = NULL, angle = NULL, state_method = c("viterbi", "stateProbs"), ... )
object |
A fitted |
data |
Optional data frame. If |
angle |
Optional name of the angle column. |
state_method |
State extraction method. |
... |
Reserved for future methods. |
A tibble with .angle, .state and optional state probabilities.
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()
Creates a quick diagnostic plot for a numeric vector of circular angles.
autoplot_circular( theta, bins = 24, density = TRUE, mean = TRUE, axial = FALSE, ... )autoplot_circular( theta, bins = 24, density = TRUE, mean = TRUE, axial = FALSE, ... )
theta |
Numeric vector of angles in radians. |
bins |
Number of rose diagram bins. |
density |
Should a circular density estimate be added? |
mean |
Should the mean direction be added? |
axial |
Should the data be treated as axial, modulo |
... |
Additional arguments currently ignored. |
A ggplot object.
autoplot_circular(wind_directions$direction)autoplot_circular(wind_directions$direction)
Autoplot circular posterior draws
autoplot_circular_draws( draws, variables = NULL, type = c("density", "interval"), axial = FALSE, ... )autoplot_circular_draws( draws, variables = NULL, type = c("density", "interval"), axial = FALSE, ... )
draws |
Circular draws or posterior draws. |
variables |
Optional variables to plot. |
type |
Plot type. |
axial |
Should draws be treated as axial, modulo |
... |
Additional arguments passed to |
A ggplot object.
Other posterior helpers:
as_circular_draws(),
summarise_circular_draws()
Plot bootstrap uncertainty for a statistical orbit
## S3 method for class 'bootstrap_stat_orbit' autoplot( object, ..., quantity = c("mu", "sigma"), base_size = 11, ribbon_fill = "#8fb4ff", line_colour = "#123f9b" )## S3 method for class 'bootstrap_stat_orbit' autoplot( object, ..., quantity = c("mu", "sigma"), base_size = 11, ribbon_fill = "#8fb4ff", line_colour = "#123f9b" )
object |
Object returned by |
... |
Reserved for future extensions. |
quantity |
Either |
base_size |
Base font size. |
ribbon_fill |
Ribbon fill colour. |
line_colour |
Line colour. |
A ggplot object.
Other directional uncertainty helpers:
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
plot_marginal_support(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_cylindrical(n = 60, seed = 1) boot <- bootstrap_stat_orbit(dat$theta, dat$x, n_boot = 5, n_theta = 12, seed = 1) ggplot2::autoplot(boot)dat <- simulate_cylindrical(n = 60, seed = 1) boot <- bootstrap_stat_orbit(dat$theta, dat$x, n_boot = 5, n_theta = 12, seed = 1) ggplot2::autoplot(boot)
Plot bootstrap uncertainty for a toroidal ridge
## S3 method for class 'bootstrap_toroidal_ridge' autoplot( object, ..., quantity = c("rho", "ridge"), base_size = 11, ribbon_fill = "#99d9d0", line_colour = "#0f766e" )## S3 method for class 'bootstrap_toroidal_ridge' autoplot( object, ..., quantity = c("rho", "ridge"), base_size = 11, ribbon_fill = "#99d9d0", line_colour = "#0f766e" )
object |
Object returned by |
... |
Reserved for future extensions. |
quantity |
Either |
base_size |
Base font size. |
ribbon_fill |
Ribbon fill colour. |
line_colour |
Line colour. |
A ggplot object.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
plot_marginal_support(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_toroidal(n = 60, scenario = "diagonal", seed = 1) boot <- bootstrap_toroidal_ridge(dat$theta, dat$phi, n_boot = 5, n_theta = 12, n_phi = 12, seed = 1) ggplot2::autoplot(boot)dat <- simulate_toroidal(n = 60, scenario = "diagonal", seed = 1) boot <- bootstrap_toroidal_ridge(dat$theta, dat$phi, n_boot = 5, n_theta = 12, n_phi = 12, seed = 1) ggplot2::autoplot(boot)
Plot diagnostic atlas data
## S3 method for class 'diagnostic_atlas_data' autoplot( object, ..., point_alpha = 0.2, point_size = 0.7, smooth = TRUE, base_size = 11 )## S3 method for class 'diagnostic_atlas_data' autoplot( object, ..., point_alpha = 0.2, point_size = 0.7, smooth = TRUE, base_size = 11 )
object |
Object returned by |
... |
Reserved for future extensions. |
point_alpha |
Point transparency. |
point_size |
Point size. |
smooth |
Should a loess smooth be added for cylindrical data? |
base_size |
Base font size. |
A ggplot object.
Other directional diagnostics:
diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_classical_comparison(),
plot_diagnostic_atlas(),
simulate_cyl_diagnostic(),
simulate_tor_diagnostic()
atlas <- diagnostic_atlas_data("cylindrical", n = 20, seed = 1) ggplot2::autoplot(atlas)atlas <- diagnostic_atlas_data("cylindrical", n = 20, seed = 1) ggplot2::autoplot(atlas)
Simulated axial orientation data, such as fiber or fault orientations, stored
modulo pi.
axial_orientationsaxial_orientations
A tibble with 300 rows and 3 variables:
Sample identifier.
Axial orientation in radians, modulo pi.
Group label.
Simulated for package examples.
Bootstrap a statistical orbit
bootstrap_stat_orbit( theta, x, n_boot = 100, n_theta = 181, kappa = 20, seed = NULL )bootstrap_stat_orbit( theta, x, n_boot = 100, n_theta = 181, kappa = 20, seed = NULL )
theta |
Angles in radians. |
x |
Real-valued response. |
n_boot |
Number of bootstrap resamples. |
n_theta |
Number of angular grid points. |
kappa |
Circular concentration for local weighting. |
seed |
Optional random seed. |
A data frame with point estimates and bootstrap intervals. The
returned object has class bootstrap_stat_orbit.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
plot_marginal_support(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_cylindrical(n = 60, seed = 1) bootstrap_stat_orbit(dat$theta, dat$x, n_boot = 5, n_theta = 12, seed = 1)dat <- simulate_cylindrical(n = 60, seed = 1) bootstrap_stat_orbit(dat$theta, dat$x, n_boot = 5, n_theta = 12, seed = 1)
Bootstrap a toroidal conditional ridge
bootstrap_toroidal_ridge( theta, phi, n_boot = 100, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, level = 0.95, seed = NULL )bootstrap_toroidal_ridge( theta, phi, n_boot = 100, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, level = 0.95, seed = NULL )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_boot |
Number of bootstrap resamples. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
level |
Coverage level for the pointwise circular bootstrap interval. |
seed |
Optional random seed. |
A data frame with ridge and local concentration intervals. The
returned object has class bootstrap_toroidal_ridge.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
marginal_support_data(),
plot_marginal_support(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_toroidal(n = 60, scenario = "diagonal", seed = 1) bootstrap_toroidal_ridge(dat$theta, dat$phi, n_boot = 5, n_theta = 12, n_phi = 12, seed = 1)dat <- simulate_toroidal(n = 60, scenario = "diagonal", seed = 1) bootstrap_toroidal_ridge(dat$theta, dat$phi, n_boot = 5, n_theta = 12, n_phi = 12, seed = 1)
Convert Cartesian coordinates to spherical coordinates
cartesian_to_spherical( x, y, z, convention = c("azimuth_colatitude", "azimuth_elevation") )cartesian_to_spherical( x, y, z, convention = c("azimuth_colatitude", "azimuth_elevation") )
x, y, z
|
Cartesian coordinates. |
convention |
Output convention for |
A tibble with theta, phi and radius.
Other spherical helpers:
spherical_summary(),
spherical_to_cartesian()
Check an angle vector
check_angle(x, allow_na = TRUE)check_angle(x, allow_na = TRUE)
x |
Object to check. |
allow_na |
Should missing values be allowed? |
Invisibly returns x if the check succeeds.
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()
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.
circular_mean_ci( x, level = 0.95, method = c("large_sample", "bootstrap"), R = 999, axial = FALSE, na.rm = TRUE, seed = NULL )circular_mean_ci( x, level = 0.95, method = c("large_sample", "bootstrap"), R = 999, axial = FALSE, na.rm = TRUE, seed = NULL )
x |
Numeric vector of angles in radians. |
level |
Confidence level. |
method |
Interval method. |
R |
Number of bootstrap resamples. |
axial |
Should data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
seed |
Optional random seed for the bootstrap. |
A tibble with mean, lower, upper, level, method, n and
Rbar.
Other circular summaries:
circular_sd(),
circular_summary(),
circular_variance(),
estimate_kappa(),
mean_direction(),
mean_resultant_length(),
resultant_length()
Summarizes circular residual diagnostics for supported angular model objects.
circular_model_diagnostics(object, data = NULL, ...)circular_model_diagnostics(object, data = NULL, ...)
object |
A supported angular model object. |
data |
Optional data frame to bind to the diagnostic columns. |
... |
Reserved for future methods. |
A tibble with residual mean direction, resultant length, circular variance and maximum absolute circular residual.
Other circular model helpers:
augment_circular(),
circular_residuals()
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.
circular_residuals(object, data = NULL, ...)circular_residuals(object, data = NULL, ...)
object |
A supported angular model object. |
data |
Optional data frame to bind to the diagnostic columns. |
... |
Reserved for future methods. |
A tibble with .observed, .fitted, .resid, .abs_resid,
.index and .model_class.
Other circular model helpers:
augment_circular(),
circular_model_diagnostics()
fit <- structure( list(y = c(0, 0.2, 0.4), mui = c(0.05, 0.15, 0.5)), class = "angular" ) circular_residuals(fit)fit <- structure( list(y = c(0, 0.2, 0.4), mui = c(0.05, 0.15, 0.5)), class = "angular" ) circular_residuals(fit)
Uses the common descriptive statistic sqrt(-2 * log(Rbar)).
circular_sd(x, axial = FALSE, na.rm = TRUE)circular_sd(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
Circular standard deviation in radians.
Other circular summaries:
circular_mean_ci(),
circular_summary(),
circular_variance(),
estimate_kappa(),
mean_direction(),
mean_resultant_length(),
resultant_length()
Computes grouped circular summaries for an angle column. Existing dplyr
groups are respected, and additional grouping variables can be supplied in
....
circular_summary(data, angle, ..., axial = FALSE, na.rm = TRUE)circular_summary(data, angle, ..., axial = FALSE, na.rm = TRUE)
data |
A data frame or tibble. |
angle |
Angle column, in radians. |
... |
Optional grouping variables. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
A tibble with columns n, mean, R, Rbar, variance, sd and
kappa. The returned object also has class ggcircular_summary.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_variance(),
estimate_kappa(),
mean_direction(),
mean_resultant_length(),
resultant_length()
tibble::tibble(group = c("a", "a", "b"), theta = c(0, pi / 2, pi)) |> dplyr::group_by(group) |> circular_summary(theta)tibble::tibble(group = c("a", "a", "b"), theta = c(0, pi / 2, pi)) |> dplyr::group_by(group) |> circular_summary(theta)
Compute circular topography data
circular_topography_data(theta, x, conditional = TRUE, ...)circular_topography_data(theta, x, conditional = TRUE, ...)
theta |
Angles in radians. |
x |
Real-valued response. |
conditional |
If |
... |
Additional arguments passed to |
A data frame with columns theta, x and density.
Other cylindrical dependence helpers:
estimate_cyl_density(),
phase_loom_data(),
stat_orbit_data()
dat <- simulate_cylindrical(n = 80, seed = 1) circular_topography_data(dat$theta, dat$x, n_theta = 24, n_x = 30)dat <- simulate_cylindrical(n = 80, seed = 1) circular_topography_data(dat$theta, dat$x, n_theta = 24, n_x = 30)
Circular variance
circular_variance(x, axial = FALSE, na.rm = TRUE)circular_variance(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
The circular variance 1 - Rbar.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_summary(),
estimate_kappa(),
mean_direction(),
mean_resultant_length(),
resultant_length()
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.
compass_to_rad(x)compass_to_rad(x)
x |
Character vector of compass labels. |
Numeric vector of bearing angles in radians.
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()
compass_to_rad(c("N", "E", "S", "W"))compass_to_rad(c("N", "E", "S", "W"))
Compute bearings
compute_bearing(x, y, angle_convention = c("mathematical", "bearing"))compute_bearing(x, y, angle_convention = c("mathematical", "bearing"))
x, y
|
Numeric coordinate vectors. |
angle_convention |
Angle convention. |
Numeric vector of bearings in radians. The first value is NA.
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
compute_step_length(x, y)compute_step_length(x, y)
x, y
|
Numeric coordinate vectors. |
Numeric vector of Euclidean step lengths. The first value is NA.
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
compute_turn_angle(bearing, period = 2 * pi)compute_turn_angle(bearing, period = 2 * pi)
bearing |
Numeric vector of bearings in radians. |
period |
Angular period. |
Numeric vector of signed turn angles. The first value is NA.
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()
Computes a simple squared variation summary for a matrix of conditional densities across conditioning-grid rows.
conditional_variation_index(density_matrix)conditional_variation_index(density_matrix)
density_matrix |
Matrix with rows representing conditioning-grid values and columns representing conditional density values. |
A non-negative numeric scalar.
Other directional dependence indicators:
alignment_index(),
local_circ_moment()
dat <- simulate_toroidal(n = 80, seed = 1) est <- estimate_toroidal_density(dat$theta, dat$phi, n_theta = 12, n_phi = 12, conditional = TRUE) conditional_variation_index(est$density)dat <- simulate_toroidal(n = 80, seed = 1) est <- estimate_toroidal_density(dat$theta, dat$phi, n_theta = 12, n_phi = 12, conditional = TRUE) conditional_variation_index(est$density)
Convenience wrapper around ggplot2::coord_polar() with arguments expressed
in circular-data language.
coord_circular( zero = c("east", "north", "west", "south"), direction = c("counterclockwise", "clockwise"), start = NULL, clip = "on" )coord_circular( zero = c("east", "north", "west", "south"), direction = c("counterclockwise", "clockwise"), start = NULL, clip = "on" )
zero |
Direction corresponding to angle zero. |
direction |
Direction in which angles increase. |
start |
Optional start offset in radians. If supplied, it overrides
|
clip |
Should drawing be clipped to the plot panel? |
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.
A ggplot2 coordinate object.
Other circular scales:
scale_x_circular_radians()
coord_circular() coord_circular(zero = "north", direction = "clockwise")coord_circular() coord_circular(zero = "north", direction = "clockwise")
Convert degrees to radians
deg_to_rad(x)deg_to_rad(x)
x |
Numeric vector in degrees. |
Numeric vector in radians.
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()
Build diagnostic atlas data
diagnostic_atlas_data( space = c("cylindrical", "toroidal"), n = 600, seed = 20260609 )diagnostic_atlas_data( space = c("cylindrical", "toroidal"), n = 600, seed = 20260609 )
space |
Either |
n |
Number of observations per scenario. |
seed |
Optional random seed. |
A data frame with diagnostic scenarios and plotting columns. The
returned object has class diagnostic_atlas_data.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_classical_comparison(),
plot_diagnostic_atlas(),
simulate_cyl_diagnostic(),
simulate_tor_diagnostic()
diagnostic_atlas_data("cylindrical", n = 20, seed = 1)diagnostic_atlas_data("cylindrical", n = 20, seed = 1)
List built-in directional diagnostic scenarios
diagnostic_scenarios()diagnostic_scenarios()
A data frame describing the built-in diagnostic scenarios.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_atlas_data(),
plot_classical_comparison(),
plot_diagnostic_atlas(),
simulate_cyl_diagnostic(),
simulate_tor_diagnostic()
diagnostic_scenarios()diagnostic_scenarios()
Estimates a joint or conditional kernel density for circular-linear data on
S1 x R. The circular component uses von Mises weights and the linear
component uses a Gaussian kernel.
estimate_cyl_density( theta, x, n_theta = 181, n_x = 200, kappa = 20, h = NULL, x_grid = NULL, conditional = TRUE )estimate_cyl_density( theta, x, n_theta = 181, n_x = 200, kappa = 20, h = NULL, x_grid = NULL, conditional = TRUE )
theta |
Angles in radians. |
x |
Real-valued response. |
n_theta |
Number of angular grid points. |
n_x |
Number of linear grid points. |
kappa |
Circular concentration for the conditioning kernel. |
h |
Linear bandwidth. If |
x_grid |
Optional grid for the linear response. |
conditional |
If |
A list with grids, a density matrix, a long data frame and smoothing metadata.
Other cylindrical dependence helpers:
circular_topography_data(),
phase_loom_data(),
stat_orbit_data()
dat <- simulate_cylindrical(n = 80, seed = 1) est <- estimate_cyl_density(dat$theta, dat$x, n_theta = 24, n_x = 30) str(est$data)dat <- simulate_cylindrical(n = 80, seed = 1) est <- estimate_cyl_density(dat$theta, dat$x, n_theta = 24, n_x = 30) str(est$data)
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.
estimate_kappa(x, axial = FALSE, na.rm = TRUE)estimate_kappa(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
Estimated concentration parameter kappa.
Fisher, N. I. (1993). Statistical Analysis of Circular Data. Cambridge University Press.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_summary(),
circular_variance(),
mean_direction(),
mean_resultant_length(),
resultant_length()
Estimates a joint or conditional kernel density for circular-circular data on
S1 x S1. Both components use von Mises weights.
estimate_toroidal_density( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, conditional = FALSE )estimate_toroidal_density( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, conditional = FALSE )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
conditional |
If |
A list with grids, a density matrix, a long data frame and smoothing metadata.
Other toroidal dependence helpers:
toroidal_flow_data(),
toroidal_ridge_data(),
toroidal_topography_data()
dat <- simulate_toroidal(n = 80, seed = 1) est <- estimate_toroidal_density(dat$theta, dat$phi, n_theta = 24, n_phi = 24) str(est$data)dat <- simulate_toroidal(n = 80, seed = 1) est <- estimate_toroidal_density(dat$theta, dat$phi, n_theta = 24, n_phi = 24) str(est$data)
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.
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 )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 )
x |
Numeric vector of angles in radians. |
k |
Number of mixture components. |
weights |
Optional non-negative observation weights. |
axial |
Should data be treated as axial, modulo |
init |
Initialization method, either |
nstart |
Number of EM starts. The fit with the largest log-likelihood is retained. |
init_params |
Optional list or data frame with initial |
kappa_max |
Maximum fitted concentration. This caps nearly degenerate components. |
min_component_weight |
Minimum relative component weight before a component is reinitialized. |
max_iter |
Maximum number of EM iterations. |
tol |
Convergence tolerance on the log-likelihood. |
na.rm |
Should missing values be removed? |
seed |
Optional random seed used for initialization. |
An object of class ggcircular_vonmises_mixture.
Other circular distributions:
stat_vonmises(),
stat_vonmises_fit(),
stat_vonmises_mixture()
fit <- fit_vonmises_mixture(wind_directions$direction, k = 2) tidy_circular(fit)fit <- fit_vonmises_mixture(wind_directions$direction, k = 2) tidy_circular(fit)
Draws a circular density estimate as a line. This is a convenience wrapper
around stat_circular_density().
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 )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 )
mapping, data, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
stat |
Statistical transformation, usually |
... |
Additional arguments passed to the layer. |
method |
Density method. Currently |
bw |
Optional circular bandwidth. It is interpreted as |
adjust |
Multiplicative adjustment applied to |
n |
Number of grid points. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer.
Other circular density layers:
stat_circular_density()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_circular_density()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_circular_density()
Convenience layers for plotting angular observations at a fixed radius.
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 )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 )
mapping, data, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to |
radius |
Radius at which points or rugs are drawn. |
na.rm |
Should missing values be silently removed? |
rug_length |
Radial length of rug marks. |
A ggplot2 layer.
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()
Draws angular intervals as arcs at a fixed radius. Intervals crossing zero are split into two path segments.
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 )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 )
mapping, data, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the path geometry. |
radius |
Default radius used when no |
n |
Number of points used to discretize each interval. |
na.rm |
Should missing interval endpoints be silently removed? |
A ggplot2 layer.
tibble::tibble(lower = 5.5, upper = 0.5) |> ggplot2::ggplot(ggplot2::aes(xmin = lower, xmax = upper)) + geom_confidence_arc()tibble::tibble(lower = 5.5, upper = 0.5) |> ggplot2::ggplot(ggplot2::aes(xmin = lower, xmax = upper)) + geom_confidence_arc()
Draws directional arrows from Cartesian coordinates and an angle.
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 )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 )
mapping, data, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to |
length |
Default arrow length when no |
arrow_length |
Grid unit controlling the arrow head length. |
angle_convention |
Angle convention. |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer.
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()
ggplot2::ggplot(animal_steps, ggplot2::aes(x = x, y = y, angle = bearing)) + geom_direction_arrow()ggplot2::ggplot(animal_steps, ggplot2::aes(x = x, y = y, angle = bearing)) + geom_direction_arrow()
Draws a radial segment at the circular mean direction. The segment length can be fixed or proportional to the mean resultant length.
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 )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 )
mapping, data, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
stat |
Statistical transformation, usually |
... |
Additional arguments passed to the layer. |
length |
Should the displayed segment length be proportional to the mean
resultant length ( |
radius |
Optional maximum displayed radius. |
conf.int |
Should approximate confidence limits be computed? |
level |
Confidence level used when |
axial |
Should the data be treated as axial, modulo |
arrow |
Should a small arrow head be drawn? |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer.
Other mean direction layers:
stat_mean_direction()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(bins = 16) + geom_mean_direction()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(bins = 16) + geom_mean_direction()
Adds mass-flow curves for circular-linear data. Use this layer with
ggplot2::ggplot(data, ggplot2::aes(x = theta, y = response)).
geom_phase_loom( mapping = NULL, data = NULL, position = "identity", n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional"), curvature = 0.24, ..., show.legend = NA, inherit.aes = TRUE )geom_phase_loom( mapping = NULL, data = NULL, position = "identity", n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional"), curvature = 0.24, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_sectors |
Number of angular sectors. |
n_x_bins |
Number of bins for the linear response. |
min_mass |
Minimum mass to draw. |
max_flows |
Maximum number of flows to draw. Use |
mass_type |
Either |
curvature |
Curvature passed to |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other cylindrical dependence layers:
stat_circular_topography(),
stat_statistical_orbit(),
stat_statistical_orbit_ribbon()
dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + geom_phase_loom(n_sectors = 12, n_x_bins = 8, min_mass = 0)dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + geom_phase_loom(n_sectors = 12, n_x_bins = 8, min_mass = 0)
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().
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 )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 )
mapping, data, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
stat |
Statistical transformation, usually |
... |
Additional arguments passed to the layer. |
bins |
Number of bins over the circular period. |
binwidth |
Optional bin width in radians. If supplied, |
boundary |
Lower boundary for the first bin. |
closed |
Included for API compatibility. Values on the upper period boundary are wrapped into the first bin. |
area |
If |
normalize |
Which scale should be used for the computed radial |
axial |
Should angles be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer.
Other rose diagram layers:
stat_rose()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(bins = 16) + coord_circular()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(bins = 16) + coord_circular()
Adds rectangular flow curves from theta sectors to phi sectors. Use with
aes(x = theta, y = phi).
geom_toroidal_flow( mapping = NULL, data = NULL, position = "identity", n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional"), curvature = 0.28, ..., show.legend = NA, inherit.aes = TRUE )geom_toroidal_flow( mapping = NULL, data = NULL, position = "identity", n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional"), curvature = 0.28, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_sectors |
Number of angular sectors for both variables. |
min_mass |
Minimum mass to draw. |
mass_type |
Either |
curvature |
Curvature passed to |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other toroidal dependence layers:
stat_toroidal_ridge(),
stat_toroidal_topography()
dat <- simulate_toroidal(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + geom_toroidal_flow(n_sectors = 12, min_mass = 0)dat <- simulate_toroidal(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + geom_toroidal_flow(n_sectors = 12, min_mass = 0)
Convert hours to radians
hour_to_rad(x)hour_to_rad(x)
x |
Numeric vector in hours on a 24-hour clock. |
Numeric vector in radians.
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()
A reproducible simulated dataset of hourly activity converted to circular angles.
hourly_activityhourly_activity
A tibble with 240 rows and 5 variables:
Individual identifier.
Hour of day.
Hour converted to radians.
Activity level.
Group label.
Simulated for package examples.
Test whether an object can represent angles
is_angle(x)is_angle(x)
x |
Object to test. |
TRUE when x is numeric and contains only finite values or NA.
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()
Computes a kernel-weighted local circular moment of phi conditional on
theta.
local_circ_moment(theta, phi, grid = NULL, kappa = 20)local_circ_moment(theta, phi, grid = NULL, kappa = 20)
theta |
Conditioning angles in radians. |
phi |
Target angles in radians. |
grid |
Optional angular grid. If |
kappa |
Circular concentration for local weighting. |
A data frame with local real and imaginary components, mean
direction mu, and local concentration rho.
Other directional dependence indicators:
alignment_index(),
conditional_variation_index()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) local_circ_moment(dat$theta, dat$phi, grid = seq(0, 2 * pi, length.out = 12))dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) local_circ_moment(dat$theta, dat$phi, grid = seq(0, 2 * pi, length.out = 12))
Computes a kernel-weighted marginal support score along the conditioning angle. Low relative support marks angular regions where conditional displays should be interpreted cautiously.
marginal_support_data( theta, grid = NULL, n_theta = 181, kappa = 20, relative_threshold = 0.15 )marginal_support_data( theta, grid = NULL, n_theta = 181, kappa = 20, relative_threshold = 0.15 )
theta |
Conditioning angles in radians. |
grid |
Optional angular grid in radians. |
n_theta |
Number of grid points used when |
kappa |
Circular concentration for local kernel weights. |
relative_threshold |
Relative support threshold used to flag low-support
regions. With other ingredients fixed, the local standard error is
approximately inflated by |
A data frame with grid values, support, relative support and flags.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
plot_marginal_support(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_cylindrical(n = 60, seed = 1) marginal_support_data(dat$theta, n_theta = 12)dat <- simulate_cylindrical(n = 60, seed = 1) marginal_support_data(dat$theta, n_theta = 12)
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.
mean_direction(x, axial = FALSE, na.rm = TRUE)mean_direction(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
A single angle in radians, or NA_real_ when the mean is undefined.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_summary(),
circular_variance(),
estimate_kappa(),
mean_resultant_length(),
resultant_length()
mean_direction(c(0, pi / 4, pi / 2))mean_direction(c(0, pi / 4, pi / 2))
Mean resultant length
mean_resultant_length(x, axial = FALSE, na.rm = TRUE)mean_resultant_length(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
The mean resultant length Rbar, between 0 and 1 when defined.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_summary(),
circular_variance(),
estimate_kappa(),
mean_direction(),
resultant_length()
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.
mutate_directional_features( data, x, y, id = NULL, time = NULL, angle_convention = c("mathematical", "bearing") )mutate_directional_features( data, x, y, id = NULL, time = NULL, angle_convention = c("mathematical", "bearing") )
data |
A data frame. |
x, y
|
Coordinate columns. |
id |
Optional individual identifier column. |
time |
Optional time column used for sorting within individual. |
angle_convention |
Angle convention passed to |
A tibble with added step_length, bearing and turn_angle.
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()
tibble::tibble(id = 1, time = 1:3, x = 0:2, y = 0) |> mutate_directional_features(x = x, y = y, id = id, time = time)tibble::tibble(id = 1, time = 1:3, x = 0:2, y = 0) |> mutate_directional_features(x = x, y = y, id = id, time = time)
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.
normalize_angle(x, period = 2 * pi, origin = 0)normalize_angle(x, period = 2 * pi, origin = 0)
x |
Numeric vector of angles. |
period |
Positive numeric period. Use |
origin |
Lower bound of the target interval. |
A numeric vector with the same length as x.
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()
normalize_angle(c(-pi, 0, 3 * pi))normalize_angle(c(-pi, 0, 3 * pi))
Discretizes circular-linear observations into angular sectors and linear bins and returns binned mass flows for phase loom displays.
phase_loom_data( theta, x, n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional") )phase_loom_data( theta, x, n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional") )
theta |
Angles in radians. |
x |
Real-valued response. |
n_sectors |
Number of angular sectors. |
n_x_bins |
Number of linear bins. |
min_mass |
Minimum mass to retain. |
max_flows |
Maximum number of flows to retain. Use |
mass_type |
Either |
A data frame with sector identifiers, endpoints and mass values.
Other cylindrical dependence helpers:
circular_topography_data(),
estimate_cyl_density(),
stat_orbit_data()
dat <- simulate_cylindrical(n = 80, seed = 1) phase_loom_data(dat$theta, dat$x, n_sectors = 12, n_x_bins = 8)dat <- simulate_cylindrical(n = 80, seed = 1) phase_loom_data(dat$theta, dat$x, n_sectors = 12, n_x_bins = 8)
Plot circular topography
plot_circular_topography( theta, x, conditional = TRUE, ..., palette = topography_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )plot_circular_topography( theta, x, conditional = TRUE, ..., palette = topography_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )
theta |
Angles in radians. |
x |
Real-valued response. |
conditional |
If |
... |
Additional arguments passed to |
palette |
Colour palette for density. |
base_size |
Base font size. |
legend_position |
Legend position. |
show_legend |
If |
A ggplot object.
Other cylindrical dependence plots:
plot_circular_topography_3d(),
plot_phase_loom(),
plot_stat_orbit()
dat <- simulate_cylindrical(n = 80, seed = 1) plot_circular_topography(dat$theta, dat$x, n_theta = 24, n_x = 30)dat <- simulate_cylindrical(n = 80, seed = 1) plot_circular_topography(dat$theta, dat$x, n_theta = 24, n_x = 30)
Displays a circular-linear conditional density on a cylinder. The function is
experimental and is intended as a geometric companion to
plot_circular_topography(), not as a replacement for the 2D display.
plot_circular_topography_3d(theta, x, radius = 1, conditional = TRUE, ...)plot_circular_topography_3d(theta, x, radius = 1, conditional = TRUE, ...)
theta |
Angles in radians. |
x |
Real-valued response. |
radius |
Radius of the cylinder. |
conditional |
If |
... |
Additional arguments passed to |
A plotly htmlwidget.
Other cylindrical dependence plots:
plot_circular_topography(),
plot_phase_loom(),
plot_stat_orbit()
dat <- simulate_cylindrical(n = 120, seed = 1) plot_circular_topography_3d(dat$theta, dat$x, n_theta = 32, n_x = 40)dat <- simulate_cylindrical(n = 120, seed = 1) plot_circular_topography_3d(dat$theta, dat$x, n_theta = 32, n_x = 40)
Plot a classical unfolded comparison
plot_classical_comparison(data, space = c("cylindrical", "toroidal"))plot_classical_comparison(data, space = c("cylindrical", "toroidal"))
data |
Data frame containing |
space |
Either |
A ggplot object.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_diagnostic_atlas(),
simulate_cyl_diagnostic(),
simulate_tor_diagnostic()
dat <- simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1) plot_classical_comparison(dat, "cylindrical")dat <- simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1) plot_classical_comparison(dat, "cylindrical")
Plot a diagnostic atlas
plot_diagnostic_atlas( space = c("cylindrical", "toroidal"), n = 600, seed = 20260609 )plot_diagnostic_atlas( space = c("cylindrical", "toroidal"), n = 600, seed = 20260609 )
space |
Either |
n |
Number of observations per scenario. |
seed |
Optional random seed. |
A ggplot object.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_classical_comparison(),
simulate_cyl_diagnostic(),
simulate_tor_diagnostic()
plot_diagnostic_atlas("toroidal", n = 20, seed = 1)plot_diagnostic_atlas("toroidal", n = 20, seed = 1)
Plot angular marginal support
plot_marginal_support( theta, grid = NULL, n_theta = 181, kappa = 20, relative_threshold = 0.15, base_size = 11 )plot_marginal_support( theta, grid = NULL, n_theta = 181, kappa = 20, relative_threshold = 0.15, base_size = 11 )
theta |
Conditioning angles in radians. |
grid |
Optional angular grid in radians. |
n_theta |
Number of grid points used when |
kappa |
Circular concentration for local kernel weights. |
relative_threshold |
Relative support threshold used to flag low-support regions. |
base_size |
Base font size. |
A ggplot object.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
sensitivity_bandwidth_grid(),
simulate_independence_lineup()
dat <- simulate_cylindrical(n = 60, seed = 1) plot_marginal_support(dat$theta, n_theta = 12)dat <- simulate_cylindrical(n = 60, seed = 1) plot_marginal_support(dat$theta, n_theta = 12)
Plot a phase loom
plot_phase_loom( theta, x, n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional"), palette = flow_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )plot_phase_loom( theta, x, n_sectors = 48, n_x_bins = 24, min_mass = 0.002, max_flows = 180, mass_type = c("joint", "conditional"), palette = flow_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )
theta |
Angles in radians. |
x |
Real-valued response. |
n_sectors |
Number of angular sectors. |
n_x_bins |
Number of linear bins. |
min_mass |
Minimum mass to retain. |
max_flows |
Maximum number of flows to retain. Use |
mass_type |
Either |
palette |
Colour palette for response levels. |
base_size |
Base font size. |
legend_position |
Legend position. |
show_legend |
If |
A ggplot object.
Other cylindrical dependence plots:
plot_circular_topography(),
plot_circular_topography_3d(),
plot_stat_orbit()
dat <- simulate_cylindrical(n = 80, seed = 1) plot_phase_loom(dat$theta, dat$x, n_sectors = 12, n_x_bins = 8)dat <- simulate_cylindrical(n = 80, seed = 1) plot_phase_loom(dat$theta, dat$x, n_sectors = 12, n_x_bins = 8)
Plot a statistical orbit
plot_stat_orbit(theta, x, n_theta = 181, kappa = 20, base_size = 12)plot_stat_orbit(theta, x, n_theta = 181, kappa = 20, base_size = 12)
theta |
Angles in radians. |
x |
Real-valued response. |
n_theta |
Number of angular grid points. |
kappa |
Circular concentration for local weighting. |
base_size |
Base font size. |
A ggplot object.
Other cylindrical dependence plots:
plot_circular_topography(),
plot_circular_topography_3d(),
plot_phase_loom()
dat <- simulate_cylindrical(n = 80, seed = 1) plot_stat_orbit(dat$theta, dat$x, n_theta = 24)dat <- simulate_cylindrical(n = 80, seed = 1) plot_stat_orbit(dat$theta, dat$x, n_theta = 24)
Convenience function for visualizing angles by observed or inferred states.
plot_state_angles( data, angle, state, type = c("rose", "density", "mean"), bins = 24, axial = FALSE )plot_state_angles( data, angle, state, type = c("rose", "density", "mean"), bins = 24, axial = FALSE )
data |
A data frame. |
angle |
Angle column. |
state |
State or group column. |
type |
Plot type. |
bins |
Number of bins for rose diagrams. |
axial |
Should data be treated as axial, modulo |
A ggplot object.
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()
Plot toroidal flow
plot_toroidal_flow( theta, phi, n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional"), palette = flow_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )plot_toroidal_flow( theta, phi, n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional"), palette = flow_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_sectors |
Number of sectors for both angles. |
min_mass |
Minimum mass to retain. |
mass_type |
Either |
palette |
Colour palette for theta sectors. |
base_size |
Base font size. |
legend_position |
Legend position. |
show_legend |
If |
A ggplot object.
Other toroidal dependence plots:
plot_toroidal_ridge(),
plot_toroidal_topography(),
plot_toroidal_topography_3d()
dat <- simulate_toroidal(n = 80, seed = 1) plot_toroidal_flow(dat$theta, dat$phi, n_sectors = 12)dat <- simulate_toroidal(n = 80, seed = 1) plot_toroidal_flow(dat$theta, dat$phi, n_sectors = 12)
Plot a conditional toroidal ridge
plot_toroidal_ridge( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01, density_palette = c("#f6f7f9", "#d7dce1", "#aab4bf", "#6d7f91", "#33485c"), rho_palette = ridge_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )plot_toroidal_ridge( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01, density_palette = c("#f6f7f9", "#d7dce1", "#aab4bf", "#6d7f91", "#33485c"), rho_palette = ridge_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
tie_tolerance |
Relative tolerance used to flag near-tied distinct local modes without changing the selected ridge. |
density_palette |
Colour palette for the density background. |
rho_palette |
Colour palette for local concentration. |
base_size |
Base font size. |
legend_position |
Legend position. |
show_legend |
If |
A ggplot object.
Other toroidal dependence plots:
plot_toroidal_flow(),
plot_toroidal_topography(),
plot_toroidal_topography_3d()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) plot_toroidal_ridge(dat$theta, dat$phi, n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) plot_toroidal_ridge(dat$theta, dat$phi, n_theta = 24, n_phi = 24)
Plot toroidal topography
plot_toroidal_topography( theta, phi, conditional = FALSE, ..., palette = topography_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )plot_toroidal_topography( theta, phi, conditional = FALSE, ..., palette = topography_palette(), base_size = 12, legend_position = "right", show_legend = TRUE )
theta |
First angle in radians. |
phi |
Second angle in radians. |
conditional |
If |
... |
Additional arguments passed to |
palette |
Colour palette for density. |
base_size |
Base font size. |
legend_position |
Legend position. |
show_legend |
If |
A ggplot object.
Other toroidal dependence plots:
plot_toroidal_flow(),
plot_toroidal_ridge(),
plot_toroidal_topography_3d()
dat <- simulate_toroidal(n = 80, seed = 1) plot_toroidal_topography(dat$theta, dat$phi, n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, seed = 1) plot_toroidal_topography(dat$theta, dat$phi, n_theta = 24, n_phi = 24)
Displays a circular-circular density on a torus. Colour represents the
estimated density and, by default, a small radial displacement also highlights
high-density regions. The function is experimental and is intended as a
geometric companion to plot_toroidal_topography().
plot_toroidal_topography_3d( theta, phi, major_radius = 1, minor_radius = 0.35, density_scale = 0.15, conditional = TRUE, ... )plot_toroidal_topography_3d( theta, phi, major_radius = 1, minor_radius = 0.35, density_scale = 0.15, conditional = TRUE, ... )
theta |
First angle in radians. |
phi |
Second angle in radians. |
major_radius |
Major torus radius. |
minor_radius |
Minor torus radius. |
density_scale |
Non-negative radial displacement applied after scaling
density to |
conditional |
If |
... |
Additional arguments passed to |
A plotly htmlwidget.
Other toroidal dependence plots:
plot_toroidal_flow(),
plot_toroidal_ridge(),
plot_toroidal_topography()
dat <- simulate_toroidal(n = 120, seed = 1) plot_toroidal_topography_3d(dat$theta, dat$phi, n_theta = 32, n_phi = 32)dat <- simulate_toroidal(n = 120, seed = 1) plot_toroidal_topography_3d(dat$theta, dat$phi, n_theta = 32, n_phi = 32)
Converts angles to the nearest label among labels. Angles are interpreted
as bearings by default: zero is north and angles increase clockwise.
rad_to_compass(x, labels = c("N", "NE", "E", "SE", "S", "SW", "W", "NW"))rad_to_compass(x, labels = c("N", "NE", "E", "SE", "S", "SW", "W", "NW"))
x |
Numeric vector of angles in radians. |
labels |
Character vector of equally spaced labels. |
Character vector of labels.
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()
rad_to_compass(c(0, pi / 2, pi))rad_to_compass(c(0, pi / 2, pi))
Convert radians to degrees
rad_to_deg(x)rad_to_deg(x)
x |
Numeric vector in radians. |
Numeric vector in degrees.
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
rad_to_hour(x)rad_to_hour(x)
x |
Numeric vector in radians. |
Numeric vector in hours on a 24-hour clock.
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()
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.
rayleigh_test(x, axial = FALSE, na.rm = TRUE)rayleigh_test(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
An object of class htest.
Other circular tests:
stat_circular_test(),
watson_williams_test()
Resultant length
resultant_length(x, axial = FALSE, na.rm = TRUE)resultant_length(x, axial = FALSE, na.rm = TRUE)
x |
Numeric vector of angles in radians. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be removed? |
The sample resultant length R.
Other circular summaries:
circular_mean_ci(),
circular_sd(),
circular_summary(),
circular_variance(),
estimate_kappa(),
mean_direction(),
mean_resultant_length()
These scales label angular x axes in radians, degrees, hours or compass directions.
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), ... )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), ... )
breaks |
Break positions in radians. |
labels |
Break labels. |
limits |
Scale limits in radians. |
... |
Additional arguments passed to |
A ggplot2 scale.
Other circular scales:
coord_circular()
scale_x_circular_radians()scale_x_circular_radians()
Ranks candidate smoothing parameters by K-fold conditional log-likelihood.
select_cyl_smoothing( theta, x, kappa_values = c(6, 8, 12, 16, 24, 36), h_values = NULL, n_folds = 5, seed = NULL )select_cyl_smoothing( theta, x, kappa_values = c(6, 8, 12, 16, 24, 36), h_values = NULL, n_folds = 5, seed = NULL )
theta |
Conditioning angles in radians. |
x |
Linear response. |
kappa_values |
Candidate circular concentration values. |
h_values |
Candidate linear bandwidth values. If |
n_folds |
Number of cross-validation folds. |
seed |
Optional random seed for fold assignment. |
A data frame ranked by decreasing mean held-out log score. The
returned object has class directional_smoothing_selection.
Other directional smoothing helpers:
select_toroidal_smoothing()
dat <- simulate_cylindrical(n = 80, seed = 1) select_cyl_smoothing( dat$theta, dat$x, kappa_values = c(8, 12), h_values = c(0.3, 0.5), n_folds = 2, seed = 1 )dat <- simulate_cylindrical(n = 80, seed = 1) select_cyl_smoothing( dat$theta, dat$x, kappa_values = c(8, 12), h_values = c(0.3, 0.5), n_folds = 2, seed = 1 )
Ranks candidate smoothing parameters by K-fold conditional log-likelihood for
f(phi | theta).
select_toroidal_smoothing( theta, phi, kappa_theta_values = c(6, 8, 12, 16, 24, 36), kappa_phi_values = kappa_theta_values, n_folds = 5, seed = NULL )select_toroidal_smoothing( theta, phi, kappa_theta_values = c(6, 8, 12, 16, 24, 36), kappa_phi_values = kappa_theta_values, n_folds = 5, seed = NULL )
theta |
Conditioning angles in radians. |
phi |
Response angles in radians. |
kappa_theta_values |
Candidate concentrations for the conditioning angle. |
kappa_phi_values |
Candidate concentrations for the response angle. |
n_folds |
Number of cross-validation folds. |
seed |
Optional random seed for fold assignment. |
A data frame ranked by decreasing mean held-out log score. The
returned object has class directional_smoothing_selection.
Other directional smoothing helpers:
select_cyl_smoothing()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) select_toroidal_smoothing( dat$theta, dat$phi, kappa_theta_values = c(8, 12), kappa_phi_values = c(8, 12), n_folds = 2, seed = 1 )dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) select_toroidal_smoothing( dat$theta, dat$phi, kappa_theta_values = c(8, 12), kappa_phi_values = c(8, 12), n_folds = 2, seed = 1 )
Evaluate sensitivity to smoothing concentration
sensitivity_bandwidth_grid( theta, target, space = c("cylindrical", "toroidal"), kappa_values = c(8, 12, 20, 32) )sensitivity_bandwidth_grid( theta, target, space = c("cylindrical", "toroidal"), kappa_values = c(8, 12, 20, 32) )
theta |
Conditioning angle in radians. |
target |
Real-valued response or second angle. |
space |
Either |
kappa_values |
Numeric vector of candidate concentrations. |
A data frame of compact sensitivity summaries.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
plot_marginal_support(),
simulate_independence_lineup()
dat <- simulate_cylindrical(n = 60, seed = 1) sensitivity_bandwidth_grid(dat$theta, dat$x, space = "cylindrical", kappa_values = c(8, 12))dat <- simulate_cylindrical(n = 60, seed = 1) sensitivity_bandwidth_grid(dat$theta, dat$x, space = "cylindrical", kappa_values = c(8, 12))
Simulate diagnostic circular-linear data
simulate_cyl_diagnostic( n = 800, scenario = c("independent", "smooth", "heteroscedastic", "multimodal", "seam"), seed = NULL )simulate_cyl_diagnostic( n = 800, scenario = c("independent", "smooth", "heteroscedastic", "multimodal", "seam"), seed = NULL )
n |
Number of observations. |
scenario |
Diagnostic scenario. |
seed |
Optional random seed. |
A data frame with theta, x and scenario.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_classical_comparison(),
plot_diagnostic_atlas(),
simulate_tor_diagnostic()
simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1)simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1)
Simulates examples on the cylinder, where theta is an angle in radians and
x is a real-valued response.
simulate_cylindrical( n = 500, scenario = c("nonlinear", "independent", "unimodal", "heteroscedastic", "multimodal"), seed = NULL )simulate_cylindrical( n = 500, scenario = c("nonlinear", "independent", "unimodal", "heteroscedastic", "multimodal"), seed = NULL )
n |
Number of observations. |
scenario |
Dependence pattern to simulate. |
seed |
Optional random seed. |
A data frame with columns theta, x and scenario.
Other directional simulation helpers:
simulate_toroidal()
simulate_cylindrical(n = 30, scenario = "nonlinear", seed = 1)simulate_cylindrical(n = 30, scenario = "nonlinear", seed = 1)
Simulate a visual-inference lineup under independence
simulate_independence_lineup( data, plot_fun = NULL, m = 20, seed = NULL, space = c("cylindrical", "toroidal"), ... )simulate_independence_lineup( data, plot_fun = NULL, m = 20, seed = NULL, space = c("cylindrical", "toroidal"), ... )
data |
Data frame containing |
plot_fun |
Optional function taking one data frame and returning a ggplot object. |
m |
Number of lineup panels. |
seed |
Optional random seed. |
space |
Either |
... |
Passed to the default plot function when |
A list with plots, true position and metadata. The returned object has
class directional_lineup.
Other directional uncertainty helpers:
autoplot.bootstrap_stat_orbit(),
autoplot.bootstrap_toroidal_ridge(),
bootstrap_stat_orbit(),
bootstrap_toroidal_ridge(),
marginal_support_data(),
plot_marginal_support(),
sensitivity_bandwidth_grid()
dat <- simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1) lineup <- simulate_independence_lineup( dat, plot_fun = function(d) ggplot2::ggplot(d, ggplot2::aes(theta, x)) + ggplot2::geom_point(), m = 4, seed = 1, space = "cylindrical" ) length(lineup$plots)dat <- simulate_cyl_diagnostic(n = 40, scenario = "smooth", seed = 1) lineup <- simulate_independence_lineup( dat, plot_fun = function(d) ggplot2::ggplot(d, ggplot2::aes(theta, x)) + ggplot2::geom_point(), m = 4, seed = 1, space = "cylindrical" ) length(lineup$plots)
Simulate diagnostic circular-circular data
simulate_tor_diagnostic( n = 900, scenario = c("independent_concentrated", "diagonal", "doubling", "bifurcation", "uniform_marginal_dependence"), seed = NULL )simulate_tor_diagnostic( n = 900, scenario = c("independent_concentrated", "diagonal", "doubling", "bifurcation", "uniform_marginal_dependence"), seed = NULL )
n |
Number of observations. |
scenario |
Diagnostic scenario. |
seed |
Optional random seed. |
A data frame with theta, phi and scenario.
Other directional diagnostics:
autoplot.diagnostic_atlas_data(),
diagnostic_atlas_data(),
diagnostic_scenarios(),
plot_classical_comparison(),
plot_diagnostic_atlas(),
simulate_cyl_diagnostic()
simulate_tor_diagnostic(n = 40, scenario = "diagonal", seed = 1)simulate_tor_diagnostic(n = 40, scenario = "diagonal", seed = 1)
Simulates examples on the torus, where both theta and phi are angles in
radians.
simulate_toroidal( n = 500, scenario = c("nonlinear", "diagonal", "anti_diagonal", "multimodal", "independent"), seed = NULL )simulate_toroidal( n = 500, scenario = c("nonlinear", "diagonal", "anti_diagonal", "multimodal", "independent"), seed = NULL )
n |
Number of observations. |
scenario |
Dependence pattern to simulate. |
seed |
Optional random seed. |
A data frame with columns theta, phi and scenario.
Other directional simulation helpers:
simulate_cylindrical()
simulate_toroidal(n = 30, scenario = "diagonal", seed = 1)simulate_toroidal(n = 30, scenario = "diagonal", seed = 1)
Computes the mean direction vector and mean spherical coordinates.
spherical_summary( theta, phi, weights = NULL, convention = c("azimuth_colatitude", "azimuth_elevation"), na.rm = TRUE )spherical_summary( theta, phi, weights = NULL, convention = c("azimuth_colatitude", "azimuth_elevation"), na.rm = TRUE )
theta |
Azimuth angle in radians. |
phi |
Colatitude or elevation angle in radians. |
weights |
Optional non-negative weights. |
convention |
Interpretation of |
na.rm |
Should missing values be removed? |
A tibble with sample size, mean spherical coordinates and resultant length.
Other spherical helpers:
cartesian_to_spherical(),
spherical_to_cartesian()
Convert spherical coordinates to Cartesian coordinates
spherical_to_cartesian( theta, phi, radius = 1, convention = c("azimuth_colatitude", "azimuth_elevation") )spherical_to_cartesian( theta, phi, radius = 1, convention = c("azimuth_colatitude", "azimuth_elevation") )
theta |
Azimuth angle in radians. |
phi |
Colatitude or elevation angle in radians. |
radius |
Radius. |
convention |
Interpretation of |
A tibble with x, y and z.
Other spherical helpers:
cartesian_to_spherical(),
spherical_summary()
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.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
method |
Density method. Currently |
bw |
Optional circular bandwidth. It is interpreted as |
adjust |
Multiplicative adjustment applied to |
n |
Number of grid points. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer. Computed variables are x, density, scaled,
count, n, bw and kappa.
Other circular density layers:
geom_circular_density()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_circular_density()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_circular_density()
Adds a text annotation with the p-value from a Rayleigh or Watson-Williams test.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the text geom. |
test |
Test to compute. |
x, y
|
Text position. |
digits |
Number of digits used for p-value formatting. |
na.rm |
Should missing values be removed? |
A ggplot2 layer.
Other circular tests:
rayleigh_test(),
watson_williams_test()
Estimates a circular-linear density and returns grid values for topographic
displays. Use with aes(x = theta, y = response).
stat_circular_topography( mapping = NULL, data = NULL, geom = "tile", position = "identity", n_theta = 181, n_x = 200, kappa = 20, h = NULL, conditional = TRUE, ..., show.legend = NA, inherit.aes = TRUE )stat_circular_topography( mapping = NULL, data = NULL, geom = "tile", position = "identity", n_theta = 181, n_x = 200, kappa = 20, h = NULL, conditional = TRUE, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_theta |
Number of angular grid points. |
n_x |
Number of linear grid points. |
kappa |
Circular concentration for the conditioning kernel. |
h |
Linear bandwidth. If |
conditional |
If |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other cylindrical dependence layers:
geom_phase_loom(),
stat_statistical_orbit(),
stat_statistical_orbit_ribbon()
dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_circular_topography(n_theta = 24, n_x = 30)dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_circular_topography(n_theta = 24, n_x = 30)
Computes one mean direction per group, with resultant length and an optional approximate confidence arc.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
length |
Should the displayed segment length be proportional to the mean
resultant length ( |
radius |
Optional maximum displayed radius. |
conf.int |
Should approximate confidence limits be computed? |
level |
Confidence level used when |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer. Computed variables include x, xend, y, yend,
mean, R, Rbar, n, kappa, ci_low and ci_high.
Other mean direction layers:
geom_mean_direction()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_mean_direction()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_mean_direction()
Computes local conditional means, local standard deviations and local skewness over an angular grid.
stat_orbit_data(theta, x, n_theta = 181, kappa = 20)stat_orbit_data(theta, x, n_theta = 181, kappa = 20)
theta |
Angles in radians. |
x |
Real-valued response. |
n_theta |
Number of angular grid points. |
kappa |
Circular concentration for local weighting. |
A data frame with theta, mu, lower, upper and skew.
Other cylindrical dependence helpers:
circular_topography_data(),
estimate_cyl_density(),
phase_loom_data()
dat <- simulate_cylindrical(n = 80, seed = 1) stat_orbit_data(dat$theta, dat$x, n_theta = 24)dat <- simulate_cylindrical(n = 80, seed = 1) stat_orbit_data(dat$theta, dat$x, n_theta = 24)
Bins circular angles over a full period and returns counts, densities and proportions for rose diagrams.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
bins |
Number of bins over the circular period. |
binwidth |
Optional bin width in radians. If supplied, |
boundary |
Lower boundary for the first bin. |
closed |
Included for API compatibility. Values on the upper period boundary are wrapped into the first bin. |
area |
If |
normalize |
Which scale should be used for the computed radial |
axial |
Should angles be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer. Computed variables are xmin, xmax, x, count,
density, proportion, width and y.
Other rose diagram layers:
geom_rose()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_rose(bins = 16) + coord_circular()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + stat_rose(bins = 16) + coord_circular()
Add a statistical orbit line
stat_statistical_orbit( mapping = NULL, data = NULL, geom = "line", position = "identity", n_theta = 181, kappa = 20, ..., show.legend = NA, inherit.aes = TRUE )stat_statistical_orbit( mapping = NULL, data = NULL, geom = "line", position = "identity", n_theta = 181, kappa = 20, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_theta |
Number of angular grid points. |
kappa |
Circular concentration for local weighting. |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other cylindrical dependence layers:
geom_phase_loom(),
stat_circular_topography(),
stat_statistical_orbit_ribbon()
dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_statistical_orbit(n_theta = 24)dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_statistical_orbit(n_theta = 24)
Add a statistical orbit ribbon
stat_statistical_orbit_ribbon( mapping = NULL, data = NULL, geom = "ribbon", position = "identity", n_theta = 181, kappa = 20, ..., show.legend = NA, inherit.aes = TRUE )stat_statistical_orbit_ribbon( mapping = NULL, data = NULL, geom = "ribbon", position = "identity", n_theta = 181, kappa = 20, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_theta |
Number of angular grid points. |
kappa |
Circular concentration for local weighting. |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other cylindrical dependence layers:
geom_phase_loom(),
stat_circular_topography(),
stat_statistical_orbit()
dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_statistical_orbit_ribbon(n_theta = 24, alpha = 0.2) + stat_statistical_orbit(n_theta = 24)dat <- simulate_cylindrical(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = x)) + stat_statistical_orbit_ribbon(n_theta = 24, alpha = 0.2) + stat_statistical_orbit(n_theta = 24)
Adds a conditional modal ridge for circular-circular data. Use with
aes(x = theta, y = phi).
stat_toroidal_ridge( mapping = NULL, data = NULL, geom = "path", position = "identity", n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01, signed = TRUE, ..., show.legend = NA, inherit.aes = TRUE )stat_toroidal_ridge( mapping = NULL, data = NULL, geom = "path", position = "identity", n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01, signed = TRUE, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
tie_tolerance |
Relative tolerance used to flag near-tied distinct local modes without changing the selected ridge. |
signed |
If |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other toroidal dependence layers:
geom_toroidal_flow(),
stat_toroidal_topography()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + stat_toroidal_ridge(n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + stat_toroidal_ridge(n_theta = 24, n_phi = 24)
Estimates a circular-circular density and returns grid values for topographic
displays. Use with aes(x = theta, y = phi).
stat_toroidal_topography( mapping = NULL, data = NULL, geom = "tile", position = "identity", n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, conditional = FALSE, signed = TRUE, ..., show.legend = NA, inherit.aes = TRUE )stat_toroidal_topography( mapping = NULL, data = NULL, geom = "tile", position = "identity", n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, conditional = FALSE, signed = TRUE, ..., show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
conditional |
If |
signed |
If |
... |
Additional arguments passed to the geom. |
A ggplot2 layer.
Other toroidal dependence layers:
geom_toroidal_flow(),
stat_toroidal_ridge()
dat <- simulate_toroidal(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + stat_toroidal_topography(n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, seed = 1) ggplot2::ggplot(dat, ggplot2::aes(x = theta, y = phi)) + stat_toroidal_topography(n_theta = 24, n_phi = 24)
Adds a theoretical von Mises density to a circular plot.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
mu |
Mean direction in radians. |
kappa |
Non-negative concentration parameter. |
n |
Number of grid points. |
axial |
Should the density be drawn over an axial period of |
na.rm |
Included for ggplot2 layer compatibility. |
sigma |
Standard deviation of the wrapped normal distribution. |
terms |
Number of wrapping terms on each side of the origin. |
A ggplot2 layer.
Other circular distributions:
fit_vonmises_mixture(),
stat_vonmises_fit(),
stat_vonmises_mixture()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) + stat_vonmises(mu = pi / 2, kappa = 3)ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) + stat_vonmises(mu = pi / 2, kappa = 3)
Estimates mu with mean_direction() and kappa with estimate_kappa(),
then draws the fitted von Mises density.
stat_vonmises_fit( mapping = NULL, data = NULL, geom = "line", position = "identity", ..., n = 512, axial = FALSE, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )stat_vonmises_fit( mapping = NULL, data = NULL, geom = "line", position = "identity", ..., n = 512, axial = FALSE, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
n |
Number of grid points. |
axial |
Should the data be treated as axial, modulo |
na.rm |
Should missing values be silently removed? |
A ggplot2 layer.
Other circular distributions:
fit_vonmises_mixture(),
stat_vonmises(),
stat_vonmises_mixture()
ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) + stat_vonmises_fit()ggplot2::ggplot(wind_directions, ggplot2::aes(x = direction)) + geom_rose(ggplot2::aes(y = ggplot2::after_stat(density))) + stat_vonmises_fit()
Fits or draws a mixture of von Mises densities.
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 )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 )
mapping, data, geom, position, show.legend, inherit.aes
|
Standard ggplot2 layer arguments. |
... |
Additional arguments passed to the layer. |
fit |
Optional |
k |
Number of components when fitting inside the statistic. |
nstart |
Number of EM starts when fitting inside the statistic. |
seed |
Optional random seed when fitting inside the statistic. |
kappa_max |
Maximum fitted concentration when fitting inside the statistic. |
n |
Number of grid points. |
axial |
Should data be treated as axial, modulo |
na.rm |
Should missing values be removed before fitting? |
A ggplot2 layer.
Other circular distributions:
fit_vonmises_mixture(),
stat_vonmises(),
stat_vonmises_fit()
Summarize circular posterior draws
summarise_circular_draws( draws, variables = NULL, level = 0.95, axial = FALSE, ... )summarise_circular_draws( draws, variables = NULL, level = 0.95, axial = FALSE, ... )
draws |
Circular draws from |
variables |
Optional variables to summarize. |
level |
Credible interval level. |
axial |
Should draws be treated as axial, modulo |
... |
Additional arguments passed to |
A tibble with posterior circular summaries.
Other posterior helpers:
as_circular_draws(),
autoplot_circular_draws()
Lightweight themes for circular plots. They keep a restrained grid and avoid imposing a strong visual identity.
theme_circular(base_size = 12, base_family = "") theme_rose(base_size = 12, base_family = "") theme_compass(base_size = 12, base_family = "")theme_circular(base_size = 12, base_family = "") theme_rose(base_size = 12, base_family = "") theme_compass(base_size = 12, base_family = "")
base_size |
Base font size. |
base_family |
Base font family. |
A ggplot2 theme.
theme_circular()theme_circular()
Discretizes two angular variables into sectors and estimates joint or conditional mass flows between sectors.
toroidal_flow_data( theta, phi, n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional") )toroidal_flow_data( theta, phi, n_sectors = 32, min_mass = 0.002, mass_type = c("joint", "conditional") )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_sectors |
Number of sectors for both angles. |
min_mass |
Minimum mass to retain. |
mass_type |
Either |
A data frame with sector identifiers, endpoints and mass values.
Other toroidal dependence helpers:
estimate_toroidal_density(),
toroidal_ridge_data(),
toroidal_topography_data()
dat <- simulate_toroidal(n = 80, seed = 1) toroidal_flow_data(dat$theta, dat$phi, n_sectors = 12)dat <- simulate_toroidal(n = 80, seed = 1) toroidal_flow_data(dat$theta, dat$phi, n_sectors = 12)
Extracts the modal phi value along a grid of conditioning angles and
attaches the local circular concentration.
toroidal_ridge_data( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01 )toroidal_ridge_data( theta, phi, n_theta = 181, n_phi = 181, kappa_theta = 20, kappa_phi = 20, tie_tolerance = 0.01 )
theta |
First angle in radians. |
phi |
Second angle in radians. |
n_theta |
Number of theta grid points. |
n_phi |
Number of phi grid points. |
kappa_theta |
Kernel concentration for |
kappa_phi |
Kernel concentration for |
tie_tolerance |
Relative tolerance used to flag two distinct local maxima as near-tied. The selected ridge remains the first exact grid maximum for backward compatibility. |
A data frame with columns theta, phi, rho, ridge_group,
n_local_modes, secondary_mode_ratio and ridge_ambiguous.
Other toroidal dependence helpers:
estimate_toroidal_density(),
toroidal_flow_data(),
toroidal_topography_data()
dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) toroidal_ridge_data(dat$theta, dat$phi, n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, scenario = "diagonal", seed = 1) toroidal_ridge_data(dat$theta, dat$phi, n_theta = 24, n_phi = 24)
Compute toroidal topography data
toroidal_topography_data(theta, phi, conditional = FALSE, ...)toroidal_topography_data(theta, phi, conditional = FALSE, ...)
theta |
First angle in radians. |
phi |
Second angle in radians. |
conditional |
If |
... |
Additional arguments passed to |
A data frame with columns theta, phi and density.
Other toroidal dependence helpers:
estimate_toroidal_density(),
toroidal_flow_data(),
toroidal_ridge_data()
dat <- simulate_toroidal(n = 80, seed = 1) toroidal_topography_data(dat$theta, dat$phi, n_theta = 24, n_phi = 24)dat <- simulate_toroidal(n = 80, seed = 1) toroidal_topography_data(dat$theta, dat$phi, n_theta = 24, n_phi = 24)
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.
watson_williams_test(x, group, ...)watson_williams_test(x, group, ...)
x |
Numeric vector of angles in radians. |
group |
Grouping variable. |
... |
Additional arguments passed to |
An object returned by circular::watson.williams.test().
Other circular tests:
rayleigh_test(),
stat_circular_test()
A reproducible simulated dataset of wind directions with station, speed and season variables. Angles are stored in radians.
wind_directionswind_directions
A tibble with 500 rows and 4 variables:
Station identifier.
Wind direction in radians.
Wind speed in arbitrary units.
Season label.
Simulated for package examples.