Skip to contents

Per-group tests of circular uniformity

Source: R/circular_statistics.R
test_uniformity.Rd

Tests whether each group's headings are uniformly distributed (i.e. no preferred direction), using any of four classical tests. The Rayleigh test ("rayleigh", default) returns an exact numeric p-value; the other three ("kuiper", "rao", "watson") use look-up tables, so by default the p_value column contains the tabled significance level rather than a continuous p-value. Set p_method = "monte_carlo" to obtain a continuous p-value for those three by simulation instead (usable with p_adjust).

Usage

test_uniformity(
  hd,
  group_col = NULL,
  angle_col = "heading",
  test = c("rayleigh", "vtest", "kuiper", "rao", "watson", "hermans_rasson", "pycke"),
  p_adjust = "none",
  axial = FALSE,
  n_sim = 9999L,
  mu = NULL,
  p_method = c("table", "monte_carlo")
)

Arguments

hd

Data frame with a heading column in radians.

group_col

Column to group by. NULL tests the whole data frame as one group.

angle_col

Heading column name. Default "heading".

test

One of "rayleigh" (default), "vtest", "kuiper", "rao", "watson", "hermans_rasson", or "pycke". "vtest" is the V-test: uniformity against a specified mean direction mu, considerably more powerful than the Rayleigh test when a bearing is expected a priori. The Hermans-Rasson and Pycke omnibus tests are far more powerful than Rayleigh against multimodal / non-symmetric alternatives; both obtain p_value by Monte-Carlo simulation.

p_adjust

Multiple-comparison correction method passed to p.adjust. Default "none". Applies only when group_col is supplied; a p_value_adj column is added to the result. Recommended: "BH" (Benjamini-Hochberg) when testing many conditions. Meaningful only for tests with continuous p-values: Rayleigh, the V-test, Hermans-Rasson, Pycke, and any test run with p_method = "monte_carlo".

axial

Logical. Treat the angles as axial (bidirectional, mod-pi) data: the uniformity test is run via the angle-doubling method (testing for an axis). Default `FALSE` (ordinary directional data).

n_sim

Number of Monte-Carlo replicates for the "hermans_rasson" and "pycke" p-values and for p_method = "monte_carlo". Default 9999. Set the RNG seed with set.seed for reproducible p-values.

mu

Numeric scalar, radians. The expected mean direction for the V-test (test = "vtest"); required for that test and ignored otherwise.

p_method

For "kuiper", "rao", and "watson" only: "table" (default) reports the tabled significance level from the circular package (or NA when the statistic falls outside the table); "monte_carlo" instead simulates n_sim uniform samples to obtain a continuous p-value. Ignored by the other tests.

Value

Tidy data frame with columns group_col (if supplied), statistic, p_value, n, test, and p_value_adj (when p_adjust != "none").

References

Landler, L., Ruxton, G.D. & Malkemper, E.P. (2019). The Hermans-Rasson test as a powerful alternative to the Rayleigh test for circular statistics in biology. BMC Ecology 19:30. doi:10.1186/s12898-019-0246-8 .

Pycke, J.-R. (2010). Some tests for uniformity of circular distributions powerful against multimodal alternatives. Canadian Journal of Statistics, 38(1), 80-96. doi:10.1002/cjs.10048 .

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc")
test_uniformity(hd, group_col = "arc", p_adjust = "BH")
#>   arc  statistic   p_value  n     test p_value_adj
#> 1  10 0.07055967 0.8675534 29 rayleigh   0.9199680
#> 2  15 0.24477975 0.1662359 30 rayleigh   0.6649438
#> 3  20 0.07326231 0.8672420 27 rayleigh   0.9199680
#> 4  30 0.12936762 0.5414943 37 rayleigh   0.9199680
#> 5  40 0.06536414 0.9199680 20 rayleigh   0.9199680
#> 6  50 0.15790182 0.5274183 26 rayleigh   0.9199680
#> 7   5 0.07181952 0.8542494 31 rayleigh   0.9199680
#> 8   0 0.23531457 0.1441169 35 rayleigh   0.6649438
# the target lies at 0 rad: test for orientation towards it
test_uniformity(hd, group_col = "arc", test = "vtest", mu = 0)
#>   arc    statistic    p_value  n  test
#> 1  10  0.013609964 0.45898856 29 vtest
#> 2  15  0.181361290 0.08049445 30 vtest
#> 3  20 -0.057634581 0.66303263 27 vtest
#> 4  30  0.120985069 0.14978536 37 vtest
#> 5  40 -0.059611637 0.64566419 20 vtest
#> 6  50 -0.002620525 0.50748393 26 vtest
#> 7   5 -0.053944829 0.66361241 31 vtest
#> 8   0 -0.234789199 0.97543503 35 vtest