Vegsoup: Create an object of class Vegsoup
In vegsoup: Classes and Methods for Phytosociology

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

The provided creator functions build the basic data structures of Vegsoup* objects from local R objects. Shorthand functions are provided to collect data files from a folder or build an object from a simple community matrix only, with dummy variables created for missing data structures (taxonomic reference list, sites data and/or coordinates). To simulate a data set an interface to the coenoflex package is provided.

Vegsoup(...) is the recommended user interface rather than the direct new("Vegsoup", ....) call.

Vegsoup(x, y, z, coverscale, group, sp.points, sp.polygons,
        proj4string = "+init=epsg:4326", stringsAsFactors = TRUE,
        verbose = FALSE)

coenoflex(i = 30, j = 20, gradients = 2, seed = NULL, ...)

plainsoup(m, coverscale, layer = "0l", verbose = TRUE)

instantsoup(folder, sep = ";", dec = ",", coverscale)

`x`	object of class `Species` or `SpeciesTaxonomy`.
`y`	object of class `Sites`.
`z`	object of class `Taxonomy`. Can be missing if `x` is of class `'SpeciesTaxonomy'`.
`m`	object that can be coereced to as matrix with plots as rows and species as columns.
`layer`	layer code to be assigned.
`folder`	Path to a folder with three csv files. One file named `species.csv` represents a table structure that can be coerced to class `'Species'` by simply calling `species("species.csv")`. Another file is coerced by `sites("sites.csv")` and the third one, a taxonomic reference list, is loaded via calls to `taxonomy("taxonomy.csv")`). For all these method the `character` dispatch is invoked (cp. `signature(obj = "character")` in the methods section for the respective method). If files for species and or sites carry the file suffix wide seperated with a blank, functions `stackSpecies` and `stackSites` are called.
`coverscale`	Abundance scale of the observations. Possible choices include all definitions given by `Coverscale`.
`group`	A-priori grouping, if any and can be missing.
`proj4string`	Projection attributes for slots 'sp.points' and 'sp.polygons'. If missing set to `CRS("+init=epsg4326")` (see `proj4string` for details).
`sp.points`	Object of class `SpatialPointsDataFrame`. If missing, it is tried to obtain coordinates from argument `'y'`, the sites data. If coordinate information can not be successfully extracted, a random point pattern in the unit square is generated.
`sp.polygons`	Object of class `SpatialPolygonsDataFrame`. If missing a random polygon pattern is generated based on `'sp.points'` equal to the number of plots (samples).
`stringsAsFactors`	Convert character strings in `y` to factors.
`sep`	See `read.csv` for parsing of csv files. Defaults are set according to `read.csv2`, also regarding `dec`!
`dec`	See `read.csv`.
`i, j, gradients`	number of plots (`n`) and species (`m`) to simulate on `gradient` (1 or 2 ).
`seed`	set random number generator to make results from methods reproducible.
`...`	Additional arguments passed to coenoflex.
`verbose`	Show status reports during function call.

Vegsoup() is the constructor function to create a prototype object of class Vegsoup. The first four arguments (x, y, z, coverscale) have to be specified. However, if argument 'x' inherits from class "SpeciesTaxonomy", argument 'z' can be left missing.

The creator function does not allow to specify all slots of an Vegsoup* object, but rather tries to guess some of it's contents. For example, if the sites data has variables exactly named longitude and latitude those will be used to extract coordinates from. For coordinates conforming to proj4string = "+init=epsg:4326" those have to be formatted as decimal degrees! See e.g. char2dms to convert between formats.

Function plainsoup is a utility function that demands on a community matrix, but nothing more. This function is suitable if there is no further information on sample plots (sites or environmental data) and the taxonomic concept used.

In order to build a Vegsoup object dummy values have to be created. Note, those will not be informative! To be exact, the function will create a single site variable named "X1" with all values set to zero. colnames(m) are used as abbreviations (see abbr) as well as full scientific latin names (see Taxonomy). All observations are put on a single layer encoded by argument layer. Because the cover (abundance) scale can not be guessed from argument m a suitable cover scale as object Coverscale needs to be assigned.

Function instantsoup is a shorthand when data files are guaranteed to conform to some format that can be interpreted by the import functions stackSpecies, respectively stackSites or are valid to simple calls to class creator methods species, sites and taxonomy all with signature 'character'. Arguments 'coverscale' and 'decostand' can be specified afterwards if needed, defaults of class Vegsoup apply otherwise. The same is true for argument 'proj4string'. The defaults for argument 'group' is to create a dummy integer variable of ones.

Function coenflex creates a random community with one or two gradients and specified size (number of species and ploits). The coenocline function in package coenocliner offers a complete interface. coenocline objects can be coerced to class Vegsoup with the as(obj, "Vegsoup") coerce method.

An object of class Vegsoup.

All missing values that might result when casting y will be replaced by NA!

If sp.points and/or sp.polygons arguments are supplied, the objects must have a column named plot.

When suppling argument proj4string ensure that CRS(proj4string) works.

If you gain errors using instantsoup, try to create separate objects for classes Species, Sites and Taxonomy. You may also want to call "SpeciesTaxonomy" for the first and last objects mentioned. Defaults for sep and dec passed to read.csv are set according to read.csv2!

Package coenoflex is currently missing from CRAN.

Roland Kaiser

Vegsoup-class as.matrix coverscale decostand vegdist

# load example data
data(barmstein)
( x <- barmstein )
# this will open a browser window
## Not run: quicklook(x)
	
# for demonstration rebuild objects from its components 
X <- species(x)
Y <- stackSites(cbind(sites(x), coordinates(x)), schema = "rownames")
Z <- taxonomy(x)

( x <- Vegsoup(X, Y, Z, "braun.blanquet") )

# Vegsoup object from community matrix only
# the dune data set
# see ?SpeciesTaxonomy for a more complete case
require(vegan)
data(dune)
x <- plainsoup(dune, "domin")

# plot ordinations of simulated data
x <- coenoflex(100, 50)
plotPCO(x, thresh = 0.2)
plot(metaMDS(as.logical(x)))

# if we omit 'as-logical' and the default 'as.matrix' applies
plot(decorana(x))

# promote to ordinal scale
coverscale(x) <- "ordinal"
table(species(coenoflex())$cov)

# order and coerce to a sparse matrix representation
vegdist(barmstein) <- "bray"
decostand(barmstein) <- "wisconsin"
as(seriation(barmstein, method = "packed"), "sparseMatrix")

# R-mode using mode argument, one of 'Q' or 'R'
as(as.logical(barmstein, mode = "R"), "sparseMatrix")