vegsoup-package: An overview of the functions in this package

In vegsoup: Classes and Methods for Phytosociology

Description

The vegsoup package provides classes and methods to store and manipulate vegetation data (spatial and temporal explicit species co-occurrence data). In a certain respect it acts like a data base system. In fact, it's data model is very similar to the TurboVeg XML interchange format (see read.XML).

Vegetation data consists of at least of two related tables – a species or community matrix and a table of measurements taken at a site (sampling unit or relevée). At the very least a sampling date is available. If taxonomic identity or traits of species is a concern – and it should be – an additional table has to be tightly linked to the species matrix. Moreover, if spatial representation (e.g. plot coordinates and/or polygons) needs to be addressed another data layer has to be included. In the most complete case, up to five independent R objects have to be managed. Indexing and manipulation easily get cumbersome in this situation and the general workflow is hindered by a serious amount of code that ensures linking of objects, for example when random subsets needs be performed. Some R packages address these issues, namely the mefa and multitable packages (Note, package multitable was removed from the CRAN repository by mid 2016). They do so by extending the data.frame concept. None of these packages is spatially explicit nor do they handle cover scales commonly applied in vegetation ecology and present vegetation data bases.

Besides that, the package provides novel functionality, it also interfaces functions in other packages, most important are vegan, optpart and labdsv. These functions are extended or their arguments are simplified, due the inherent properties of Vegsoup objects. It was avoided to create new function names whenever another package already defines a suitable and meaningful name. Examples are decostand() and vegdist() which have extended meaning.

The vegsoup term follows the tradition of strange named functions in the vegan package – in particular vegemite, to give but one example, but also notice the tabasco() function.

This package should be mainly useful in the field of vegetation ecology, vegetation mapping and classification, and phytosociology in particular.

Summary

The package implements classes for vegetation data (see Vegsoup-class) and supports

• a solid class that is capable to store all relevant information

• species data to be structured in layers/strata

• several cover scales and conversions thereof

• taxonomic treatment (possibly including species traits) and amendment

• selection of standardizations

• ad-hoc creation of species and dissimilarity/distance matrices

• indexing, extract, replace and sample operations

• row and column aggregation

• merging of objects

• coerce methods

• partitioning (clustering) methods

• validation and refinement of partitions

• indicator species analysis

• several table methods

• specialized import routines

• output methods (Latex, text files, spatial data)

• spatial methods

• plotting and visualization methods

There are several side other packages depending on vegsoup, they support additional functionality, synoptic and evc are examples. Type vignette("vegsoup") for some usage example.

Creating Vegsoup objects and their base classes

Vegsoup objects or their foundation classes (e.g. Species, Sites, Taxonomy) can be created (1) from file connections including data base views, (2) from local R objects, (3) from community simulations, (4) from plain text files (OCR-scans) or (5) from other classes, with the following functions:

Vegsoup

main constructor function demanding full specification

plainsoup

supply just a community matrix and coverscale but no further data elements

instantsoup

shorthand function when data files conform to some specific conventions (format)

coenoflex

random community of specified size

species

constructor function for class Species

sites

constructor function for class Sites

taxonomy

constructor function for class Taxonomy

stackSpecies

reshape a vegetation table from wide to long format

stackSites

as above, but for sites data

reshapeSpecies

cast long to wide format with layer columns for class Species

stackCoordinates

collects spatial coordinates

read.verbatim

reads data from text arrays (OCR scans)

read.XML

reads data from XML files exported from the TurboVeg data base

Derived objects from base class Vegsoup

The vegsoup package uses S4 classes that relate to each other by direct inheritance. There are 2 derived classes from the base class Vegsoup. Objects of class VegsoupPartition directly extend the former class, that means all methods defined for class Vegsoup apply. As the name suggests, class VegsoupPartition represents an object that is partitioned (clusterend).

The following functions and methods are designed for class VegsoupPartition.

VegsoupPartition

constructor function

stable

classification stability

constancy

classification stability

Class VegsoupOptimstride also extends class Vegsoup. This class contains information on how a data set could be partitioned.

OptimStride

compute a series of clusterings by different methods and quantify their quality

stride

number of faithful species for each partition

threshold

threshold values set for the Fisher test

optimclass1,optimclass2

matrices with the counts of faithful species

peaks

peaks along the stride and

which.max

number of k that coincides with the highest number of faithful species

When indicator species analysis was performed on an object of that class, an object of VegsoupPartitionFidelity obtained, again with it's own unique and additional properties.

Properties of Vegsoup* objects

As outlined above, a Vegsoup object contains several data partitions. Besides the species and sites data it contains a taxonomic reference for all taxa, a definition of a cover scale, some standardisation statement(s), a dissimilarity measure to apply, and spatial coordinates. Basic parameters of existing Vegsoup objects can be obtained, and in most cases also changed, by:

decostand

retrieve or set a standardization method

vegdist

specify a dissimilarity measures

nrow,ncol,dim

return the dimensions of the species matrix

ncell,fill

report the number of cells and the proportion of non zero elements in the species matrix

coverscale

get or set coverscale

layers

the unique layers/strata

extent,bbox

spatial extent

proj4string

projection attributes (coordinate reference system)

For VegsoupPartition objects the following additional methods are defined.

partitioning

partitioning vector

getK

number of partitions

Summarizing and validation

Summary and print methods

print

show summary

head,tail

return the first or last parts of the species matrix

richness

dataset, sample or pooled species richness

For VegsoupPartition objects the following additional methods are defined.

spread

lists all occurrences of species in partitions

shared

matrix showing percentages of shared species between partitons

typical

identifies plots that typify partitions

outlier

outliers based on mean inter-plot dissimilarity or nearest neighbour criterion

silhouette

evaluates cluster by silhouette information

partana

evaluates cluster by partition analysis

disdiam

evaluates cluster by dissimilarity diameters

tabdev

calculates the probability of observing as low a deviance as observed

singleton

test if any partition has only 1 member

The species matrix stored in Vegsoup objects

There exists several methods that retrieve a community table as class matrix from Vegsoup objects. All methods access slot 'species' of an object. Transposed versions of each are available with the mode argument.

as.logical

returns a matrix with zeros coding for absences and ones for presences

as.numeric

returns a matrix with species abundances decoded by a coverscale, usually percentage cover

as.character

returns a matrix with species abundances in the data set's original scale

as.matrix

equivalent to the above, but storage type controlled by argument typeof

as.array

multidimensional dimensional array where each layer represents a dimension

as.vector

returns a vector with storage mode controlled by argument mode

indices

pointer to non empty cells in the species matrix

rowSums,colSums

row and column sums for the the species matrix

rowMeans,colMeans

row and column means for the the species matrix

as.dist

compute a dissimilarity matrix

For VegsoupPartition objects the following additional methods are defined.

quantile

sample quantiles for each species in each partition

Row and Column Names

Vegsoup objects have row and column names. Row names are the plots (relevée). Row names are shared among the species matrix and the sites data frame. Column names are either dimnames of the species matrix (class matrix) or the names of the sites data (colnames relates to the species matrix, whereas names relates to the sites data). The $ operator acts like with normal data frames, it extracts the sites data. Replacement methods are also defined.

rownames,row.names

plot names (mode character), the identifier of the sampling units

colnames

compound string of abbreviated scientific species names and layer (collapsed with @)

dimnames

dimnames(as.matrix(x)) equaling rownames and colnames as above

names

column names of the sites data

Print and summary methods

There are several ways to print Vegsoup* objects.

relevee

list a single relevee

taxalist

list of taxon names

abbr

abbreviations (abbr) used to encode scientific species names

Manipulating Vegsoup objects

There are several ways to manipulate Vegsoup* objects.

bind

combine a sequence of objects and bind to a single object

Extract

basic row and column-wise indexing

subset

subset based on literal taxon names

combine

combines two or more taxa by selecting scientific species names

layers<-

modify an object's layer structure

For VegsoupPartition objects the following additional methods are defined.

partition

extract parts (partitions) of an object

reorder

reorder an partitioned object based on the topology of a dendrogram

seriation

modify an objects internal order as to reflect a vegetation table

Sample Operation

Vegsoup* object can be (sub)sampled with the following methods.

sample

random samples and permutations

hcr

heterogeneity-constrained random samples

Table methods

Only class VegsoupPartition has meaningful table methods, although some work for Vegsoup* objects as well (constancy and contingency).

constancy

constancy table

contingency

contingency table

average

table of mean abundances in partitions

confusion,accuracy

cross-classifies each partition by actual and predicted class memberships

as.table

tabulation of partitioning(obj) against a cross-classifying factor

partitioningMatrix

memberships of plots to partitions

partitioningCombinations

tabulate all possibele combinations of partitions

Optimization

The clustering partition vector of VegsoupPartition objects can be optimized using the below set of methods.

optsil

modify partitioning as to optimize silhouette widths

remos

as above but deploy the REMOS method

optindval

modify partitioning as to optimize Dufrene and Legendre's indicator value

Spatial methods

Methods from spatial packges.

spTransform

extract the values of a raster object (package sp)

over

overlay method for spatial polygons (package sp)

extract

extract the values of a raster object (package raster)

Plotting

quicklook

opens a browser window and plots pushpins of plot coordinates

rectangles

plots a box according to number of species and sites for each partition

plotPCO

plot principal coordinates

coldiss

plots unordered and ordered colored matrix of dissimilarities

Typesetting

Latex

Create synoptic vegetation tables to be compiled by with LaTex. The synoptic package (https://github.com/kardinal-eros/synoptic) provides another implementation.

Writing files

Basic and advanced writing of entire files or parts thereof.

write.verbatim

generates a table structures with mono-spaced fonts

Latex

table structures to be compiled by LaTeX

KML

visualization in google earth

Miscellaneous

Miscellaneous methods and functions.

compass

cuts numeric values of angular degrees into characters of the wind-rose

tile2latlng

geocoding functionality using the grid scheme of tile map services

elevation

topographic height information from the SRTM3 data set

Acknowledgements

Extensive suggestions were made by ... and many others.

Author(s)

Maintainer: Roland Kaiser [e-mail]

See Also

vegan optpart labdsv vegdata mefa

vegsoup documentation built on Feb. 24, 2021, 3 a.m.