# maxent.test: Inferential Permutation Tests for Maximum Entropy Models In FD: Measuring Functional Diversity (FD) from Multiple Traits, and Other Tools for Functional Ecology

 maxent.test R Documentation

## Inferential Permutation Tests for Maximum Entropy Models

### Description

`maxent.test` performs the permutation tests proposed by Shipley (2010) for maximum entropy models. Two different null hypotheses can be tested: 1) the information encoded in the entire set of constraints C is irrelevant for predicting the probabilities, and 2) the information encoded in subset B of the entire set of constraints C = {A U B} is irrelevant for predicting the probabilities. A plot can be returned to facilitate interpretation.

### Usage

```maxent.test(model, obs, sub.c, nperm = 99, quick = TRUE,
alpha = 0.05, plot = TRUE)
```

### Arguments

 `model` list returned by `maxent`. `obs` vector, matrix or data frame of observed probabilities of the states (columns). `sub.c` character or numeric vector specifying the subset of constraints B associated with null hypothesis 2. If missing, null hypothesis 1 is tested. `nperm` number of permutations for the test. `quick` if `TRUE`, the algorithm stops when `alpha` is outside the confidence interval of the P-value. Can be useful to speed up the routine. `alpha` desired alpha-level for the test. Only relevant if `quick` is `TRUE`. `plot` if `TRUE`, a plot is returned to facilitate interpretation.

### Details

`maxent.test` is a direct translation of the permutation tests described by Shipley (2010). Please refer to this article for details.

Using `quick = FALSE` will return the true null probability for a given `nperm`. However, if `nperm` is large (a rule-of-thumb is >=999 permutations for allowing inference at alpha = 0.05), this can take a very long time. Using `quick = TRUE` is a much faster and highly recommended alternative if one is only interested in accepting/rejecting the null hypothesis at the specified alpha-level given by argument `alpha`.

If `maxent` was run with multiple data sets (i.e. if `constr` had more than one row), then `maxent.test` performs the test for all sets simultaneously, following the ‘omnibus’ procedure described by Shipley (2010).

The following measure of fit between observed and predicted probabilities is returned:

fit = 1 - (sum(o_ij - p_ij)^2 / sum(o_ij - q_ij)^2)

where o_ij, o_ij, and q_ij are the observed, predicted and prior probabilities of state i from data set j, respectively, S is the number of states, and D the number of data sets (i.e. rows in `obs`). A value of 1 indicates perfect predictive capacity, while a value near zero indicates that the constraints provide no additional information beyond what is already contained in the prior q (Sonnier et al. 2009).

### Value

 `fit` measure of fit giving the predictive ability of the entire set of constraints C, beyond that already provided by the prior distribution. `fit.a` measure of fit giving the predictive ability of the subset of constraints A, beyond that already provided by the prior distribution; only returned if `sub.c` is specified `r2` Pearson r^2 between observed and predicted probabilities, using the entire set of constraints C `r2.a` Pearson r^2 between observed and predicted probabilities, using the subset of constraints A; only returned if `sub.c` is specified `r2.q` Pearson r^2 between observed and prior probabilities; only returned when `sub.c` is missing `obs.stat` observed statistic used for the permutation test; see Shipley (2010) `nperm` number of permutations; can be smaller than the specified `nperm` when `quick` is `TRUE` `pval` P-value `ci.pval` approximate confidence intervals of the P-value

### Warning

`maxent.test` is a computationally intensive function. The tests can take a very long time when `nperm` is large and `quick = FALSE`. It is highly recommended to use `quick = TRUE` because of this, unless you are interested in obtaining the true null probability.

### Author(s)

Etienne Laliberté etiennelaliberte@gmail.com

### References

Sonnier, G., Shipley, B., and M. L. Navas. 2009. Plant traits, species pools and the prediction of relative abundance in plant communities: a maximum entropy approach. Journal of Vegetation Science in press.

Shipley, B. (2010) Inferential permutation tests for maximum entropy models in ecology. Ecology in press.

`maxent` to run the maximum entropy model that is required by `maxent.test`.

Another faster version of `maxent.test` for multicore processors called `maxent.testMC` is available from Etienne Laliberté (etiennelaliberte@gmail.com). It's exactly the same as `maxent.test` but makes use of the multicore, doMC, and foreach packages. Because of this, `maxentMC` only works on POSIX-compliant OS's (essentially anything but Windows).

### Examples

```
# example with tussock dataset
traits <- tussock\$trait[, c(2:7, 11)] # use only continuous traits
traits <- na.omit(traits) # remove 2 species with NA's
abun <- tussock\$abun[, rownames(traits)] # abundance matrix
abun <- t(apply(abun, 1, function(x) x / sum(x) )) # relative abundances
agg <- functcomp(traits, abun) # community-aggregated traits
traits <- t(traits) # transpose matrix

# run maxent on site 1 (first row of abun), all species
pred.abun <- maxent(agg[1,], traits)

## Not run:
# do the constraints give predictive ability?
maxent.test(pred.abun, obs = abun[1,], nperm = 49)

# are height, LDMC, and leaf [N] important constraints?
maxent.test(pred.abun, obs = abun[1,], sub.c = c("height",
"LDMC", "leafN"), nperm = 49)

## End(Not run)
```

FD documentation built on May 2, 2022, 5:08 p.m.