mefa: Create an Object of Class 'mefa'
In psolymos/mefa: Multivariate Data Handling in Ecology and Biogeography

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

An object of class 'mefa' is a compendium of a crosstabulated taxa-by-samples (count) data, and optionally (count) data for segments, and linked tables for samples and taxa. The 'mefa' term stand for an acronym of 'metafaunistics', indicating that data processing is a critical and often time consuming step before data analysis. The 'mefa' package aims to help in this respect.

mefa(xtab, samp = NULL, taxa = NULL, id.samp = NULL, id.taxa = NULL,
segment = TRUE, nested = FALSE, drop.zero = FALSE, drop.index = FALSE,
xtab.fixed = TRUE)
## S3 method for class 'mefa'
is(x)
## S3 method for class 'mefa'
print(x, nlist = 10, ...)
## S3 method for class 'mefa'
summary(object, nlist = 10, ...)
## S3 method for class 'summary.mefa'
print(x, nlist, ...)
## S3 method for class 'mefa'
dim(x)
## S3 method for class 'mefa'
dimnames(x)

`xtab`	data. Can be an object of class 'stcs', or a matrix or data frame. Can be count (integer) or non-integer.
`samp`	a data frame containing rows for samples, or `NULL`. See argument `xtab.fixed` and details for sample matching options.
`taxa`	a data frame containing rows for taxa, or `NULL`. See argument `xtab.fixed` and details for taxa matching options.
`id.samp`	`NULL` if sample names for matching are the rownames of `samp`, otherwise, the index refers to the column of `samp` where the names are located.
`id.taxa`	`NULL` if taxa names for matching are the rownames of `taxa`, otherwise, the index refers to the column of `taxa` where the names are located.
`segment`	logical, whether information in the segments column of the 'stcs' object should be used (`TRUE`, default). It has no effect when `xtab` is matrix or data frame.
`nested`	logical, whether segments should be nested within each other from the first to the last (`TRUE`) or not (`FALSE`, default).
`drop.zero`	logical, if `TRUE` empty samples are removed from the result (can be useful before multivariate analyses). Otherwise, empty rows are left intact (`FALSE`, default).
`drop.index`	logical, whether columns of the samples and taxa tables containing the names used for matching should be removed (`TRUE`) to reduce redundancy or not (`FALSE`, default). This argument has effect only if `id.samp` and `id.taxa` are not `NULL`.
`xtab.fixed`	logical, if `TRUE` (default) the `samp` and `taxa` tables are subsetted and ordered according to the names of `xtab`. If `FALSE`, `xtab` is also subsetted according to the intersect of the names. Row and column ordering is determined by `xtab` in either cases.
`x, object`	an object of class 'mefa'.
`nlist`	number of elements in the list of segment names to print. List of segment names is truncated at 10 by default.
`...`	other arguments passed to functions.

Main goals of the mefa function are to (1) convert a long formatted object of 'stcs' into a crosstabulated and optionally segmented 'mefa' object and (2) link this crosstabulation with tables of samples and taxa. The segments can be nested within each other. This feature can be useful, if segments represent e.g. subsequent sampling periods (years) and the the aim is to detect effects of data accumulation over time.

A mefa object can be viewed as a project oriented compendium of the data. It contains 3 dimensional (samples, taxa, segments) representation of the count data and data tables for samples and taxa. Segments contain information on some particular internal division of the data (sub populations, method specific partitions, repeated measures), but it has technical significance. Thus data tables for segments are not supported.

Input values may contain non-integer values as well.

If the input xtab is a matrix, dimnames are necessary if either samp or taxa tables are provided. In other cases, dimnames are not necessary. In this way, simple statistics can be returned for the matrix.

The print method returns basic information, instead of a long structural representation.

The summary contains statistics calculated from the 'mefa' object (species richness, number of individuals, occupancy, abundance, total sum, matrix fill, etc., see 'Value' section). The list can be recalled by e.g. unclass(summary(x)), elements of the list e.g. summary(x)$s.rich.

Methods for extracting, subsetting, plotting and reporting 'mefa' objects are discussed elsewhere (see links in 'See also' section). On how the 'mefa' objects can be used in further analyses, see 'Examples' and the vignette (vignette("mefa")).

When the as.mefa function is used with a 'mefa' object as argument, samples and taxa tables are used when samp and taxa arguments are missing. If the aim is to redefine these tables, those also can be given.

The mefa function returns an object of class 'mefa'. It is a list with 5 elements:

`call`	the function call.
`xtab`	crosstabulated count data, rows are samples, columns are taxa.
`segm`	list of matrices if segments are used, otherwise `NULL`.
`samp`	a data frame for sample related data (rows correspond to samples) if provided, otherwise `NULL`.
`taxa`	a data frame for taxa related data (rows correspond to taxa) if provided, otherwise `NULL`.

The summary.mefa function returns a list invisibly, with elements: s.rich: vector with species richness values for the samples, s.abu: vector with number of individuals values for the samples, t.occ: number of sites occupied by each species, t.abu: abundances of each species, ntot: total number of individuals, mfill: matrix fill, nsamp: number of samples, ntaxa: number of taxa, nsegm: number of segments, segment: vector of segment names, call: the function call from the 'mefa' object, nested, drop.zero, xtab.fixed: attributes of the 'mefa' object.

The method dim returns a vector of length 3 with values for number of samples, number of taxa and number of segments in the 'mefa' object. The third value is 1 in cases, when s$segm is NULL (because it is 1 undefined segment essentially identical to the matrix x$xtab, thus no need for a replicate).

The dimnames method returns a list of three character vectors for names of samples, taxa and segments. These can be NULL as well.

The mefa function alone can be used instead of the combination of object classes xcount and xorder used in older (< 2.0) versions of the mefa package. Further it is also extended by previously undocumented features.

P\'eter S\'olymos, solymos@ualberta.ca

S\'olymos P. (2008) mefa: an R package for handling and reporting count data. Community Ecology 9, 125–127.

S\'olymos P. (2009) Processing ecological data in R with the mefa package. Journal of Statistical Software 29(8), 1–28. doi: 10.18637/jss.v029.i08

http://mefa.r-forge.r-project.org/

Further methods are discussed on separate help pages: see [.mefa and aggregate.mefa for extracting and aggregating the data, melt.mefa for redefining segments or melting data into long format, report.mefa for generating report into file, and plot.mefa boxplot.mefa and image.mefa for graphical display.

See as.mefa for coercion methods.

See table and xtabs functions.

data(dol.count, dol.samp, dol.taxa)
## Input is stcs
x1 <- mefa(stcs(dol.count))
x1
## Input is matrix
x2 <- mefa(x1$xtab)
x2
## Attach data frame for samples
x3 <- mefa(stcs(dol.count), dol.samp)
x3
## Attach data frame for samples and taxa
x4 <- mefa(stcs(dol.count), dol.samp, dol.taxa)
x4
## Methods
## (chapter 'See also' provides
## links for further methods)
summary(x4)
## Descriptives inside the summary
unclass(summary(x4))
## Testing mefa objects
is(x4, "mefa")
## Removing empty samples
as.mefa(x4, drop.zero = TRUE)
## Dimensions
dim(x4)
## Dimnames
dimnames(x4)
## Simple examples how to use mefa objects in analyis
## GLM on sample abundances
mod <- glm(summary(x4)$s.abu ~ .^2,
    data = x4$samp, family = quasipoisson)
summary(mod)
## See the demo and vignette for more examples
# demo(mefa)
# vignette("mefa")
## Cluster analysis of community matrix
x5 <- aggregate(x4, c("method", "microhab"))
h <- hclust(dist(x5$xtab))
plot(h)