nestedRanksTest (version 0.2)

nestedRanksTest: Mann-Whitney-Wilcoxon ranks test when data are in groups.

Description

The statistic for the nested ranks test is a Z-score calculated by comparing ranks between treatment levels, with contributions of each group to the final Z-score weighted by group size. The p-value is determined by comparing the observed Z-score against a distribution of Z-scores calculated by bootstrapping ranks assuming no influence of treatment while respecting group sizes. When there is just one group, this test is essentially identical to a standard Mann-Whitney-Wilcoxon test. This test is intended to be a mixed-model extension of the wilcox.test, for which treatment is a fixed effect and group membership is a random effect.

Usage

"nestedRanksTest"(formula, data, groups = NULL, subset, ...)
"nestedRanksTest"(x, y, groups, n.iter = 10000, lightweight = FALSE, ...)

Arguments

formula

A formula of the form lhs ~ rhs or lhs ~ rhs | groups, where lhs is a numeric variable giving the data values, rhs is a variable obeying conditions for x, and groups is a variable obeying conditions for groups. If "| groups" is not included in the formula, group membership must be specified with the groups argument.

data

An optional matrix or data frame (or similar: see model.frame) containing the variables in the formula formula. By default the variables are taken from environment(formula).

groups

A (non-empty) vector specifying group membership for each y, coerced to a factor. There must be at least one y in each group for each treatment level.

subset

An optional vector specifying a subset of observations to be used.

...

Further arguments to be passed to or from methods.

x

A (non-empty) vector of treatments for each y, coerced to factor. Must contain exactly two levels.

y

A (non-empty) numeric vector of data values.

n.iter

Number of bootstrap iterations to perform. The value of the final iteration is provided by the observed Z-score. Using n.iter = 1 simply returns the observed Z-score.

lightweight

If TRUE, the vector of individual values of the null distribution is excluded from the return value of class 'htest_boot'. By default the null distribution is included. If n.iter is large, specifying TRUE for this option can save space, but note that calling plot on the return value will produce an error if so.

Value

A list with class 'htest_boot' based on class 'htest' containing the following components. Components marked with "*" are additions to 'htest'.

statistic

the value of the observed Z-score.

p.value

the p-value for the test.

alternative

a character string describing the alternative hypothesis.

method

a character string indicating the nested ranks test performed.

data.name

a character string giving the name(s) of the data.

bad.obs

the number of observations in the data excluded because of NA values.

null.values

quantiles of the null distribution used for calculating the p-value.

n.iter*

the number of bootstrap iterations used for generating the null distribution.

weights*

the weights for groups, calculated by nestedRanksTest_weights.

null.distribution*

null distribution of Z-scores, with statistic the last value.

The length of null.distribution equals n.iter. Note that null.distribution will not be present if the lightweight = TRUE option was given to nestedRanksTest.

References

Thompson, P. G., Smouse, P. E., Scofield, D. G. and Sork, V. L. (2014) What seeds tell us about birds: a multi-year analysis of acorn woodpecker foraging movements. Movement Ecology 2:12. http://www.movementecologyjournal.com/content/2/1/12

https://github.com/douglasgscofield/nestedRanksTest

See Also

wilcox.test, print.htest_boot, plot.htest_boot

Examples

require(graphics)

data(woodpecker_multiyear)

## S3 method for class 'formula'

## n.iter set to 1000 to shorten completion time

## group in formula
nestedRanksTest(Distance ~ Year | Granary, n.iter = 1000,
                data = woodpecker_multiyear,
                subset = Species == "agrifolia")
## group in 'groups='
nestedRanksTest(Distance ~ Year, groups = Granary, n.iter = 1000,
                data = woodpecker_multiyear,
                subset = Species == "lobata")

## Default S3 method

dat.a <- subset(woodpecker_multiyear, Species == "agrifolia")
## arguments in default order
nestedRanksTest(dat.a$Year, dat.a$Distance, dat.a$Granary, n.iter = 1000)
## named arguments used in 'formula' order
res <- with(subset(woodpecker_multiyear, Species == "lobata"),
           nestedRanksTest(y = Distance, x = Year, groups = Granary,
                           n.iter = 1000))
plot(res)