Type:	Package
Title:	Multivariate Data Handling in Ecology and Biogeography
Version:	3.2-10
Date:	2025-07-12
Maintainer:	Peter Solymos <psolymos@gmail.com>
Description:	A framework package aimed to provide standardized computational environment for specialist work via object classes to represent the data coded by samples, taxa and segments (i.e. subpopulations, repeated measures). It supports easy processing of the data along with cross tabulation and relational data tables for samples and taxa. An object of class ‘mefa’ is a project specific compendium of the data and can be easily used in further analyses. Methods are provided for extraction, aggregation, conversion, plotting, summary and reporting of ‘mefa’ objects. Reports can be generated in plain text or LaTeX format. Vignette contains worked examples.
Depends:	R (≥ 2.14.0)
Suggests:	MASS, vegan, mefa4, Matrix
Imports:	methods
License:	GPL-2
URL:	https://github.com/psolymos/mefa
BugReports:	https://github.com/psolymos/mefa/issues
LazyLoad:	yes
LazyData:	true
NeedsCompilation:	no
Packaged:	2025-07-13 21:40:17 UTC; Peter
Author:	Peter Solymos [aut, cre]
Repository:	CRAN
Date/Publication:	2025-07-13 22:00:02 UTC

Create an Object of Class 'mefa'

Description

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.

Usage

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)

Arguments

Details

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.

Value

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

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.

Note

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.

Author(s)

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

References

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/

See Also

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.

Examples

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)

Extract and Aggregate Objects of Class 'mefa'

Description

These methods are useful when extracting or aggregating 'mefa' objects. The count data matrix, the matrices for segments and the linked tables of samples and taxa are extracted or aggregated at the same time.

Usage

## S3 method for class 'mefa'
aggregate(x, by.samp = NULL, by.taxa = NULL, ...)
## S3 method for class 'mefa'
x[i = 1:dim(x)[1], j = 1:dim(x)[2], k = 1:dim(x)[3], drop = FALSE]
xtab(x, ...)
samp(x, ...)
taxa(x, ...)
segm(x, ...)

Arguments

Details

If a 'mefa' object is aggregated, either or both tables for samples and taxa (depending on if the aggregation was made by rows, columns or both) are set to NULL. Because aggregation is not straightforward for data frames with mixed type of data (e.g. factors, character vectors), and the applied function (mean, sum, etc.) depends on the type of the numeric variables. Consequently, if new data table is needed, that must be defined again by the function mefa. If the original data frame contained only numeric columns, it can be easily aggregated if the function to apply is known. For factors and numeric columns, however, such aggregation is not defined.

The ordering of dimensions follow the ordering of the indices in the extraction call, except for nested subsets, when sequence of nested segments is not allowed to be affected by the extraction (error message is given). The extracting method retains samples and taxa tables as well. If non-nested segments are extracted, the x$xtab matrix will contain the sum of segments, and not the original values of x$xtab. Thus if a resulting 'mefa' object has only one segment, it will be identical to the x$xtab matrix. If nested segments are extracted, x$xtab will be identical to the last segment and not the sum of segments. See the examples for these differences. If the original object had nested segments and the first is excluded, segment names change as a result. If only one segment remains in the result, the nested attribute is turned off.

If the aggregation is done over a vector that is not part of the tables inside the 'mefa' object, it must have a class attribute to be recognised, use e.g. the as.factor function (see 'Examples').

The resulting 'mefa' object must contain at least 2 samples and 2 taxa.

Extractor functions xtab, samp, taxa, and segm extract the corresponding element from the 'mefa' object.

Value

An object of class 'mefa'.

Note

The aggregate method replaces the function strify, the [ method replaces the function exclmf of the old (< 2.0) versions of the mefa package.

Author(s)

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

References

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/

See Also

mefa

Examples

data(dol.count, dol.samp, dol.taxa)
x <- mefa(stcs(dol.count), dol.samp, dol.taxa)
## These two are identical
aggregate(x, "microhab")
aggregate(x, x$samp$microhab, inside = FALSE)
## Interaction
aggregate(x, c("method", "microhab"))
## Both samples and taxa tables
aggregate(x, "microhab", "familia")
## To use a factor
aggregate(x, "microhab", as.factor(rbinom(dim(x)[2], 1, 0.5)))
## Extraction
x[1:10, ]
x[, 1:5]
x[, , "broken"]
x[1:10, 1:5]
x[1:10, 1:5, 2]
## Note factor levels
y <- x[which(x$samp$method == "time"), ]
levels(y$samp$method)
z <- x[which(x$samp$method == "time"), drop = TRUE]
levels(z$samp$method)
## Note the differences in total sums
y <- mefa(stcs(dol.count), dol.samp, dol.taxa, nested = TRUE)
x[ , , 2]
y[ , , 2]

Abundance-Occupancy Plot

Description

Abundance-occupancy plot.

Usage

aoplot(x, ...)
## Default S3 method:
aoplot(x, log = TRUE, xlab, ylab, ...)

Arguments

Details

Column sums of x (species abundances) are plotted against column sums of the binarized x (species occupancy).

Value

Creates a plot as a side effect.

Invisibly returns abundance and occurrence values in a matrix.

Author(s)

Peter Solymos <solymos@ualberta.ca>

Examples

data(dol.count)
x <- mefa(stcs(dol.count))
aoplot(x)

Manipulation Tools for Class 'dist'

Description

Converts a 'dist' object into vector and vice versa.

Usage

vec2dist(x, size, labels = NULL, diag = FALSE, upper = FALSE, 
call = FALSE, method = NULL)
is.dist(x)
## S3 method for class 'dist'
stack(x, dim.names = FALSE, ...)

Arguments

Value

vec2dist returns an object of class dist.

is.dist returns a logical statement about the class of the object.

stack.dist returns a data frame with comuns row for row id's, col for column id's and dist for the distance values.

Author(s)

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

References

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/

Examples

vec2dist(1:3, 3)
vec2dist(1:3, 3, diag = TRUE)
vec2dist(1:3, 3, diag = TRUE, upper = TRUE)
vec2dist(1:3, 3, labels=letters[1:3])
x <- dist(1:5)
attr(x, "Labels") <- LETTERS[1:5]
x
is.dist(x)
stack(x)
stack(x, dim.names = TRUE)

Conversion Among Various Object Classes

Description

These functions coerce into class 'mefa' or 'stcs'; or converts 'mefa' or 'stcs' obects into a 'data.frame', 'matrix', 'array', 'list'.

Usage

as.stcs(x, ...)
## Default S3 method:
as.stcs(x, ...)
as.mefa(x, ...)
as.Mefa(x, ...)
as.Xtab(x, ...)
## Default S3 method:
as.mefa(x, samp, taxa, ...)
## S3 method for class 'array'
as.mefa(x, ...)
## S3 method for class 'list'
as.mefa(x, ...)
## S3 method for class 'mefa'
as.matrix(x, ...)
## S3 method for class 'mefa'
as.array(x, ...)
## S3 method for class 'mefa'
as.list(x, ...)
## S3 method for class 'stcs'
as.data.frame(x, ...)
## S3 method for class 'mefa'
as.data.frame(x, ..., fun, name, make.unique = FALSE)
mss(x, name, make.unique = FALSE, ...)
msr(x, name, make.unique = FALSE, ...)
mts(x, name, make.unique = FALSE, ...)
mtr(x, name, make.unique = FALSE, ...)

Arguments

Details

The usage of most of these coercion methods is trivial. Arrays and lists can be coerced into 'mefa' objects as if those were the segm element of it (either nested, or non nested). The reverse is true, when coercing an object of class 'mefa' into list or array, the segm element is used.

Coercing among object classes 'matrix' and 'mefa' is done via using the xtab element.

By as.data.frame.mefa, four kinds of data frames can be returned, depending on the function used as the fun argument: mss returns summary statistics for samples (richness and abundance) and x$samp; msr returns raw data (x$xtab) and x$samp; mts returns summary statistics for taxa (occurrence and abundance) and x$taxa; mtr returns raw data (t(x$xtab)) and x$taxa.

The name can be used if only a subset of the summary statistics, or raw data should be returned. The character vector should contain names of elements to return (see examples).

It might (rarely) occur, that names of the summary statistics, or the raw data and the column names of the sample/taxa table overlap (contains names that are common in the two set). In this case, the make.unique = TRUE can be used to resolve non-uniqueness and avoid the error message produced otherwise.

The functions supplied as the fun argument can be used separately. Although the usage of the as.data.frame method is more transparent.

Value

An object of class 'stcs', 'mefa', 'matrix', 'array', 'list' or 'data.frame', depending on the method used.

Author(s)

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

References

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/

See Also

mefa, stcs, as.matrix, as.list, as.array, as.data.frame

Examples

data(dol.count, dol.samp, dol.taxa)
x <- mefa(stcs(dol.count), dol.samp, dol.taxa)
## These two are equivalent
as.data.frame(x, fun = mss)
mss(x)
## Return only two species
as.data.frame(x, fun = msr, c("iiso", "ppyg"))
## Taxa table and summary
as.data.frame(x, fun = mts)
## Taxa table and raw data transpose
as.data.frame(x, fun = mtr)
## Why is it useful?
## Instead of
glm(x$xtab[,"amin"] ~ microhab + method, data = x$samp, family = poisson)
## it is more convenient to use
glm(amin ~ microhab + method, data = msr(x), family = poisson)

The Dolina Dataset

Description

Data were collected in dolines (sinkholes, karstic depressions) of Northeast Hungary.

Usage

data(dol.count)
data(dol.samp)
data(dol.taxa)

Format

The dol.count data set is a data frame with 297 observations on the following 4 variables.

samp

a factor with levels for samples.

taxa

a factor with levels for the species.

count

a numeric vector with count data.

segm

a factor with levels for segments.

The dol.samp data set is a data frame with 24 observations on the following 2 variables.

microhab

a factor with levels dead.wood litter live.wood rock for microhabitats.

method

a factor with levels time quadrat for the sampling method applied.

The dol.taxa data set is a data frame with 121 observations on the following 4 variables.

species

a factor with levels the species names.

author

a factor with levels for authors of the species and description dates (accents are removed).

familia

a factor with levels for family level classification.

size

a numeric vector for major shell dimension of the adult specimen.

Details

The data sets are results of the 'DOLINA 2007' expedition (Vilisics et al. 2008). Species characteristics are based on Kerney et al. (1983). The full dataset (S\'olymos & Kemencei 2008) from which this example was derived is available at the Dataverse Network (hdl:1902.1/12060) with the code to make the subsetting.

Source

S\'olymos, P., Kemencei, Z. (2008) Methodological study data set of land snails from the Dolina 2007 project. Available at the Dataverse Network: hdl:1902.1/12060.

S\'olymos, P., Kemencei, Z., P\'all-Gergely, B., Farkas, R., Vilisics, F., Hornung, E. (2009) Does shell accumulation matter in micro scale land snail surveys? Malacologia, 51, 389–393.

Vilisics, F., Nagy, A., S\'olymos, P., Farkas, R., Kemencei, Z., P\'all-Gergely, B., Kisfali, M., Hornung, E. (2008) Data on the terrestrial isopoda fauna of the Als\'o-hegy, Aggtelek National Park, Hungary. Folia Faunistica Slovaca 13, 9–12.

Kerney, M. P., Cameron, R. A. D., Jungbluth, J. H. (1983) Die Landschnecken Nord- und Mitteleuropas. P. Parey, Hamburg-Berlin, 384 p.

Examples

data(dol.count)
str(dol.count)
data(dol.samp)
str(dol.samp)
data(dol.taxa)
str(dol.taxa)

Replace <NA> Values with Nearest Above Values

Description

The function replaces <NA> values with the nearest values above them in the same column.

Usage

fill.na(x)

Arguments

Details

This function is useful when converting a 'notebook style' data into an 'stcs' object. The 'notebook style' data means that observations are registered in a non-redundant way, e.g. when typing in a spreadsheet.

Value

A matrix or a data frame.

Note

This function is not vectorized, so can be a bit slow for large data sets.

Author(s)

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

References

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/

See Also

stcs

Examples

x <- data.frame(
    samp = c("s1",NA,"s2",NA,"s3","s4"),
    taxa = c("t1",NA,"s1","s2","s3",NA),
    count = c(1, 2, 10, 3, 4, 1),
    segm = c("male","female","male","female","male","male"))
x
fill.na(x)
fill.na(c(1:4, NA))

Image Plot of a 'dist' Object

Description

Image plot of a 'dist' object.

Usage

## S3 method for class 'dist'
image(x, grad, lab = TRUE, ...)

Arguments

Value

Creates an image plot as a side effect.

Invisibly returns plotted values.

Author(s)

Peter Solymos <solymos@ualberta.ca>

Examples

data(dol.count, dol.samp)
m <- mefa(stcs(dol.count), dol.samp)
d <- dist(m$xtab)
g <- with(m$samp, interaction(microhab, method))
image(d)

Assign Label to an Object and Return It

Description

This function assigns a label to any kind of object. The label later can be retrieved and reused.

Usage

label(x)
label(x) <- value

Arguments

Details

The label can be any expression assigned to any object. It is stored as a character attribute. Inheritance is not implemented, so by any transformation of the object into another one, the label is lost.

Value

Print out the label value.

Author(s)

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

References

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/

Examples

x <- 1:10
x
## Assign a character
label(x) <- "x is a vector"
x
## Get back the label
label(x)
## Note the effect of deparsing
label(x) <- 1:10
label(x)

Matrix Manipulation Tools

Description

Converts a matrix to a list, calculates matrix fill, or exclude rows/columns with certain rox/column sums.

Usage

mat2list(x, MARGIN = 1)
mfill(x)
rdrop(x, cutoff = 0, attrib = FALSE)
cdrop(x, cutoff = 0, attrib = FALSE)

Arguments

Value

mat2list returns a list of length nrow(x) or ncol(x) depending on MARGIN. Elements are rows/columns of x. Dimnames are retained as names.

mfill returns a single number with the matrix fill value.

rdrop and cdrop returns the original object but excluding rows (rdrop), or columns (cdrop) that has sum <= cutoff. Excluded row/colum numbers and specifications are stored in the "exclude" attribute of attrib = TRUE.

Author(s)

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

References

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/

Examples

x <- matrix(1:12, 3, 4)
rownames(x) <- letters[1:3]
colnames(x) <- LETTERS[1:4]
mat2list(x, 1)
mat2list(x, 2)
x[2, ] <- 0
x[, 2] <- 0
mfill(x)
mfill(x) == sum(x > 0) / prod(dim(x))
rdrop(x)
cdrop(x)
cdrop(x, cutoff = 5)
cdrop(x, cutoff = 22) # be careful

Check and Compare Object(s) of Class 'mefa'

Description

The functions evaluates the internal structute of a 'mefa' object.

Usage

mefaCheck(x)
mefaCompare(x1, x2, strict = FALSE)

Arguments

Value

mefaCheck returns a list, first element is logical with TRUE indicating that all requirements are met. If this is FALSE, following elements of the list describe the encountered problems as characters. mefaCheck is called by the is.mefa function.

mefaCompare compares two mefa objects. If all dimnames, and the corresponding values in the xtab and segm parts are identical, the result is TRUE, and otherwise FALSE. Different ordering of dimnames allowed, the comparison is based on the numeric values determined by dimnames.

Author(s)

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

References

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/

See Also

mefa, is.mefa, all.equal.list

Examples

x <- matrix(rpois(20,1), 5, 4)
m <- mefa(x)
mefaCheck(m)
data(dol.count)
x1 <- mefa(stcs(dol.count))
x2 <- mefa(melt(x1))
mefaCompare(x1, x2)
mefaCompare(x1, x2, strict = TRUE)

Cross Tabulate an Object of Class 'stcs'

Description

The function makes cross tabulation of an object of class 'stcs'. Similar to the table function but handles specialities of the 'stcs' object class (i.e. removes 'pseudo species' created to indicate empty samples). This is used internally by the function mefa to make 3 dimensional representation of the data.

Usage

mefaCrosstab(x, segment = FALSE, nested = FALSE, drop.zero = FALSE)

Arguments

Details

The cross tabulation of an object of class 'stcs' is made by the function xtabs, whic accepts non-integer values too.

Value

It returs a matrix if segment = FALSE or a list with matrices for the segments if segment = TRUE.

Author(s)

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

References

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/

See Also

stcs, mefa, rep.data.frame

Examples

x <- data.frame(sample = LETTERS[c(1,1,2,2,3,4)],
    species = c(letters[c(5,5,5,6,7)], "zero.pseudo"),
    count = c(1,2,10,3,4,0), segment = letters[c(8,9,8,9,8,8)])
y <- stcs(x)
mefaCrosstab(y)
mefaCrosstab(y, segment = TRUE)
mefaCrosstab(y, segment = TRUE, nested = TRUE)
## Examples for non-integer data
y[1:5, 3] <- y[1:5, 3] + 0.123
mefaCrosstab(y)
mefaCrosstab(y, segment = TRUE)

Make Non-Nested 'mefa' Object

Description

The functions makes a non-nested 'mefa' object.

Usage

mefaNestedless(x)

Arguments

Value

Returns an object of class 'mefa', with non-nested segments. This function is internally used by the melt.mefa function.

Author(s)

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

References

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/

See Also

mefa, is.mefa, melt.mefa

Examples

data(dol.count)
x <- mefa(stcs(dol.count), nested = TRUE)
x
y <- mefaNestedless(x)
y

Subsetting and Ordering of Related Data Tables

Description

This function is called by the mefa function to subset the community data matrix and the related data frames, but can be applied more generally for subsetting and ordering.

Usage

mefaTables(xtab, dframe, margin, index = NULL,
drop.index = FALSE, xtab.fixed = TRUE)

Arguments

Value

Returns a list with elements xtab (matrix) and dtab (data frame), corresponding to the subsetted xtab and dframe data sets, respectively. Original column and row orderings in the input matrix xtab are preserved.

Author(s)

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

References

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/

See Also

mefa

Examples

x <- matrix(rpois(20,1), 5, 4)
## Note the reverse alphabetical names
rownames(x) <- letters[5:1]
x
f <- data.frame(matrix(rnorm(30), 10, 3))
rownames(f) <- letters[1:10]
f
## Reverse alphabetical names preserved
mefaTables(x, f, 1)
## Now result is the intersect
rownames(f) <- letters[3:12]
mefaTables(x, f, 1, xtab.fixed = FALSE)

Display Package Documentation

Description

Display package documentation using pager or pdfviewer defined in options.

Usage

mefadocs(doc = c("ChangeLog","SampleReport"))

Arguments

Details

"ChangeLog" contains version history, "SampleReport" shows an example LaTeX document how to use report.mefa to prepare Sweave reports based on faunistic data.

Author(s)

P\'eter S\'olymos (solymos@ualberta.ca) adapted Jari Oksanen's vegandocs function in the vegan package.

Examples

## Not run: 
mefadocs("Change")
mefadocs("Sample")

## End(Not run)

Schematic Plot of an Object of Class 'mefa'

Description

Plots a shematic representation of and object of class 'mefa', or alternatively plots a colored logo of the mefa package.

Usage

mefalogo(type = c("cont", "fill"), labels = c("str", "r"),
adj=c(0,0), scale=c(1,1), new = TRUE, cex = 1, ann=FALSE, axes=FALSE,
xlim=c(0,10)*scale[1]+adj[1], ylim=c(0,10)*scale[2]+adj[2], ...)

Arguments

Details

This function was developed for depicting the general structure of the 'mefa' objects. The colored logo version can be used in presentations as well.

Author(s)

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

References

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/

Examples

mefalogo()
mefalogo("fill", "r")

Open 'mefa' Website

Description

Opens the 'mefa' website in the default navigator.

Usage

mefaweb()

Details

The website contains resources for the 'mefa' package, please check out for more. Thank you!

Author(s)

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

References

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/

Examples

## Not run: 
mefaweb()

## End(Not run)

Melt (Convert) an Object of Class 'mefa' Into 'stcs'

Description

The function converts a wide formatted 'mefa' object into a long formatted 'stcs' object. The resulting segment column can take various formats.

Usage

melt(x, ...)
## S3 method for class 'mefa'
melt(x, segm.var = NULL, by.samp = TRUE,
raw.out = FALSE, drop.zero = FALSE, ...)

Arguments

Details

If a 'mefa' objet has original segments and segm.var = NULL, the function returns original segments. In this case, the raw.out = TRUE cannot be applied (because segments have different zero samples, so the option is meaningless). If the 'mefa' object contains only a data matrix without dimnames, rows and columns are numbered before melting.

Besides the goal to convert from wide format to long format, this 'mefa' specific implementation is also useful, if a segment is not coded along with the long formatted database, but can be found in a linked table of samples or species. In this way, a 'mefa' object with new segments can be defined easily.

If melting is done with a vector that is not part of the tables inside the 'mefa' object, it must have a class attribute to be recognised, use e.g. the as.factor function (see 'Examples').

Value

An object of class 'stsc' if raw = FALSE, pure 'data.frame' otherwise (because the zero count flag cannot be applied).

Author(s)

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

References

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/

Examples

data(dol.count, dol.samp, dol.taxa)
x <- mefa(stcs(dol.count), dol.samp, dol.taxa)
## Long format with original segments
melt(x)
## Long format with undefined segment
melt(as.mefa(x, segment = FALSE))
## These two are identical
melt(x, "microhab")
melt(x, x$samp$microhab) ## this is a factor
## Using a simple vector as factor
melt(x, as.factor(rbinom(dim(x)[1], 1, 0.5)))
## Interaction
melt(x, c("method", "microhab"))
## From taxa table
melt(x, "familia", by.samp = FALSE)
## Example for non-integer data
y <- x$xtab
y[y > 0] <-  y[y > 0] + 0.123
z <- mefa(y)
melt(z)

Plotting Methods for Object of Class 'mefa' and 'stcs'

Description

Various methods for plotting objects of class 'mefa'.

Usage

## S3 method for class 'mefa'
plot(x, stat = 1:4, type = c("hist", "rank"),
trafo = c("none", "log", "ratio"), show = TRUE, ylab, xlab, ...)
## S3 method for class 'mefa'
boxplot(x, stat = 1:4, all = TRUE, show = TRUE, ylab, xlab, ...)
## S3 method for class 'mefa'
image(x, segm=NULL, trafo=c("none", "log", "bins", "prab"), 
probs = seq(0, 1, 0.05), ordering = TRUE, reverse = TRUE, names = FALSE,
show = TRUE, ylab, xlab, ...)
## S3 method for class 'stcs'
plot(x, stat = 1:4, type = c("hist", "rank"),
trafo = c("none", "log", "ratio"), show = TRUE, ylab, xlab, ...)
## S3 method for class 'stcs'
boxplot(x, stat = 1:4, all = TRUE, show = TRUE, ylab, xlab, ...)
## S3 method for class 'stcs'
image(x, segm=NULL, trafo=c("none", "log", "bins", "prab"), 
probs = seq(0, 1, 0.05), ordering = TRUE, reverse = TRUE, names = FALSE,
show = TRUE, ylab, xlab, ...)

Arguments

Details

plot returns barchart/histogram, or ranked curve of summary statistics (number of species, individuals in samples, number of occurrences or abundance of taxa) based on the x$xtab matrix of the 'mefa' objects. These values are basically returned by summary.mefa.

boxplot returns box-and-whiskers plots for the summary statistics based on matrices for each segments in x$segm.

image creates a grid of colored rectangles with colors corresponding to the values in the segment defined by the argument segm. If ordering = TRUE, the ordering of the segment will be based on the x$xtab matrix and not on the matrix for the segment itself. This is due to better comparison among segments.

All graphical display methods for objects of class 'stcs' are based on the conversion of the object into 'mefa', and than the respective plotting method is applied. The conversion is made based on the default mefa settings (e.g. with segments). If more control is needed over the object structure, use the mefa function to coerce to a more appropriate class for this.

Value

All methods produce a plot if show = TRUE, and return the plotted values invisibly, or visibly if show = FALSE.

Author(s)

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

References

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/

See Also

image, plot, boxplot, filled.contour, par, heat.colors, topo.colors, terrain.colors, rainbow

Examples

data(dol.count, dol.samp, dol.taxa)
x <- mefa(stcs(dol.count), dol.samp, dol.taxa)
## Frequency distributions
opar <- par(mfrow=c(2,2))
plot(x, 1)
plot(x, 2)
plot(x, 3)
plot(x, 4)
par(opar)
## Ranked curves
opar <- par(mfrow=c(2,2))
plot(x, 1, type="rank")
plot(x, 2, type="rank")
plot(x, 3, type="rank")
plot(x, 4, type="rank")
par(opar)
## Boxplot for segments
opar <- par(mfrow=c(2,2))
boxplot(x, 1)
boxplot(x, 2)
boxplot(x, 3)
boxplot(x, 4)
par(opar)
## Image (levelplot)
## comparing all and the segments
opar <- par(mfrow=c(1,3))
image(x, trafo = "bins", main = "All segments")
image(x, segm = 1, trafo = "bins", main = dimnames(x)$segm[1])
image(x, segm = 2, trafo = "bins", main = dimnames(x)$segm[2])
par(opar)
## For black and white, with names
image(x, col = grey(seq(0, 1, 0.1)), names = TRUE)
## For nice colors other than default
opar <- par(mfrow=c(1,2))
image(x[,,"fresh"], col = topo.colors(10),
main = "Fresh")
image(x[,,"broken"], col = terrain.colors(10),
main = "Broken")
par(opar)

Ordinal Transformation of a Vector

Description

Converts a numeric vector into an ordinal one based on quantiles.

Usage

qvector(x, probs = seq(0, 1, 0.25), na.rm = FALSE, ...)

Arguments

Value

A numeric vector of length the same as the input vector, containing the respective (upper) quantile values.

Author(s)

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

References

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/

See Also

quantile

Examples

x <- rnorm(20)
x
y <- qvector(x)
y
rbind(x, y)
plot(x, y, type="h")

Inflate (repeat) a Data Frame

Description

The function inflates a data frame based on count values in a vector corresponding the rows.

Usage

## S3 method for class 'data.frame'
rep(x, ...)

Arguments

Details

Each rows of the data frame x will be repeated as many times as the corresponding value in e.g. the vector times. This function is called internally by the function stcs.

Value

A data frame with columns as in the original (x) and e.g. sum(times) number of rows.

Author(s)

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

References

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/

See Also

stcs

Examples

x <- data.frame(sample = LETTERS[c(1,1,2,2,3)],
    species = letters[c(5,5,5,6,7)],
    count = c(1,2,10,3,4), segment = letters[c(8,9,8,9,8)])
x
rep(x[,c(1,2,4)], times = x[,3])
rep(x[,c(1,2,4)], each = 2)

Write Report of an Object of Class 'mefa' into File

Description

The data of the 'mefa' object is written into a file in a standard format used by most local journals for publishing distribution data of organisms. The aim is to provide an exporting facility that can directly be used for generating reports, parts of research papers, or supplementary materials.

Usage

report(x, ...)
## S3 method for class 'mefa'
report(x, filename, segment = FALSE, n = NULL,
    by.taxa = TRUE, samp.var = NULL, drop.redundant = NULL,
    collapse = TRUE, taxa.name = NULL, author.name = NULL,
    taxa.order = NULL, grouping = FALSE, tex = FALSE, binary = FALSE,
    tex.control = list(ital.taxa = TRUE, noindent = TRUE, 
    bold.sect = TRUE, bold.1st = TRUE, vspace1 = 0.5, vspace2 = 0.2),
    sep = c(",", ":", "(", ":", ",", ")", ";"), dir = getwd(), ...)

Arguments

Details

The resulting file can be recycled by copy-and-pasting into a document (if tex = FALSE) or be included into a LaTeX report (e.g. via the package Sweave, see mefadocs("SampleReport")). Contrary to the many arguments, the default values do not need much modifications in most of the cases (see examples).

Value

Writes a file into the working (or a specified) directory.

Note

The by.taxa = FALSE option is not yet implemented.

Author(s)

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

References

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/

See Also

mefa, write

Examples

data(dol.count, dol.samp, dol.taxa)
x <- mefa(stcs(dol.count), dol.samp, dol.taxa)
## Not run: 
## Plain text
## Count values from x$xtab
report(x, "report-all.txt")
## Count values for each segments
report(x, "report-segm-all.txt",
    samp.var = c("method","microhab"), segment = TRUE)
## LaTeX formatting
report(x, "report-all.tex", tex=TRUE)
## For how to include into a TeX or Rnw file, see:
mefadocs("SampleReport")

## End(Not run)

Create an Object of Class 'stcs'

Description

This function creates object of class 'stcs' from a data frame. This is the primary format for long (database style) data sets in the mefa package. The 'stcs' object can be converted into an object of class 'mefa' with the function mefa. The function name 'stcs' refers to first letters of column names of the resulting object: samples, taxa, counts, segments.

Usage

stcs(dframe, expand = FALSE, drop.zero = FALSE, zero.pseudo = "zero.pseudo")
## S3 method for class 'stcs'
is(x)
## S3 method for class 'stcs'
summary(object, ...)

Arguments

Details

If the data are in a long (database style) format, the stcs function prepares the ground for the mefa function to make the cross tabulation. But if only a crosstabulated matrix is needed, the table function can be applies as well (in this case be sure to set expand = TRUE, and this is only for integer data), or alternatively see the xtabs or mefaCrosstab functions (these accepts non-integer data). For subsetting, simply use extraction methods available for data frames ([.data.frame).

The summary contains statistics calculated after coercing the object into the class 'mefa'.

Methods for extracting, subsetting are the same as for data frame objects. Plotting 'stcs' objects are discussed elsewhere (see links in 'See also' section).

Value

Returns an object of class 'stcs' with 4 columns. The column names are converted consistently into samp for samples, taxa for taxa names, count for counts and segm for segment names.

The class has its own methods (i.e. is, as.stcs, summary and plot), but also has a data.frame class attribute. Thus other methods that available for data frames are applicable to an object of class 'stcs' (e.g. print, str).

Note

The stcs function nearly equivalent to the sscount function in older (< 2.0) versions of the mefa package.

Author(s)

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

References

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/

See Also

data.frame, summary.data.frame, str, table

See plot.stcs boxplot.stcs and image.stcs for graphical display options.

See as.stcs for coercion methods.

Examples

## General long format data
x <- data.frame(
    sample = paste("Sample", c(1,1,2,2,3,4), sep="."),
    species = c(paste("Species", c(1,1,1,2,3), sep="."),  "zero.pseudo"),
    count = c(1,2,10,3,4,0),
    segment = letters[c(6,13,6,13,6,6)])
x
## Long format as stcs
y <- stcs(x)
y
## Methods
as.stcs(x)
is(y, "stcs")
is(y, "data.frame")
## Effects of arguments
stcs(x, expand = TRUE)
stcs(x, drop.zero = TRUE)
stcs(x, zero.pseudo = "pseudo.secies")
## Input options
stcs(x[,1:2])
stcs(x[,1:3])
stcs(x[,c(1:2,4)])
## The Dolina dataset
data(dol.count)
dol <- stcs(dol.count)
dol
plot(dol)