\documentclass[article,shortnames,nojss]{jss}
\usepackage{thumbpdf}

%% need no \usepackage{Sweave.sty}
\SweaveOpts{engine = R, strip.white = true, keep.source = TRUE, eps = FALSE}

\newcommand{\class}[1]{`\code{#1}'}

%\VignetteIndexEntry{Processing Ecological Data in R with the mefa Package}
%\VignettePackage{mefa}
%\VignetteDepends{MASS, vegan}
%\VignetteKeywords{biodiversity, biogeography, data manipulation, ecology, multivariate methods, R}

\author{P\'eter S\'olymos\\University of Alberta}
\Plainauthor{P\'eter S\'olymos}

\title{Processing Ecological Data in \proglang{R} with the \pkg{mefa} Package}
\Plaintitle{Processing Ecological Data in R with the mefa Package}
\Shorttitle{\pkg{mefa}: Processing Ecological Data in \proglang{R}}

\Abstract{
  \pkg{mefa} is an \proglang{R} package for multivariate data handling in
  ecology and biogeography. It provides 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 relational data tables for
  samples and taxa. An object of class \class{mefa} is a project specific compendium
  of the dataset and can be easily used in further analyses. Methods are provided
  for extraction, aggregation, conversion, plotting, summary and reporting of \class{mefa}
  objects. Reports can be generated in plain text or \LaTeX~format. This paper
  presents worked examples on a variety of ecological analyses.

  This vignette is based on the manuscript: P\'eter S\'olymos, 2009, Processing Ecological Data in R With the mefa
  Package. \emph{Journal of Statistical Software} 29(8), 1--28. \doi{10.18637/jss.v029.i08};
  processed with \pkg{mefa} \Sexpr{packageDescription("mefa", field="Version")} in \Sexpr{R.version.string} on \today.
}

\Keywords{biodiversity, biogeography, data manipulation, ecology, multivariate methods, \proglang{R}}
\Plainkeywords{biodiversity, biogeography, data manipulation, ecology, multivariate methods, R}

\Address{
  P\'eter S\'olymos\\
  Alberta Biodiversity Monitoring Institute\\
  and Boreal Avian Modelling project\\
  Department of Biological Sciences\\
  CW 405, Biological Sciences Bldg\\
  University of Alberta\\
  Edmonton, Alberta, T6G 2E9, Canada\\
  E-mail: \email{solymos@ualberta.ca}
}



\begin{document}


<<echo=FALSE, results=hide>>=
options(prompt = "R> ", continue = "+   ", useFancyQuotes = FALSE, width = 76)
@


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


Fortunately, many packages are available for the analysis of ecological data in \proglang{R} \citep{rcore-manual}, e.g., the \pkg{ade4} \citep{ade4-jss-07}, \pkg{labdsv} \citep{labdsv-manual} and \pkg{vegan} \citep{vegan-manual} packages among other more standard statistical packages e.g., \pkg{MASS} \citep{mass-book-02} and \pkg{stats} \citep{rcore-manual}. These, however, often require the multivariate data in the form of a matrix or data frame.

Extensive ecological data sets (with observations of multiple taxa at multiple locations) are not stored in crosstabulated format because most biodiversity data sets are sparse with matrix fill often lower than 30 percent. The conversion between data formats of biodiversity databases and ecological packages might require substantial work. Of course there are many possibilities for general data manipulation in \proglang{R} \citep{spector-manip-08}. The \pkg{Hmisc} \citep{hmisc-manual}, \pkg{reshape} \citep{reshape-manual}, \pkg{simba} \citep{simba-manual} and \pkg{labdsv} \citep{labdsv-manual} packages contain functions for converting ecological data in database formats into crosstabulated data matrices, and vice versa.

When the problems are more complex (e.g., a survey spanning across multiple spatial or temporal scales), results are stored in several related data tables. Most multivariate methods require a matrix, whereas response modeling usually require data frame as input. The simultaneous manipulation and checking of the community data matrix and related data frames can be time consuming with the standard tools.

The aim of the \pkg{mefa} \proglang{R} package is to provide standardized computational environment for specialist work in ecology and biogeography by bridging the gap between the data and the analysis, and reducing the time spent with data preprocessing. It provides object classes and methods for convenient manipulation of related data tables and can be used for generating reports in plain text or \LaTeX~format.

The package name \pkg{mefa} is a short for \emph{metafaunistics} indicating that data processing is a critical step prior to data analysis. The \emph{faunistics} part refers to the study of the fauna of some territory or area, while the \emph{meta} part refers to the procedures (data processing and analysis) beyond the data collection part of the scientific endeavor. Of course, the package intends to be more general than covering only faunistics. It can be useful when dealing with almost all kinds of organisms that can be counted or measured, including microorganisms, fungi and plants as well.

Compared to previous versions \citep[< 2.0;][]{mefa-comecol-08}, the package has been extensively rewritten to
enhance efficiency and speed, and with a focus on methods, but the data model remained the same. A stable
version of the package is available under the terms of the General Public License from the Comprehensive
\proglang{R} Archive Network (CRAN, \url{http://CRAN.R-project.org/package=mefa}), developmental version is
available at the \proglang{R}-Forge (\url{http://mefa.R-Forge.R-project.org/}).

In this paper I outline the motivation and the general idea behind the package, and I describe the structure of the object classes. A real-world data set is used to demonstrate the methods in the package and the use of objects in further data analysis.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Example dataset}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The ``Dolina 2007'' survey was aimed to discover the soil and litter dwelling macroinvertebrates (land snails, and terrestrial isopods) with special respect to microhabitat characteristics. We have surveyed dolines (sinkholes, karstic depressions) at the Als\'o-hegy plateau of the Aggtelek National Park, North Hungary, August, 2007. These dolines were mainly covered by hornbeam and beech, and were 0.5--2 hectares in extent. The dolines contained keystone habitat elements i.e., large pieces of coarse woody debris and different rock formations.

We collected invertebrates from four different microhabitats (\underline{L}itter, live \underline{W}ood,
\underline{D}ead wood as an equivalent for coarse woody debris, and \underline{R}ock\footnote{Underlined letters indicate the notation used for first characters of sample names. Second characters stand for sampling methods, and thirds are the replicate numbers. The first quadrat and timed samples from the rock microhabitat are \code{RQ1} and \code{RT1}, respectively.}) with at least three replicates per microhabitat per doline. We collected 1 L of litter per replicate (\code{"quadrat"} method for short) and employed a time restricted search (\code{"time"} method, five minutes per replicate) in a 1 m radius around the litter sample location. Litter samples were taken from the bottom of live trees, dead trees and rocks \citep{eureco-abstract, vilisics-08}.

Here I will use the data of land snails from the first dolina only, that is provided with the package (dataset \code{dol.count}). Samples are named after the microhabitat, the applied method and a number for replication. Snails were identified to species and categorized according to extent of shell decay. Four letter short names were used to refer to species. Live animals and fresh shells constituted the \code{"fresh"} group. Whitened, decayed and broken shells constituted the \code{"broken"} group. Shell decay stages formed the segments in the data set for further analyses.

A data frame containing microsite characteristics of the samples and the applied methods is provided in the dataset \code{dol.samp}. Characteristics (nomenclature, taxonomy, adult shell dimension) of the snail species are in the dataset \code{dol.taxa} and are based on \citep{kcj-83}. The full dataset along with the code showing how it was extracted from the full dataset is available on the Dataverse Network \citep{dolina-method-dataset}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Motivation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


Load the package and the example data set (showing only the first 16 rows out of 297)%
\footnote{The package demo (\code{demo(mefa, package = "mefa")}) and vignette (\code{vignette("mefa", package = "mefa")}) can help to go through the procedures presented in this paper.}:
%
<<>>=
library("mefa")
data("dol.count")
head(dol.count, 16)
@
%
This is a typical format for biodiversity datasets, where the \code{samp} column represents the observational units (samples). In planned ecological field experiments and surveys these units are expected to be comparable in terms of sampling effort. However, when data came from unplanned field observations, samples are often not comparable but refer to an observation, or set of individuals collected from a given location, by a given person in a given time.

The \code{taxa} column refers to the taxonomic identity of the individuals found in a given sample. The taxonomic resolution might vary due to expert knowledge and development stage of the individuals. When an actual sample did not contain individuals, it is convenient to refer to this situation by a pseudo-species (here, it is named as \code{"zero.pseudo"}) indicating that 0 individuals were found in the sample coded as \code{LT1} (first replicate from the litter microhabitat collected by timed search).

The \code{count} column contains the outcome of the field experiment, the number of individuals of a given taxa (i.e., a species) that were found in a given sample. It is zero when the sample contained no individuals. This notation is only necessary, if we are interested in zero samples (i.e., indication of very low abundances). Functions in the package accept non-integer values, too.

The \code{segm} column is used to distinguish segments (subpopulations) within individuals of the same species (nested into samples and species). Here we use \code{"fresh"} and \code{"broken"} segments to classify individuals based on shell decay. Other common examples for such segments are when distinguishing between males and females, different life stages or age classes. But it can also be used to identify subsets of the data, e.g., in case of a repeated measures experiment, when samples are nested within subsequent sampling period. As an example, data from museum collections can be used in this way to describe data accumulation trends through time \citep{solymos-feher-ibs-08}.

This format is ideal for the storage of the data but not adequate for data analysis. Prior to analysis, we have to crosstabulate the data to get a matrix filled with numeric values and with rows as samples and columns as taxa. Besides the functions \code{table} \citep[in package \pkg{base}, for factors;][]{rcore-manual}, there are some other functions in \proglang{R} to do this. For two-way crosstabulation of such data, there is the function \code{cast} in the \pkg{reshape} package \citep{reshape-manual}, the \code{mama} function in the \pkg{simba} package \citep{simba-manual} based on the \code{reshape} function, and the \code{matrify} function in the \pkg{labdsv} package \citep{labdsv-manual}.

Complications may arise, however, when we are dealing with three-way crosstabulation of the data \citep[see \code{xtabs} in package \pkg{stats}, with formula interface;][]{rcore-manual} and complex data structures, like the results of a hierarchical sampling design. We have to aggregate the samples into higher level units or the taxa into taxonomic or functional groups. And we might want to extract a subset of the crosstabulated data along with subsetted tables for samples and taxa at the same time. The way to do it with the \pkg{mefa} package is shown in the next sections.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Object classes}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The structure of the above data set with the four column is basically the prototype of an object of class
\class{stcs}. This is the primary format for database style data sets in the \pkg{mefa} package. The four letter
acronym comes from the first letters of the column names (\underline{s}amples, \underline{t}axa, \underline{c}ounts,
\underline{s}egments). To convert our example into an \class{stcs} object we do:
%
<<>>=
x1 <- stcs(dol.count)
str(x1)
unique(x1$count)
@
%
The object inherits from the data frame class, thus methods available for data frames apply for \class{stcs} objects as well. But there are four additional attributes. The \code{call} attribute is the function call. The \code{expand} attribute refers to the count column. If the count values are all ones (except for empty samples), then each row represent one individual, and the \code{expand} attribute is \code{TRUE}. We can achieve this by the \code{expand} argument in the function call:
%
<<>>=
x2 <- stcs(dol.count, expand = TRUE)
str(x2)
sum(x2$count)
unique(x2$count)
@
%
As an effect, the data frame is expanded and the count column contain 1 and 0 values. As we see, now the result contains 732 rows instead of 297. The 732 is the sum of the counts (one row for each count) plus one row for the empty sample. This expansion can be done with any data frame by the \code{inflate} function of the package. If values are non-integers, this cannot be applied.

The \code{zero.count} attribute refers to the presence or absence of empty samples in the data set. If empty samples are present, taxa and segment indices of the corresponding rows are set to the value stored in the \code{zero.pseudo} attribute. This can be set by the \code{zero.pseudo} argument in the function call. Count values of this pseudo species should be 0, the segment value is indifferent (but it can be set as the second element of a character vector supplied as the \code{zero.pseudo} argument).

Empty samples can be dropped by the \code{drop.zero = TRUE} argument (some multivariate methods, i.e., dissimilarity or diversity indices, are not defined for empty samples):
%
<<>>=
x3 <- stcs(dol.count, drop.zero = TRUE)
str(x3)
unique(x3$count)
@
%
Now the \code{zero.count} attribute is \code{FALSE} and the \code{zero.pseudo} attribute is \code{"not.defined"} as a result.

The number of columns in the input data frame may vary from two to four. If two columns are provided, it is assumed that the first column contains sample, while the second taxa names. If three columns are provided, the first two are treated as sample and taxa names, while the third is treated as count if numeric, and segment if character or factor. If four columns are provided, those are assumed to be in the samples, taxa, counts, segments order.

To crosstabulate the data of a \class{stcs} object, use:
%
<<>>=
m1 <- mefa(x1)
m1
m1$xtab["LT1", ]
@
%
The \code{mefa} function returns an object of class \class{mefa}. The print method for the \class{mefa} objects returns basic information on the dimensions of the data. The \code{$xtab} list element contains the crosstabulated data. The pseudo species has been removed, thus the row for sample \code{LT1} is empty. Row and column ordering follows the original internal coding of factors in the \class{stcs} object. The \code{$segm} is a list with length equal to the number of segments, and contains the matrices for each segment, with dimensions and names being the same as for \code{$xtab}:
%
<<>>=
str(m1$xtab)
str(m1$segm)
@

If segments represent e.g., successive sampling periods (years, decades) the use of the \code{nested = TRUE} argument can be convenient to inspect the data accumulation over time. In this case, values in subsequent segments are added up and segment names indicate this also:
%
<<>>=
mefa(x1, nested = TRUE)
@

If we do not want to use segments, use the \code{segment = FALSE} argument:
%
<<>>=
mefa(x1, segment = FALSE)
@

If the input object for the \code{mefa} function is a matrix or data frame, segments cannot be specified directly. Segments can, however, be defined indirectly through a \class{mefa}$\rightarrow$\class{stcs}$\rightarrow$\class{mefa} loop by the \code{melt} method (discussed in the examples later).

Besides the crosstabulated data, we also have a data frame for the samples. Here are the covariates for the 24 samples (microhabitat type and sampling method):
%
<<echo=TRUE, eval=FALSE>>=
data("dol.samp")
str(dol.samp)
@
%
<<echo=FALSE, eval=TRUE>>=
data("dol.samp")
str(dol.samp, strict.width = "cut")
@

And we also have a table containing variables related to the species (three factors, one numeric, note that \code{size} is based on average adult shell dimension and taken from the literature):
%
<<echo=TRUE, eval=FALSE>>=
data("dol.taxa")
str(dol.taxa)
@
%
<<echo=FALSE, eval=TRUE>>=
data("dol.taxa")
str(dol.taxa, strict.width = "cut")
@

These two tables, or either only one of them can easily be combined with the crosstabulation:
%
<<echo=TRUE, eval=FALSE>>=
mefa(x1, samp = dol.samp)
mefa(x1, taxa = dol.taxa)
m2 <- mefa(x1, samp = dol.samp, taxa = dol.taxa)
m2
str(m2$xtab)
str(m2$samp)
str(m2$taxa)
@
%
<<echo=FALSE, eval=TRUE>>=
mefa(x1, samp = dol.samp)
mefa(x1, taxa = dol.taxa)
m2 <- mefa(x1, samp = dol.samp, taxa = dol.taxa)
m2
str(m2$xtab)
str(m2$samp, strict.width = "cut")
str(m2$taxa, strict.width = "cut")
@

The tables are subsetted and ordered according to the row and column names in the crosstabulation. If names do not match, an error message is produced. This can be the case e.g., if the input object for the \code{mefa} function is a matrix without row or column names. It is not necessary to have names, only if tables for samples and taxa are provided.

In those cases, when the tables for samples and taxa do not contain rows for all the crosstabulated ones, the \code{xtab.fixed = FALSE} argument can be useful. This results in a \class{mefa} object containing samples and taxa that are common in the names (natural join based on intersect of dimnames):
%
<<echo=TRUE, eval=FALSE>>=
m2.sub <- mefa(x1, dol.samp[-c(1:5), ], dol.taxa[-c(1:80), ],
  xtab.fixed = FALSE)
m2.sub
str(m2.sub$xtab)
str(m2.sub$samp)
str(m2.sub$taxa)
@
%
<<echo=FALSE, eval=TRUE>>=
m2.sub <- mefa(x1, dol.samp[-c(1:5), ], dol.taxa[-c(1:80), ],
  xtab.fixed = FALSE)
m2.sub
str(m2.sub$xtab)
str(m2.sub$samp, strict.width = "cut")
str(m2.sub$taxa, strict.width = "cut")
@

As we see, the count data matrix is also subsetted, according to the related tables of samples and taxa.

An object of class \class{mefa} is a list of length five. The first element is the function call (\code{$call}), second is a matrix with the cross tabulated data (\code{$xtab}). These two are always present, the remaining three depend on the availability of data and the aims of the study. The third element contains a list of matrices for segments (\code{$segm}), the fourth and fifth contain data frames with data for samples (\code{$samp}) and taxa (\code{$taxa}), respectively. The general structure of an object of class \class{mefa} follows a relational data model, where dimnames attributes of the main count data matrix, the segment data matrices and the samples/taxa data tables for the rows and columns are identical. The print method for the \class{mefa} objects shows the names of these elements to help memorizing the notation. Figure~\ref{mefastr} depicting the object structure can be called as:
%
<<mefastr-raw, echo=TRUE, eval=FALSE>>=
mefalogo()
@
%
<<mefastr, fig=TRUE, include=FALSE, echo=FALSE>>=
opar <- par(mar = rep(0, 4))
<<mefastr-raw>>
par(opar)
@

\begin{figure}[t]
    \begin{center}
        \includegraphics[width=0.8\textwidth]{mefa-mefastr}
    \end{center}
    \caption{Representation of the relational data model in an object of class \class{mefa}.\label{mefastr}}
\end{figure}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section[S3 methods]{\proglang{S}3 methods}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%
\subsection{Summary and graphical display}
%%%%%%%%%%%%%


Dimensions and dimension names can be retrieved by the \code{dim} and \code{dimnames} methods:

<<>>=
dim(m2)
dimnames(m2)
@

To get a summary of the data, use the \code{summary} method:

<<>>=
summary(m2)
@

This returns basic characteristics of the data matrix. There are observations of 731 land snail individuals in the object and 26~\% of the matrix cells are non zero. There is also a list with segment levels, and summaries of the marginal tables derived from the count data matrix. Four vectors are based on marginal tables, the number of taxa (species) and individuals in the samples (\code{s.rich} and \code{s.abu}), and the number of occupied samples and individuals per species (\code{t.occ} and \code{t.abu}). The characteristics shown in the summary can be extracted according to their names:

<<>>=
names(summary(m2))
@

For example to return species richness values for the samples, or matrix fill, use:

<<>>=
summary(m2)$s.rich
summary(m2)$mfill
@

To get summaries for the linked data tables, use e.g., \code{summary(m2$samp)} or \code{summary(m2$taxa)}.

The first four characteristics of the samples and taxa can be plotted as barchart (\code{type = "bar"}; Figure~\ref{plot}A) or ranked in decreasing order (\code{type = "rank"}; Figure~\ref{plot}B) by the \code{plot} method. Values can be log transformed (\code{trafo = "log"}; Figure~\ref{plot}B) or normalized by their maxima (\code{trafo = "ratio"}). Here, only two cases are shown (when the second argument is \code{1} and \code{4}):

<<plot-raw, echo=TRUE, eval=FALSE>>=
plot(m2, 1, main = "A")
plot(m2, 4, type = "rank", trafo = "log", main = "B")
@

<<plot, echo=FALSE, fig=TRUE, include=FALSE, width=10, height=5>>=
opar <- par(mfrow = c(1, 2))
<<plot-raw>>
par(opar)
@

\begin{figure}[t]
    \includegraphics[width=1\textwidth]{mefa-plot}
    \caption{Plotting an object of class \class{mefa}: barcharts for species richness~(A),
      and ranked log abundances for species~(B).\label{plot}}
\end{figure}


The \code{boxplot} method is provided to retreive these statistics for each segment (Figure \ref{boxplot}). Again, only two cases are shown (when the second argument is \code{2} and \code{3} to complement the previous figure):

<<boxplot-raw, echo=TRUE, eval=FALSE>>=
boxplot(m2, 2, main = "A")
boxplot(m2, 3, main = "B")
@

<<boxplot, echo=FALSE, fig=TRUE, include=FALSE, width=10, height=5>>=
opar <- par(mfrow = c(1, 2))
<<boxplot-raw>>
par(opar)
@

\begin{figure}[t]
    \includegraphics[width=1\textwidth]{mefa-boxplot}
    \caption{Boxplots to depict differences among segments in abundances for samples~(A), frequency of
    occurrences for taxa~(B).\label{boxplot}}
\end{figure}

The \code{melt} method refers to the conversion of a \class{mefa} object into an \class{stcs} representation. The generic function is defined here, but can be found in the \pkg{reshape} package as well (transforming between wide and long formatted data), which also contains methods for data frames, arrays, matrices, tables and lists. The method for \class{mefa} objects is defined in the \pkg{mefa} package. Use the sampling method column in the samples table for segments (\code{m2$samp$method}), and make an object of class \class{stcs} as follows:

<<>>=
molten <- melt(m2, "method")
str(molten)
@

Then make an object of class \class{mefa} using the samples and taxa tables, because those have not changed, only the segments (instead of shell decay stage, now it refers to sampling methods, see segment names in the following example):

<<>>=
m3 <- mefa(molten, dol.samp, dol.taxa)
m3
@

This kind of melting--refreezing can be useful, if e.g., segments were not defined in the original \class{stcs} object, or the \class{mefa} object was based on a matrix or data frame (without segments). In this way, we can create segmented representations based on groups of samples (e.g., spatial units, repeated measures) or groups of taxa (e.g., taxonomic or functional groups) to more easily explore their differences.

Here we used melting--refreezing to explore the effects of sampling methods (note, originally shell decay stages were used as segments, and not sampling methods). We can visualize the relationship by the \code{image} method. This method creates a grid of colored rectangles with colors corresponding to the values in count data table. Segments can be specified as well. The rows and the columns are ordered according to their sums, being the top-left corner with the highest values. Transformations (log, order-scaled values based on quantiles, presence-absence) are also available to best represent the data in the plot. Figure~\ref{image} shows differences between the sampling methods compared to the main data matrix.

<<image-raw, echo=TRUE, eval=FALSE>>=
image(m3, trafo = "log", sub = "all segments", main="A")
for (i in 1:2) image(m3, segm = i, trafo = "log",
  sub = dimnames(m3)$segm[i], main = LETTERS[i + 1])
@

<<image, echo=FALSE, fig=TRUE, include=FALSE, height=3>>=
opar <- par(mfrow = c(1, 3))
<<image-raw>>
par(opar)
@

\begin{figure}[t]
    \includegraphics[width=1\textwidth]{mefa-image}
    \caption{Levelplot representation of an object of class \class{mefa}. Intensity of red coloring refers to
    increasing log abundances in the cells of the main data matrix~(A) and the segments for the time
    restricted search~(B), and the quadrat~(C) methods.\label{image}}
\end{figure}

Methods for objects of class \class{stcs} (\code{summary}, \code{plot}, \code{boxplot}, \code{image}) are also provided for convenience, but those merely use the crostabulated results to do the same job as the respective method for the \class{mefa} objects. Other methods for \class{stcs} objects rely on methods for data frames (e.g., \code{print}, \code{str}, \code{dim}, \code{dimnames}).

%%%%%%%%%%%%%
\subsection{Extraction and aggregation}
%%%%%%%%%%%%%


If we want to analyze only a subset of the data, the extraction of the \class{mefa} objects can be done via square brackets and by indexing the samples, taxa and segments to extract. Indexing can be numeric, or can refer to dimnames:

<<>>=
ex1 <- m2[1:20, 11:15, "fresh"]
dim(ex1)
dim(ex1$samp)
dim(ex1$taxa)
@

As a result, the count data and the samples/taxa tables were subsetted in the same step. If negative numeric
values are given, the respective parts of the object are omitted, e.g., the first element in the second
dimension can be excluded by \code{m2[, -1]}. Unused factor levels in the \code{$samp} and \code{$taxa} tables can be dropped by the argument \code{drop = TRUE}:

<<>>=
ex2 <- m2[m2$samp$method == "time"]
levels(ex2$samp$method)
ex3 <- m2[m2$samp$method == "time", drop = TRUE]
levels(ex3$samp$method)
@

The data set can be easily aggregated if we want to calculate statistics, e.g., species richness, on different levels of the sampling hierarchy \citep[like in additive diversity partitioning;][]{lande-96, crist-03}. Aggregation can be done by internal vectors, when the name of the variable refers to a column in the samples or taxa tables. If external vectors (that are not part of the \class{mefa} object) are used, the current implementation require a class attribute (e.g., \code{"factor"}) to be recognized as an external object. Now we create a factor with levels \code{"large"} and \code{"small"} for snail species with adult body size larger or equal to, or smaller than 5 millimeters, respectively\footnote{We treat semislugs with \code{NA} values as small sized species.}. Then, aggregate the object according to the internal \code{"microhab"} (microhabitat type) variable for samples and this external body size factor for taxa:

<<>>=
size.5 <- as.factor(is.na(m3$taxa$size) | m3$taxa$size < 5)
levels(size.5) <- c("large", "small")
m4 <- aggregate(m3, "microhab", size.5)
t(m4$xtab)
lapply(m4$segm, t)
@

From these results it is clear, that the proportion of size categories differs among sampling methods and microhabitats. We will further analyze this in the next chapters.

The methods provided for the object classes in the \pkg{mefa} package are reviewed in Table~\ref{methtab}.

\begin{table}[t]
\begin{center}
\begin{tabular}{llp{11.5cm}}
\hline
Class & Method & Description \\ 
\hline
\texttt{stcs} & \texttt{is.stcs}   & evaluates if an object is of class \class{stcs}. \\ 
            & \texttt{as.stcs}   & coerces to class \class{stcs}. \\ 
            & \texttt{summary}   & does the same as \texttt{summary} for \class{mefa} objects, just for convenience. \\ 
            & \texttt{plot}      & does the same as \texttt{plot} for \class{mefa} objects, just for convenience. \\ 
            & \texttt{boxplot}   & does the same as \texttt{boxplot} for \class{mefa} objects, just for convenience. \\ 
            & \texttt{image}     & does the same as \texttt{image} for \class{mefa} objects, just for convenience. \\ 
\texttt{mefa} & \texttt{is.mefa}   & evaluates if an object is of class \class{mefa}. \\ 
            & \texttt{as.mefa}   & coerces to class \class{mefa}. \\ 
            & \texttt{print}     & print basic characteristics of the object. \\ 
            & \texttt{summary}   & print basic summaries on the data. \\ 
            & \texttt{plot}      & graphical display of basic summaries of the data based on the main data matrix. \\ 
            & \texttt{boxplot}   & graphical display of basic summaries of the data based on data matrices for segments. \\ 
            & \texttt{image}     & graphical display of the values in the main data matrix or data matrix for a segment. \\ 
            & \texttt{aggregate} & aggregate (sum) the values in the matrices (main data and segments). \\ 
            & \texttt{[}         & extract an object (data matrices and relational data frames) based on indexing for rows (samples) columns (taxa) and segments.\\ 
            & \texttt{melt}      & convert an object of class \class{mefa} into an object of class \class{stcs}. \\ 
            & \texttt{report}    & writes data from an object of class \class{mefa} into a file. \\ 
            & \texttt{dim}       & return dimension of the \class{mefa} object. \\ 
            & \texttt{dimnames}  & return names for rows (samples) columns (taxa) and segments in the \class{mefa} object. \\
\hline
\end{tabular}
\caption{Description of methods provided for the object classes.\label{methtab}}
\end{center}
\end{table}

%%%%%%%%%%%%%
\subsection{Writing reports}
%%%%%%%%%%%%%


If the count data as the result of a field experiment are given, along with information about the sampling
locations, making a report is easy with the \code{report} method. This writes a text file into the specified
or the working directory. Contents of this text file can be further used e.g., by copy-pasting it into a word
processor. But it is more straightforward to use the \code{tex = TRUE} argument to write a formatted
\LaTeX~file and use the \LaTeX~function \code{input} to include the results into the main document. A sample
document on how to use the function in a \code{Sweave} document \citep{leisch-sweave} can be viewed by calling \code{mefadocs("SampleReport")}.

Now we write the dataset into a file after extracting the ten randomly selected species only, retaining all samples and both segments:

<<>>=
set.seed(1234)
m5 <- m2[ , sample(1:dim(m2)[2], 10)]
report(m5, "report.tex", tex = TRUE, segment = TRUE,
  taxa.name = 1, author.name = 2, drop.redundant = 1)
@

The meaning of the arguments used is: use the \code{m5} \class{mefa} object to write a report into the file \code{"report.tex"} by using \LaTeX~formatting. Use segments. Taxa names are in the first, author names are in the second column of the taxa table. We also want that implicitly all columns in the sample table should be used in the same order as before, to generate sample information (this can be specified by the \code{samp.var} argument not used here). Redundant levels of these sample information are dropped here (see help page \code{?report.mefa} for further details). The result is shown in Figure~\ref{minipg} with appropriate \LaTeX~formatting. The formatting rules can be modified via the \code{tex.control} argument.

\begin{figure}[!htb]
\begin{center}
\fbox{
\begin{minipage}{0.95\textwidth}
\begin{small}
<<show-report, echo=FALSE, results=tex>>=
writeLines(readLines("report.tex"))
invisible(file.remove("report.tex"))
@

\end{small}
\end{minipage}
}
\end{center}
\caption{Report generated from a \class{mefa} object by the \code{report} method.\label{minipg}}
\end{figure}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Data analysis}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%
\subsection{Single taxon response modeling}
%%%%%%%%%%%%%

Here we use the data of the land snail species \emph{Aegopinella minor} (\code{"amin"}) and the samples data table to investigate the effect of microhabitat and sampling method on the abundance of this species. The response is the \code{"amin"} column of the \code{m2$xtab} matrix, for the data argument of the Poisson GLM, we simply provide the \code{m2$samp} table:

<<>>=
mod.amin <- glm(m2$xtab[, "amin"] ~ ., data = m2$samp, family = poisson)
summary(mod.amin)
@

The model output indicates that the species was more frequent in dead wood and rock microhabitats than in live wood and litter, further, most of the individuals were collected by the quadrat method.

%%%%%%%%%%%%%
\subsection{Modeling the marginal sum as response}
%%%%%%%%%%%%%


The distribution of the number of snails in the samples is skewed and likely overdispersed, thus we use a negative binomial model to analyze the relationship between land snail abundances and sample covariates. The GLM for the negative binomial is implemented in the \pkg{MASS} package \citep{mass-book-02}. As part of the maximum likelihood fit, a shape parameter (\code{theta}) is also estimated in order to model the data as gamma mixture of Poisson distributions. We use the \code{summary} method to get the vector of the number of individuals, and the samples table again for covariates using their interaction as well:

<<>>=
library("MASS")
mod.abu <- glm.nb(summary(m2)$s.abu ~ .^2, data = m2$samp)
summary(mod.abu)
@

The abundance of snails in the samples was positively associated with dead wood and rock microhabitats. The interaction of sampling method and microhabitat has proved to be significant, indicating that the collecting efficiency of snails varied among microhabitats. The number of snails collected by the quadrat method was higher for the litter and live wood microhabitats, while in the dead wood microhabitat, the timed search resulted in more snails.

We can take advantage of the segments in the analysis as well. We now investigate, whether the proportion of fresh shells (including living animals) differ among microhabitats and sampling methods. First, we make a two-column matrix with the number of fresh shells per samples and the total number of shells (fresh and broken) collected per samples. Then, assuming that decay status (fresh or broken) of a single shell follows a Bernoulli process, we use this matrix in a binomial GLM (logistic regression) with the number of trials equal to the total number of individuals per sample:

<<>>=
prop.fr <- cbind(summary(m2[ , , "fresh"])$s.abu, summary(m2)$s.abu)
mod.fr <- glm(prop.fr ~ .^2, data = m2$samp, family = binomial)
summary(mod.fr)
@

It is clear that the proportion of fresh shells is not constant among microhabitats and sampling methods. The proportion was lowest in the rock microhabitats, although the quadrat method resulted more fresh shells from the rock microhabitats than the timed search method (due to the significant microhabitat $\times$ method interaction).


%%%%%%%%%%%%%
\subsection{Multivariate response modeling}
%%%%%%%%%%%%%


We employ a non-parametric multivariate analysis of variance to assess the effects of covariates on community composition. The method is implemented in the \code{adonis2} function \citep{mcardle-01, anderson-01} of the \pkg{vegan} package \citep{vegan-manual}. The method is based on a distance matrix calculated from the community data by the Bray--Curtis index of dissimilarity, by default. Thus, the input data matrix should not contain rows with zero sum. We have to remove those samples from the count data matrix and the samples table as well. This is most easily done by the \code{as.mefa} method with using the argument \code{drop.zero = TRUE}:

<<results=hide>>=
library("vegan")
@

<<>>=
m6 <- as.mefa(m2, drop.zero = TRUE)
m6.ado <- adonis2(m6$xtab ~ .^2, data = m6$samp, permutations = 100)
m6.ado
@

The results revealed that 18~\% of the total variation in community composition was due to sampling method (see also Figure~\ref{image}), and 24.6~\% was explained by microhabitats. Their interaction was also significant, explaining 15.4~\% of the total variation. But the unexplained variance remained relatively high (42~\%).

We can visualize this relationship by constrained (canonical) correspondence analysis (CCA). For this, use the \code{cca} function from the \pkg{vegan} package \citep{vegan-manual}. We base the analysis only on the matrix of the \code{"fresh"} segment (note that here we use it as data frame) and use the samples table for environmental constraints:

<<cca, fig=TRUE, include=FALSE>>=
m2.cca <- cca(m2$segm[["fresh"]] ~ ., data=m2$samp, 
    subset=rowSums(m2$segm[["fresh"]]) > 0)
plot(m2.cca)
@

\begin{figure}[t!]
    \includegraphics[width=\textwidth]{mefa-cca}
    \caption{Compound results of the constrained correspondence analysis based on a \class{mefa} object.\label{cca}}
\end{figure}

Most of the species tend to be associated with dead wood and rock microsites, and samples separate well according to sampling method (Figure~\ref{cca}).


%%%%%%%%%%%%%
\subsection{Analyzing multiple subsets}
%%%%%%%%%%%%%

The modular structure of the \class{mefa} objects enables easy processing of the data in loops. Now we use hierarchical cluster analysis based on multiple subsets of the data to assess the effects of shell decay stages and sampling methods on the community composition. We first make a list with four subsets of the Dolina dataset, referring to combinations of timed search and quadrat method, and fresh and broken shells. We also aggregate the samples over microhabitats:

<<>>=
m.list <- list()
n1 <- rep(c("time", "quadrat"), each = 2)
n2 <- rep(c("fresh", "broken"), 2)
n3 <- paste(n1, n2, sep=".")
for (i in 1:4) m.list[[n3[i]]] <-
  aggregate(m2[m2$samp$method == n1[i], , n2[i]], "microhab")
@

Then we do the clustering on each elements of the list object \code{m.list} using Euclidean distance and Ward's method:

<<clust-raw, echo=TRUE, eval=FALSE>>=
for (i in 1:4) {
  tmp <- hclust(dist(m.list[[i]]$xtab), "ward")
  plot(tmp, main = LETTERS[i], sub = names(m.list)[i], xlab = "")
}
@

<<clust, echo=FALSE, fig=TRUE, include=FALSE, height=7.5, width=7.5>>=
opar <- par(mfrow = c(2, 2))
<<clust-raw>>
par(opar)
@

\begin{figure}[t!]
    \includegraphics[width=1\textwidth]{mefa-clust}
    \caption{Hierarchical cluster analysis of multiple subsets of the Dolina dataset. Subsets are extracted to represent combinations of shell decay stages (A, C: fresh; B, D: broken) and sampling methods (A--B: timed search; C--D: quadrat method).\label{clust}}
\end{figure}

Figure~\ref{clust} shows that the dendrograms for the fresh and broken segments of the quadrat method are congruent, while that for the timed search are not. For the fresh shells, the dead wood communities resembled the rock community. While for the broken shells, dead wood communities were more similar to live wood and litter communities than to the rock.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Conclusions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The \pkg{mefa} package provides standardized environment and a and convenient tool for ecologists and biogeographers working on biodiversity data sets in \proglang{R}. The object classes (\class{stcs} and \class{mefa}) and \proglang{S}3 methods provide a coherent framework for data preprocessing of structured data sets. Based on \class{mefa} objects, reports can be generated in plain text or \LaTeX~format. It was presented how the objects can be directly used in further analyses for a variety of ecological problems.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Acknowledgments}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


Initial development of the \pkg{mefa} package was motivated by complex sampling designs of landscape scale invertebrate surveys, especially the ``Dolina 2007'' experiment. The author would like to thank to Zita Kemencei, Ferenc Vilisics, Elisabeth Hornung, Roland Farkas, Zolt\'an Elek and Zolt\'an Feh\'er for discussions and feedback, and providing data to test and improve the package. The helpful reviews of two anonymous referees and comments of the associate editor considerably improved the earlier version of the manuscript and the package itself. The work of the author was supported by a postdoctoral fellowship from the NSERC and the Alberta Biodiversity Monitoring Institute.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography{mefa}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\end{document}
