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
1 2  maxent.test(model, obs, sub.c, nperm = 99, quick = TRUE,
alpha = 0.05, plot = TRUE)

Arguments
model 
list returned by 
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 
alpha 
desired alphalevel for the test. Only relevant if 
plot 
if 
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 ruleofthumb 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 alphalevel 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 
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 
r2.q 
Pearson r^2 between observed and prior probabilities;
only returned when 
obs.stat 
observed statistic used for the permutation test; see Shipley (2010) 
nperm 
number of permutations; can be smaller than the specified 
pval 
Pvalue 
ci.pval 
approximate confidence intervals of the Pvalue 
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.
See Also
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 POSIXcompliant OS's (essentially anything but Windows).
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20  # 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) # communityaggregated 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)
