stack: Stack Species Matrix, Sites Data or Spatial Coordinates
In vegsoup: Classes and Methods for Phytosociology

Description Usage Arguments Details Value Note Author(s) See Also Examples

All functions reshape a data frame between wide format with measurements in separate columns to long format with the measurements in separate rows (see reshape).

The long format is called as such, because more sampling results in a lengthening of the data (i.e., the addition of rows) without any widening (i.e., the addition of columns). In contrast, it is common in community ecology to store abundance data as spreadsheets with sites as rows and species as columns. Such a data storage format is often called wide format, because more sampling may result additionally in a widening of the data (e.g., more columns are required as further sampling reveals an increasing number of species).

Function stackSpecies converts a matrix like input object, or file, into a representation in long format, where each observation on a species consists of one row in a resulting data frame that has as many rows as there are single species occurrences in the data set, including layer replicates (see Species).

In a similar fashion, function stackSites can be used to derive the long format from a plot by variable matrix (see Sites).

Function stackCoordinates collects spatial coordinates from spatial data stored on disk by calls to readOGR. It then reshapes two or three columns (in case of 3D features) of spatial coordinates along with a plot identifier to the format defined by class Sites.

Results of stackSites and stackCoordinates can be combined using bind to associate the sites with spatial information as intended for Vegsoup objects (see ‘Examples’).

stackSpecies(x, file, sep = ";", dec = ",", schema = c("abbr", "layer"),
             discard = c("taxon", "comment"), absences, zeros = FALSE, verbose = FALSE)

stackSites(x, file, sep = ";", dec = ",", schema = "plot", zeros = FALSE, verbose = FALSE)

stackCoordinates(dsn, layer, schema, round = TRUE, verbose = TRUE, ...)

# Arguments to all functions

`x`	An object converted to a data frame.
`file`	character. Path to a csv-file
`sep, dec`	character. See `read.csv`.
`schema`	character. Names of columns to be searched for. For `stackSites()` `schema = "rownames"` is available. See ‘Details’.
`zeros`	logical. If `TRUE`, drop leading zeros in plot names.
`verbose`	Prints some diagnostic messages.

# Arguments for function stackSpecies

`absences`	Character used to code absences. Can be missing, see ‘Details’.
`discard`	Names of additinal columns to be discarded.

# Arguments for function stackCoordinates

`dsn`	Data source name. See `readOGR`.
`layer`	Layer name. See `readOGR`.
`round`	Round decimals to given precision. See ‘Details’.
`...`	additional arguments passed to `readOGR`. For `bind` method, objects of class `Species` respectively `Sites`.

For stackSpecies the supported data frame, either read from file, or passed as R object must hold columns corresponding to argument schema. The default schema is 'abbr', 'layer' (cf. class Species). The first element of schema has to name a column holding valid strings for 'abbr'. The second element defines the column that has layer memberships. Any further elements (e.g 'taxon') are only mandatory if x has additional columns except schema and the taxa block (the plain matrix of only species cover values, see below). These columns may also be covered by argument discard (possibly by its defaults). Any further fields can be used to store taxonomic or other relevant information (accuracy of determination) on a particular observation, again, this is not mandatory. The species matrix is assumed to have species in rows and plots in columns. Plot names are derived form names(x). If argument file is supplied, data is imported using read.csv(..., colClasses = "character"). This matters if species abundances were recorded on a non-ordinal scale (e.g. integers) and shall later be treated as continuos. The Coverscale) class controls these conversions.

Internal checking of type conversion is performed using type.convert to test for appropriate mode of the species abundances vector; setting verbose = TRUE will report results of this test. If argument absences is missing an almost save guess (matrix fill lower than 50%) !is obtained from the data and derived as the most frequent value in the species data matrix, these are usually species absences.

For stackSites there are no specific requirements about the form of the object, except that one column must be specified which will then be used as the plot identifier. The default is to search for a column named 'plot', but an other column name can be specified by argument schema.

For stackCoordinates the rgdal package needs to be loaded first. The first element of argument schema defines the name of the column in the OGR data source that identifies unique plots. This argument is mandatory and must match a column name in the spatial attributes data. A second element of argument schema can specify the name of the column in the OGR data source that identifies altitude measurements. If absent and the geometry is 3D the function reads the third (z) dimension of the data source. If verbose the function will print what is returned by ogrInfo. Irrespective of the geometry type the function will use the coordinates method in package sp to obtain a pair of geographic coordinates for each plot. In case of irregular polygons the centroid so obtained must not be accurate. If the coordinate reference system is not equivalent to CRS("+init=epsg:4326") it will be transformed.

stackSpecies returns an object of class Species stackSites and stackCoordinates returns an object of class Sites.

Functionality related to package rgdal is only available if this package is installed and loaded.

Roland Kaiser

bind, Species-class, Sites-class, reshapeSpecies, elevation, tile2latlng, read.csv, readOGR in package rgdal

# species matrix from the dune data set
require(vegan)
data(dune)

# create data.frame according to the defaults of the schema argument in stackSpecies
# there are two moss species in the dune data set, we assign them to a moss layer
x <- data.frame(abbr = names(dune),
                layer = c(rep("hl", 8), "ml",
                          rep("hl", 6), "ml",
                          rep("hl", 14)),
                t(dune))

# promote to class 'Species'
X <- stackSpecies(x, verbose = TRUE)

# stack corresponding sites data
data(dune.env)
x <- data.frame(plot = row.names(dune.env), dune.env)
Y <- stackSites(x, verbose = TRUE) # default schema = "plot" 

# the same using schema = "rownames"
Y <- stackSites(dune.env, schema = "rownames")

## create a file of dummy coordiantes in a common format for spatial data
# some random points
Y2 <- data.frame(x = rnorm(20), y = rnorm(20),
                  plot = unique(X$plot))

# promate to class 'SpatialPointsDataFrame'
coordinates(Y2) <- ~x+y
proj4string(Y2) <- CRS("+init=epsg:4326") # WGS84

# for demonstartion save to ESRI Shapefile
require(rgdal)
dsn <- tempfile()
layer <- "foo"
writeOGR(Y2, dsn, layer, driver = "ESRI Shapefile")

# read this file and promote to class 'Sites'
Y2 <- stackCoordinates(dsn, layer, schema = "plot")

# bind with remaining environmental data
Y <- bind(Y, Y2)
variables(Y)