Species-class: Species Class
In vegsoup: Classes and Methods for Phytosociology

Description Objects from the Class Slots Methods Details Author(s) See Also Examples

Data representation of species data in long format, where each observation of a species in a particular plot and vegetation stratum is represented by a single row with at least four columns, grouping the observation into plot, taxon, layer, and abundance (cover).

Objects can be created by calls of the form new("Species", ...), where ... expands to slot 'data'. Using the species method with appropriate objects is also convenient (see ‘Methods’). The stackSpecies function is useful when the data is in wide format (plot by species matrix).

data:

Object of class "data.frame" with at least four columns named 'plot', 'abbr', 'layer' and 'cov', all of type character. The meaning of these columns is as detailed below:

"plot" contains the plot identifier associated with each species observation, any numeric values are coerced to characters.
"abbr" typically contains unique abbreviations of a scientific latin name, although, any character string might be used (the full species name for example). It's handy however, to keep abbr short and intuitive. In any case, syntactic valid names are automatically created using make.names (e.g. blanks will be dots).
"layer" assigns a layer/stratum to each observation, even if they are all the same (e.g. the data includes only a single herb layer)
"cov" contains an estimate of species abundance or performance (e.g. plant cover) coerced to as character, regardless if it is ordinal (e.g. Braun-Blanquet scale), continuous (frequencies or counts) or simple presence.

The above outlined data columns must be available in order to create a Species object and the species methods detailed below relies they are present, named or in the order above.

Besides these mandatory columns and their rigid names and order, it is possible for an object of class Species to contain more columns with data. Imagine, for example, additional useful information for an observed species in a particular plot (plant size, flowering/not flowering, etc.) is available.

species

There exists species methods for a number of R base classes:

signature(obj = "data.frame"): promote data.frame to object of class Species.

signature(obj = "matrix"): promote matrix to object of class Species. Note, obj does not need to have dimnames, but order matters.

signature(obj = "character"): supply a file to be read by read.csv and promote that object to class Species. Remember to pass appropriate arguments to read.csv that meet the specifications of your file (e.g. argument sep).

The following classes defined in the vegsoup package have a species method:

signature(obj = "Species"): accessor function (slot 'data'). Returns class data.frame.

signature(obj = "SpeciesTaxonomy"): accessor function (slot 'taxonomy'). Returns class Species.

signature(obj = "Vegsoup"): accessor method for slot 'Species', equals species(obj) and returns an object of class Species. Use species(species(obj)) to get the slot 'data'. species(obj)@data should be avoided.

signature(obj = "VergsoupVerbatim"): promote "VegsoupVerbatim" object to class Species.

species<-

signature(obj = "Vegsoup", value = "Species"): assign (possibly subset) with object of class Species.

nrow

signature(x = "Species"): the number of rows. Each observation of a species in plot (stratum-replicate) constitutes a row.

dimnames

signature(x = "Species"): non unique dimnames. The dimnames that are constructed by pasting plot and layer collapsed with @. Not to be called by the user.

[

signature(x = "Species"): subset parts of an object. Note, indexing that will evaluate to an object with less than four columns will fail, due to the class inherent data model (see ‘Slots’).

$

signature(x = "Species"): retrieve column by name (see ‘Slots’), or perform replacement.

bind

signature(x = "Species"): bind method to combine two or more objects. See verbatim for an example.

The initialization step for the class involves some basic checks of data integrity. If duplicated species are identified for a specific plot a warning is issued and duplicates are dropped automatically. The same applies to duplicated species abundances for plots. Finally an ordering of the form order(plot, layer, data) is performed during initialization. None of the first four columns can contain NA, as this will not allow a valid object of the class to be built.

The design of the the class initialization method allows for data that have not been checked for data stringency. Such data might arise when field data was digitized without the help of a database system, for example, by using spread sheet software. The default behavior is to discard all ambiguities in the data (e.g. duplicated observations of species in the same plot and/or in the same stratum).

A standard procedure to abbreviate scientific names is to use four first letters of the generic name and four first letters of the specific epithet (see make.cepnames). Depending on the number of taxa that need to be encoded, another block of four letters might be necessary, in order to reference lower taxonomic ranks, or to make non unique abbreviations unique.

Roland Kaiser

class SpeciesTaxonomy and function SpeciesTaxonomy, Taxonomy, Sites, Vegsoup, stackSpecies

require(vegsoup)

showClass("Species")

data(barmstein)

# for demonstration we first retrieve the slot 'Species' of an existing Vegsoup object
spc <- species(barmstein)
class(spc)

# the slot 'data' of a Species object can be accessed by
spc <- species(spc)
class(spc)

# this can also be written as
spc <- species(species(barmstein))

# matrix method to promote to class "Species"
s1 <- species(as.matrix(spc))
class(s1)

# combine two objects
data(windsfeld)
s2 <- species(windsfeld)
( s <- bind(s1, s2) )