R: Display Compact Ordered Community Tables

vegemite {vegan} | R Documentation

## Display Compact Ordered Community Tables

### Description

Functions `vegemite` and `tabasco` display compact community tables. Function `vegemite` prints text tables where species are rows, and each site takes only one column without spaces. Function `tabasco` provides interface for `heatmap` for a colour `image` of the data. The community table can be ordered by explicit indexing, by environmental variables or results from an ordination or cluster analysis.

### Usage

    vegemite(x, use, scale, sp.ind, site.ind, zero=".", select ,...)
    tabasco(x, use, sp.ind = NULL, site.ind = NULL, select,
        Rowv = TRUE, Colv = TRUE, labRow = NULL, labCol = NULL,
        scale = c("none", "column", "row"), col = heat.colors(12), ...)
    coverscale(x, scale=c("Braun.Blanquet", "Domin", "Hult", "Hill", "fix","log"),
               maxabund)

### Arguments

`x` | Community data.
`use` | Either a vector, or an object from `cca`, `decorana` etc. or `hclust` or a `dendrogram` for ordering sites and species.
`sp.ind, site.ind` | Species and site indices. In `tabasco`, these can also be `hclust` tree, `agnes` clusterings or `dendrogram`s.
`zero` | Character used for zeros.
`select` | Select a subset of sites. This can be a logical vector (`TRUE` for selected sites), or a vector of indices of selected sites. The order of indices does not influence results, but you must specify `use` or `site.ind` to reorder sites.
`Rowv, Colv` | Re-order dendrograms for the rows (sites) or columns (species) of `x`. If the `Rowv = TRUE`, row dendrograms are ordered by the first axis of correspondence analysis, and when `Colv = TRUE` column dendrograms by the weighted average (`wascores`) of the row order. Alternatively, the arguments can be vectors that are used to reorder the dendrogram.
`labRow, labCol` | character vectors with row and column labels used in the `heatmap` instead of the default. NB., the input matrix is transposed so that row labels will be used for data columns.
`scale` | In `vegemite` and `coverscale`: cover scale used (can be abbreviated). In `tabasco`: scaling of colours in `heatmap`; if `"column"` or `"row"`, all columns or rows are scaled to equal maximum colour (NB., these refer to the transposed data of the `heatmap`).
`col` | A vector of colours used for above-zero abundance values.
`maxabund` | Maximum abundance used with `scale = "log"`. Data maximum in the `select`ed subset will be used if this is missing.
`...` | Arguments passed to `coverscale` (i.e., `maxabund`) in `vegemite` and to `heatmap` in `tabasco`.

### Details

The function `vegemite` prints a traditional community table. The display is transposed, so that species are in rows and sites in columns. The table is printed in compact form: only one character can be used for abundance, and there are no spaces between columns. Species with no occurrences are dropped from the table.

Function `tabasco` produces a similar table as `vegemite` using `heatmap`, where abundances are coded by colours. The function can also display dendrograms for sites (columns) or species if these are given as an argument (`use` for sites, `sp.ind` for species).

The parameter `use` will be used to re-order output. The `use` can be a vector or an object from `hclust` or `agnes`, a `dendrogram` or any ordination result recognized by `scores` (all ordination methods in vegan and some of those not in vegan). The `hclust`, `agnes` and `dendrogram` must be for sites. The dendrogram is displayed above the sites in `tabasco`, but is not shown in `vegemite`. No dendrogram for species is displayed, except when given in `sp.ind`.

If `use` is a vector, it is used for ordering sites. If `use` is an object from ordination, both sites and species are arranged by the first axis (provided that results are available both also for species). When `use` is an object from `hclust`, `agnes` or a `dendrogram`, the sites are ordered similarly as in the cluster dendrogram. Function `tabasco` re-orders the dendrogram if `Rowv = TRUE` or `Rowv` is a vector. Such re-ordering is not available for `vegemite`, but it can be done by hand using `reorder.dendrogram` or `reorder.hclust`. Please note that `dendrogram` and `hclust` reordering can differ: unweighted means of merged branches are used in `dendrogram`, but weighted means (= means of leaves of the cluster) are used in `reorder.hclust`. In all cases where species scores are missing, species are ordered by their weighted averages (`wascores`) on site order.

Species and sites can be ordered explicitly giving their indices or names in parameters `sp.ind` and `site.ind`. If these are given, they take precedence over `use`. A subset of sites can be displayed using argument `select`, but this cannot be used to order sites, but you still must give `use` or `site.ind`. However, `tabasco` makes two exceptions: `site.ind` and `select` cannot be used when `use` is a dendrogram (clustering result). In addition, the `sp.ind` can be an `hclust` tree, `agnes` clustering or a `dendrogram`, and in that case the dendrogram is plotted on the left side of the `heatmap`. Phylogenetic trees cannot be directly used, `as.hclust.phylo` (package ape) can transform these to `hclust` trees.

If `scale` is given, `vegemite` calls `coverscale` to transform percent cover scale or some other scales into traditional class scales used in vegetation science (`coverscale` can be called directly, too). Braun-Blanquet and Domin scales are actually not strict cover scales, and the limits used for codes `r` and `+` are arbitrary. Scale `Hill` may be inappropriately named, since Mark O. Hill probably never intended this as a cover scale. However, it is used as default 'cut levels' in his `TWINSPAN`, and surprisingly many users stick to this default, and this is a de facto standard in publications. All traditional scales assume that values are cover percentages with maximum 100. However, non-traditional alternative `log` can be used with any scale range. Its class limits are integer powers of 1/2 of the maximum (argument `maxabund`), with `+` used for non-zero entries less than 1/512 of the maximum (`log` stands alternatively for logarithmic or logical). Scale `fix` is intended for ‘fixing’ 10-point scales: it truncates scale values to integers, and replaces 10 with `X` and positive values below 1 with `+`.

### Value

The functions are used mainly to display a table, but they return (invisibly) a list with items:

`species` | Ordered species indices
`sites` | Ordered site indices

These items can be used as arguments `sp.ind` and `site.ind` to reproduce the table. In addition to the proper table, `vegemite` prints the numbers of species and sites and the name of the used cover scale at the end.

### Note

The name `vegemite` was chosen because the output is so compact, and the `tabasco` because it is just as compact, but uses heat colours.

### Author(s)

Jari Oksanen

### References

The cover scales are presented in many textbooks of vegetation science; I used:

Shimwell, D.W. (1971) The Description and Classification of Vegetation. Sidgwick & Jackson.

### See Also

`cut` and `approx` for making your own ‘cover scales’ for `vegemite`. Function `tabasco` is based on `heatmap` which in turn is based on `image`. Both functions order species with weighted averages using `wascores`.

### Examples

    data(varespec)
    ## Print only more common species
    freq <- apply(varespec > 0, 2, sum)
    vegemite(varespec, scale="Hult", sp.ind = freq > 10)
    ## Order by correspondence analysis, use Hill scaling and layout:
    dca <- decorana(varespec)
    vegemite(varespec, dca, "Hill", zero="-")
    ## Show one class from cluster analysis, but retain the ordering above
    clus <- hclust(vegdist(varespec))
    cl <- cutree(clus, 3)
    sel <- vegemite(varespec, use=dca, select = cl == 3, scale="Br")
    ## Re-create previous
    vegemite(varespec, sp=sel$sp, site=sel$site, scale="Hult")
    ## Re-order clusters by ordination
    clus <- as.dendrogram(clus)
    clus <- reorder(clus, scores(dca, choices=1, display="sites"), agglo.FUN = mean)
    vegemite(varespec, clus, scale = "Hult")

    ## Abundance values have such a wide range that they must be rescaled
    ## or all abundances will not be shown in tabasco
    tabasco(decostand(varespec, "log"), dca)

    ## Classification trees for species
    data(dune, dune.taxon)
    taxontree <- hclust(taxa2dist(dune.taxon))
    plotree <- hclust(vegdist(dune), "average")
    ## Automatic reordering of clusters
    tabasco(dune, plotree, sp.ind = taxontree)
    ## No reordering of taxonomy
    tabasco(dune, plotree, sp.ind = taxontree, Colv = FALSE)
    ## Species cluster: most dissimilarity indices do a bad job when
    ## comparing rare and common species, but Raup-Crick makes sense
    sptree <- hclust(vegdist(t(dune), "raup"), "average")
    tabasco(dune, plotree, sptree)

[Package vegan version 2.4-3 Index]