R: Inferential Permutation Tests for Maximum Entropy Models
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 subsetB of the entire set of constraints C = {A U B} is irrelevant for predicting the probabilities.
A plot can be returned to facilitate interpretation.
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:
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.
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 Sciencein press.
Shipley, B. (2010) Inferential permutation tests for maximum entropy models in ecology. Ecologyin press.
See Also
maxent to run the maximum entropy model that is required by maxent.test.
# 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)
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(FD)
Loading required package: ade4
Loading required package: ape
Loading required package: geometry
Loading required package: magic
Loading required package: abind
Loading required package: vegan
Loading required package: permute
Loading required package: lattice
This is vegan 2.4-0
Attaching package: 'vegan'
The following object is masked from 'package:ade4':
cca
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/FD/maxent.test.Rd_%03d_medium.png", width=480, height=480)
> ### Name: maxent.test
> ### Title: Inferential Permutation Tests for Maximum Entropy Models
> ### Aliases: maxent.test
> ### Keywords: distribution math models
>
> ### ** 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:
> ##D # do the constraints give predictive ability?
> ##D maxent.test(pred.abun, obs = abun[1,], nperm = 49)
> ##D
> ##D # are height, LDMC, and leaf [N] important constraints?
> ##D maxent.test(pred.abun, obs = abun[1,], sub.c = c("height",
> ##D "LDMC", "leafN"), nperm = 49)
> ## End(Not run)
>
>
>
>
>
> dev.off()
null device
1
>