NEWS | R Documentation

## vegan News

### Changes in version 2.0.7

#### NEW FUNCTIONS

- `tabasco()` is a new function for graphical display of community data matrix. Technically it is an interface to R `heatmap`, but its use is closer to vegan function `vegemite`. The function can reorder the community data matrix similarly as `vegemite`, for instance, by ordination results. Unlike `heatmap`, it only displays dendrograms if supplied by the user, and it defaults to re-order the dendrograms by correspondence analysis. Species are ordered to match site ordering or like determined by the user.

#### BUG FIXES

- Function `fitspecaccum(..., model = "asymp")` fitted logistic model instead of asymptotic model (or the same as `model = "logis"`).

- `nestedtemp()` failed with very sparse data (fill < 0.38%).

#### NEW FEATURES

- The `plot` function for constrained ordination results (`cca`, `rda`, `capscale`) gained argument `axis.bp` (defaults `TRUE`) which can be used to suppress axis scale for biplot arrays.

- Number of iterations in nonmetric multidimensional scaling (NMDS) can be set with keyword `maxit` (defaults `200`) in `metaMDS`.

#### DEPRECATED

- The result objects of `cca`, `rda` and `capscale` will no longer have scores `u.eig`, `v.eig` and `wa.eig` in the future versions of vegan. This change does not influence normal usage, because vegan functions do not need these items. However, external scripts and packages may need changes in the future versions of vegan.

### Changes in version 2.0-6

#### BUG FIXES

- The species scores were scaled wrongly in `capscale()`. They were scaled correctly only when Euclidean distances were used, but usually `capscale()` is used with non-Euclidean distances. Most graphics will change and should be redone. The change of scaling mainly influences the spread of species scores with respect to the site scores.

- Function `clamtest()` failed to set the minimum abundance threshold in some cases. In addition, the output was wrong when some of the possible species groups were missing. Both problems were reported by Richard Telford (Bergen, Norway).

- Plotting an object fitted by `envfit()` would fail if `p.max` was used and there were unused levels for one or more factors. The unused levels could result from deletion of observations with missing values or simply as the result of supplying a subset of a larger data set to `envfit()`.

- `multipart()` printed wrong information about the analysis type (but did the analysis correctly). Reported by Valerie Coudrain.

- `oecosimu()` failed if its `nestedfun` returned a data frame. A more fundamental fix will be in vegan 2.2-0, where the structure of the `oecosimu()` result will change.

- The plot of two-dimensional `procrustes()` solutions often draw original axes in a wrong angle. The problem was reported by Elizabeth Ottesen (MIT).

- Function `treedive()` for functional or phylogenetic diversity did not correctly match the species names between the community data and species tree when the tree contained species that did not occur in the data. Related function `treedist()` for phylogenetic distances did not try to match the names at all.

#### NEW FEATURES

- The output of `capscale()` displays the value of the additive constant when argument `add = TRUE` was used.

- `fitted()` functions for `cca()`, `rda()` and `capscale()` can now return conditioned (partial) component of the response: Argument `model` gained a new alternative `model = "pCCA"`.

- `dispindmorisita()` output gained a new column for Chi-squared based probabilities that the null hypothesis (random distribution) is true.

- `metaMDS()` and `monoMDS()` have new default convergence criteria. Most importantly, scale factor of the gradient (`sfgrmin`) is stricter. The former limit was too slack with large data sets and iterations stopped early without getting close to the solution. In addition, `scores()` ignore now requests to dimensions beyond those calculated instead of failing, and `scores()` for `metaMDS()` results do not drop dimensions.

- `msoplot()` gained `legend` argument for positioning the legend.

- Nestedness function `nestednodf()` gained a `plot` method.

- `ordiR2step()` gained new argument `R2scope` (defaults `TRUE`) which can be used to turn off the criterion of stopping when the adjusted R-squared of the current model exceeds that of the scope. This option allows model building when the `scope` would be overdetermined (number of predictors higher than number of observations).

  `ordiR2step()` now handles partial redundancy analysis (pRDA).

- `orditorp()` gained argument `select` to select the rows or columns of the results to display.

- `protest()` prints the standardized residual statistic squared m12 in addition to the squared Procrustes correlation R-squared. Both were calculated, but only the latter was displayed.

  Permutation tests are much faster in `protest()`. Instead of calling repeatedly `procrustes()`, the goodness of fit statistic is evaluated within the function.

- `wcmdscale()` gained methods for `print`, `plot` etc. of the results. These methods are only used if the full `wcmdscale` result is returned with, e.g., argument `eig = TRUE`. The default is still to return only a matrix of scores similarly as the standard R function `cmdscale()`, and in that case the new methods are not used.

### Changes in version 2.0-5

#### BUG FIXES

- `anova(<cca_object>, ...)` failed with `by = "axis"` and `by = "term"`. The bug was reported by Dr Sven Neulinger (Christian Albrecht University, Kiel, Germany).

- `radlattice` did not honour argument `BIC = TRUE`, but always displayed AIC.

#### NEW FUNCTIONS

- Most vegan functions with permutation tests have now a `density` method that can be used to find empirical probability distributions of permutations. There is a new `plot` method for these functions that displays both the density and the observed statistic. The `density` function is available for `adonis`, `anosim`, `mantel`, `mantel.partial`, `mrpp`, `permutest.cca` and `procrustes`.

  Function `adonis` can return several statistics, and it has now a `densityplot` method (based on lattice).

  Function `oecosimu` already had `density` and `densityplot`, but they are now similar to other vegan methods, and also work with `adipart`, `hiersimu` and `multipart`.

- `radfit` functions got a `predict` method that also accepts arguments `newdata` and `total` for new ranks and site totals for prediction. The functions can also interpolate to non-integer “ranks”, and in some models also extrapolate.

#### NEW FEATURES

- Labels can now be set in the `plot` of `envfit` results. The labels must be given in the same order that the function uses internally, and new support function `labels` can be used to display the default labels in their correct order.

- Mantel tests (functions `mantel` and `mantel.partial`) gained argument `na.rm` which can be used to remove missing values. This options should be used with care: Permutation tests can be biased if the missing values were originally in matching or fixed positions.

- `radfit` results can be consistently accessed with the same methods whether they were a single model for a single site, all models for a single site or all models for all sites in the data. All functions now have methods `AIC`, `coef`, `deviance`, `logLik`, `fitted`, `predict` and `residuals`.

#### INSTALLATION AND BUILDING

- Building of vegan vignettes failed with the latest version of LaTeX (TeXLive 2012).

- R versions later than 2.15-1 (including development version) report warnings and errors when installing and checking vegan, and you must upgrade vegan to this version. The warnings concern functions `cIndexKM` and `betadisper`, and the error occurs in `betadisper`. These errors and warnings were triggered by internal changes in R.

### Changes in version 2.0-4

#### BUG FIXES

- `adipart` assumed constant gamma diversity in simulations when assessing the P-value. This could give biased results if the null model produces variable gamma diversities and option `weights = "prop"` is used. The default null model (`"r2dtable"`) and the default option (`weights = "unif"`) were analysed correctly.

- `anova(<prc-object>, by = "axis")` and other `by` cases failed due to ‘NAMESPACE’ issues.

- `clamtest` wrongly used frequencies instead of the counts when calculating sample coverage. No detectable differences were produced when rerunning examples from Chazdon et al. 2011 and vegan help page.

- `envfit` failed with unused factor levels.

- `predict` for `cca` results with `type = "response"` or `type = "working"` failed with `newdata` if the number of rows did not match with the original data. Now the `newdata` is ignored if it has a wrong number of rows. The number of rows must match because the results in `cca` must be weighted by original row totals. The problem did not concern `rda` or `capscale` results which do not need row weights. Reported by Glenn De'ath.

#### NEW FEATURES

- Functions for diversity partitioning (`adipart`, `hiersimu` and `multipart`) have now `formula` and `default` methods. The `formula` method is identical to the previous functions, but the `default` method can take two matrices as input.

  Functions `adipart` and `multipart` can be used for fast and easy overall partitioning to alpha, beta and gamma diversities by omitting the argument describing the hierarchy.

- The method in `betadisper` is biased with small sample sizes. The effects of the bias are strongest with unequal sample sizes. A bias adjusted version was developed by Adrian Stier and Ben Bolker, and can be invoked with argument `bias.adjust` (defaults to `FALSE`).

- `bioenv` accepts dissimilarities (or square matrices that can be interpreted as dissimilarities) as an alternative to community data. This allows using other dissimilarities than those available in `vegdist`.

- `plot` function for `envfit` results gained new argument `bg` that can be used to set background colour for plotted labels.

- `msoplot` is more configurable, and allows, for instance, setting y-axis limits.

- Hulls and ellipses are now filled using semitransparent colours in `ordihull` and `ordiellipse`, and the user can set the degree of transparency with a new argument `alpha`. The filled shapes are used when these functions are called with argument `draw = "polygon"`. Function `ordihull` puts labels (with argument `label = TRUE`) now in the real polygon centre.

- `ordiplot3d` returns function `envfit.convert` and the projected location of the `origin`. Together these can be used to add `envfit` results to existing `ordiplot3d` plots.

  Equal aspect ratio cannot be set exactly in `ordiplot3d` because underlying core routines do not allow this. Now `ordiplot3d` sets equal axis ranges, and the documents urge users to verify that the aspect ratio is reasonably equal and the graph looks like a cube. If the problems cannot be solved in the future, `ordiplot3d` may be removed from next releases of vegan.

- Function `ordipointlabel` gained argument to `select` only some of the items for plotting. The argument can be used only with one set of points.

### Changes in version 2.0-3

#### NEW FUNCTIONS

- Added new nestedness functions `nestedbetasor` and `nestedbetajac` that implement multiple-site dissimilarity indices and their decomposition into turnover and nestedness components following Baselga (Global Ecology and Biogeography 19, 134–143; 2010).

- Added function `rarecurve` to draw rarefaction curves for each row (sampling unit) of the input data, optionally with lines showing rarefied species richness with given sample size for each curve.

- Added function `simper` that implements “similarity percentages” of Clarke (Australian Journal of Ecology 18, 117–143; 1993). The method compares two or more groups and decomposes the average between-group Bray-Curtis dissimilarity index to contributions by individual species. The code was developed in GitHub by Eduard Szöcs (Uni Landau, Germany).

#### BUG FIXES

- `betadisper()` failed when the `groups` was a factor with empty levels.

- Some constrained ordination methods and their support functions are more robust in border cases (completely aliased effects, saturated models, user requests for non-existng scores etc). Concerns `capscale`, `ordistep`, `varpart`, `plot` function for constrained ordination, and `anova(<cca.object>, by = "margin")`.

- The `scores` function for `monoMDS` did not honour `choices` argument and hence dimensions could not be chosen in `plot`.

- The default `scores` method failed if the number of requested axes was higher than the ordination object had. This was reported as an error in `ordiplot` in R-sig-ecology mailing list.

#### NEW FEATURES

- `metaMDS` argument `noshare = 0` is now regarded as a numeric threshold that always triggers extended dissimilarities (`stepacross`), instead of being treated as synonymous with `noshare = FALSE` which always suppresses extended dissimilarities.

- Nestedness discrepancy index `nesteddisc` gained a new argument that allows user to set the number of iterations in optimizing the index.

- `oecosimu` displays the mean of simulations and describes alternative hypothesis more clearly in the printed output.

- Implemented adjusted R-squared for partial RDA. For partial model `rda(Y ~ X1 + Condition(X2))` this is the same as the component `[a] = X1|X2` in variance partition in `varpart` and describes the marginal (unique) effect of constraining term to adjusted R-squared.

- Added Cao dissimilarity (CYd) as a new dissimilarity method in `vegdist` following Cao et al., Water Envir Res 69, 95–106 (1997). The index should be good for data with high beta diversity and variable sampling intensity. Thanks to consultation to Yong Cao (Univ Illinois, USA).

### Changes in version 2.0-2

#### BUG FIXES

- Function `capscale` failed if constrained component had zero rank. This happened most likely in partial models when the conditions aliased constraints. The problem was observed in `anova(..., by ="margin")` which uses partial models to analyses the marginal effects, and was reported in an email message to R-News mailing list.

- `stressplot` and `goodness` sometimes failed when `metaMDS` was based on `isoMDS` (MASS package) because `metaMDSdist` did not use the same defaults for step-across (extended) dissimilarities as `metaMDS(..., engine = "isoMDS")`. The change of defaults can also influence triggering of step-across in `capscale(..., metaMDSdist = TRUE)`.

- `adonis` contained a minor bug resulting from incomplete implementation of a speed-up that did not affect the results. In fixing this bug, a further bug was identified in transposing the hat matrices. This second bug was only active following fixing of the first bug. In fixing both bugs, a speed-up in the internal f.test() function is fully realised. Reported by Nicholas Lewin-Koh.

#### NEW FEATURES

- `ordiarrows` and `ordisegments` gained argument `order.by` that gives a variable to sort points within `groups`. Earlier the points were assumed to be in order.

- Function `ordispider` invisibly returns the coordinates to which the points were connected. Typically these are class centroids of each point, but for constrained ordination with no `groups` they are the LC scores.

### Changes in version 2.0-1

#### NEW FUNCTIONS

- `clamtest`: new function to classify species as generalists and specialists in two distinct habitats (CLAM test of Chazdon et al., Ecology 92, 1332–1343; 2011). The test is based on multinomial distribution of individuals in two habitat types or sampling units, and it is applicable only to count data with no over-dispersion.

- `as.preston` gained `plot` and `lines` methods, and `as.fisher` gained `plot` method (which also can add items to existing plots). These are similar as `plot` and `lines` for `prestonfit` and `fisherfit`, but display only data without the fitted lines.

- `raupcrick`: new function to implement Raup-Crick dissimilarity as a probability of number of co-occurring species with occurrence probabilities proportional to species frequencies. Vegan has Raup-Crick index as a choice in `vegdist`, but that uses equal sampling probabilities for species and analytic equations. The new `raupcrick` function uses simulation with `oecosimu`. The function follows Chase et al. (2011) Ecosphere 2:art24 [doi:10.1890/ES10-00117.1], and was developed with the consultation of Brian Inouye.

#### BUG FIXES

- Function `meandist` could scramble items and give wrong results, especially when the `grouping` was numerical. The problem was reported by Dr Miguel Alvarez (Univ. Bonn).

- `metaMDS` did not reset `tries` when a new model was started with a `previous.best` solution from a different model.

- Function `permatswap` for community null models using quantitative swap never swapped items in a 2 by 2 submatrix if all cells were filled.

- The result from `permutest.cca` could not be `update`d because of a ‘NAMESPACE’ issue.

- R 2.14.0 changed so that it does not accept using `sd()` function for matrices (which was the behaviour at least since R 1.0-0), and several vegan functions were changed to adapt to this change (`rda`, `capscale`, `simulate` methods for `rda`, `cca` and `capscale`). The change in R 2.14.0 does not influence the results but you probably wish to upgrade vegan to avoid annoying warnings.

#### ANALYSES

- `nesteddisc` is slacker and hence faster when trying to optimize the statistic for tied column frequencies. Tracing showed that in most cases an improved ordering was found rather early in tries, and the results are equally good in most cases.

### Changes in version 2.0-0

#### GENERAL

- Peter Minchin joins the vegan team.

- vegan implements standard R ‘NAMESPACE’. In general, `S3` methods are not exported which means that you cannot directly use or see contents of functions like `cca.default`, `plot.cca` or `anova.ccabyterm`. To use these functions you should rely on R delegation and simply use `cca` and for its result objects use `plot` and `anova` without suffix `.cca`. To see the contents of the function you can use `:::`, such as `vegan:::cca.default`. This change may break packages, documents or scripts that rely on non-exported names.

- vegan depends on the permute package. This package provides powerful tools for restricted permutation schemes. All vegan permutation will gradually move to use permute, but currently only `betadisper` uses the new feature.

#### NEW FUNCTIONS

- `monoMDS`: a new function for non-metric multidimensional scaling (NMDS). This function replaces `MASS::isoMDS` as the default method in `metaMDS`. Major advantages of `monoMDS` are that it has ‘weak’ (‘primary’) tie treatment which means that it can split tied observed dissimilarities. ‘Weak’ tie treatment improves ordination of heterogeneous data sets, because maximum dissimilarities of 1 can be split. In addition to global NMDS, `monoMDS` can perform local and hybrid NMDS and metric MDS. It can also handle missing and zero dissimilarities. Moreover, `monoMDS` is faster than previous alternatives. The function uses `Fortran` code written by Peter Minchin.

- `MDSrotate` a new function to replace `metaMDSrotate`. This function can rotate both `metaMDS` and `monoMDS` results so that the first axis is parallel to an environmental vector.

- `eventstar` finds the minimum of the evenness profile on the Tsallis entropy, and uses this to find the corresponding values of diversity, evenness and numbers equivalent following Mendes et al. (Ecography 31, 450-456; 2008). The code was contributed by Eduardo Ribeira Cunha and Heloisa Beatriz Antoniazi Evangelista and adapted to vegan by Peter Solymos.

- `fitspecaccum` fits non-linear regression models to the species accumulation results from `specaccum`. The function can use new self-starting species accumulation models in vegan or other self-starting non-linear regression models in R. The function can fit Arrhenius, Gleason, Gitay, Lomolino (in vegan), asymptotic, Gompertz, Michaelis-Menten, logistic and Weibull (in base R) models. The function has `plot` and `predict` methods.

- Self-starting non-linear species accumulation models `SSarrhenius`, `SSgleason`, `SSgitay` and `SSlomolino`. These can be used with `fitspecaccum` or directly in non-linear regression with `nls`. These functions were implemented because they were found good for species-area models by Dengler (J. Biogeogr. 36, 728-744; 2009).

#### NEW FEATURES

- `adonis`, `anosim`, `meandist` and `mrpp` warn on negative dissimilarities, and `betadisper` refuses to analyse them. All these functions expect dissimilarities, and giving something else (like correlations) probably is a user error.

- `betadisper` uses restricted permutation of the permute package.

- `metaMDS` uses `monoMDS` as its default ordination engine. Function gains new argument `engine` that can be used to alternatively select `MASS::isoMDS`. The default is not to use `stepacross` with `monoMDS` because its ‘weak’ tie treatment can cope with tied maximum dissimilarities of one. However, `stepacross` is the default with `isoMDS` because it cannot handle adequately these tied maximum dissimilarities.

- `specaccum` gained `predict` method which uses either linear or spline interpolation for data between observed points. Extrapolation is possible with spline interpolation, but may make little sense.

- `specpool` can handle missing values or empty factor levels in the grouping factor `pool`. Now also checks that the length of the `pool` matches the number of observations.

#### DEPRECATED AND DEFUNCT

- `metaMDSrotate` was replaced with `MDSrotate` that can also handle the results of `monoMDS`.

- `permuted.index2` and other “new” permutation code was removed in favour of the permute package. This code was not intended for normal use, but packages depending on that code in vegan should instead depend on permute.

#### ANALYSES

- `treeheight` uses much snappier code. The results should be unchanged.