wallraff.test: Wallraff Test of Angular Distances
In circular: Circular Statistics

Description Usage Arguments Details Value Author(s) References See Also Examples

Performs the Wallraff test of angular distances or angular dispersion around the mean.

wallraff.test(x, ...)

## Default S3 method:
wallraff.test(x, group, ref=NULL, ...)

## S3 method for class 'list'
wallraff.test(x, ref=NULL, ...)

## S3 method for class 'formula'
wallraff.test(formula, data, ref=NULL, ...)

`x`	a vector of angles (coerced to class `circular`) or a list of such angles. When `x` is a list, its elements are taken as the samples to be compared.
`group`	a vector or factor object giving the group for the corresponding elements of `x`. Ignored if `x` is a list
`formula`	a formula of the form `lhs ~ rhs` where `lhs` is a vector of angles and `rhs` a vector or factor giving the corresponding groups.
`data`	an optional data.frame containing the variables in the formula `formula`.
`ref`	a vector of angles used as reference to compute the angular distances from, in each group. It should contain as many elements as there are groups, in the same order. If `x` is a list, the order is the order of the elements of the list. In the default or formula interfaces, if the grouping vector is a factor, the order is the order of its levels; if the grouping vector is not a factor, it is coerced as such but with levels in the order of their appearance in the original vector. In this case a warning is issued to make sure the order of `ref` is correct. If `ref` has less elements than the number of groups (typically one: a common reference for all groups), it is recycled to match the number of groups. If `ref` is `NULL` (the default), the mean angle of each group will be used as reference. In this situation, the Wallraff test becomes a comparison of angular dispersion around the mean.
`...`	further arguments passed to or from other methods.

The Wallraff test of angular distances between two or more groups is performed and the results are printed. The null hypothesis is that distances are equal across groups.

The test proceeds by computing the angular distances from a reference angle, in each group. The angular distance between two angles is the circular range and is computed with range.circular. Then the distances are compared with a usual rank sum test (Kruskal-Wallis, kruskal.test). When there are only two groups, the Wilcoxon-Mann-Whitney test could be used but wilcox.test without continuity correction for the p-value is equivalent to kruskal.test so only kruskal.test is used here.

The Wallraff test is most frequently used to compare angular dispersion around the mean, between samples. In this case, the reference angle is the mean angle of each sample. This is the default here, when no reference angles are provided.

All angles should be of class circular and will be coerced as such with the default parameters if they are not. An exception are the reference angles in ref. For ease of use, those can be only numeric and are then considered to be in the same angular reference as x.

A list with class "htest" containing the following components:

`statistic`	the chi-squared statistic from `kruskal.test`.
`parameter`	the degrees of freedom for the chi-squared statistic.
`p.value`	the p-value for the test.
`method`	a character string containing the name of the test.
`data.name`	a character string giving the name(s) of the data.

Jean-Olivier Irisson

Batschelet, E (1981). Circular Statistics in Biology. chap. 6.10, p. 124

Zar, J H (2010). Biostatistical analysis. sec. 27.7-8, p. 643

kruskal.test for the Kruskal-Wallis rank sum test used on the angular distances.

wilcox.test for the two samples alternative to the Kruskal-Wallis test.

# Homing of pigeons
# Example used in Batschelet (1981)
data <- list(
  control = circular(c(70, 80, 80, 85, 85, 90, 95, 95), 
        units="degrees", template="geographics"),
  experimental = circular(c(5, 5, 15, 55, 55, 65, 105, 120, 340), 
            units="degrees", template="geographics")
)

# compare the angular dispersion between the two groups
wallraff.test(data)

# compare the homing performance
# home azimuth is 40 degrees for both groups
wallraff.test(data, 
              ref = circular(c(40, 40), units="degrees",
                                 template="geographics")
             )
# we could have more simply used
wallraff.test(data, ref=40)
# because ref is automatically repeated and considered
# in the same circular reference as the data