\documentclass[11pt]{article}
\usepackage[top=2cm, bottom=3cm, left=2cm, right=2cm]{geometry} % Page margins
\usepackage[utf8]{inputenc}
\usepackage{amsmath}            % /eqref
\usepackage[authoryear,round]{natbib}
\usepackage{booktabs}           % Some macros to improve tables
\usepackage{url}
\usepackage[none]{hyphenat}     % No hyphens

%\VignetteIndexEntry{A quick introduction to Cheddar}
%\VignetteKeyword{food web}
%\VignetteKeyword{body mass}
%\VignetteKeyword{numerical abundance}
%\VignetteKeyword{community}
%\VignetteKeyword{allometry}

\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\R}{\textsf{R} }

\begin{document}

\sloppy    % Prevent hyphenated words running into margins

\title{Cheddar quick start 
       (\Sexpr{packageDescription('cheddar', fields='Version')})}
\author{Lawrence Hudson}
\date{\Sexpr{packageDescription('cheddar', fields='Date')}}
\maketitle

\tableofcontents

<<echo=FALSE>>=
library(cheddar)

# Makes copy-paste much less painful
options(continue=' ')
options(width=90)
options(prompt='> ')

options(SweaveHooks = list(fig=function() par(mgp=c(2.5,1,0), 
                                              mar=c(4,4,2,1),
                                              oma=c(0,0,1,0),
                                              cex.main=0.8)))
@

\SweaveOpts{width=6,height=6}
\setkeys{Gin}{width=0.5\textwidth}

\section{Introduction}
The Cheddar \R package provides a flexible, extendable representation of an 
ecological community and a range of functions for analysis and visualisation, 
focusing on food web, body mass and numerical abundance data. It also allows 
inter-web comparisons such as examining changes in community structure over 
environmental, temporal or spatial gradients. This vignette is a brief 
introduction to some different areas of Cheddar. Each area is discussed in 
detail in its own vignette, listed in Section \ref{sec:further_reading}.

\section{Community basics}
The examples below use the pelagic epilimnion community of Tuesday Lake, 
Michigan, USA sampled in 1984 \citep{CarpenterAndKitchell1996, 
CohenEtAl2003PNAS, JonssonEtAl2005AER}, available in Cheddar as the 
\code{TL84} dataset. 
<<>>=
data(TL84)      # Load the dataset
print(TL84)     # A description of the data
NumberOfNodes(TL84)
NumberOfTrophicLinks(TL84)
@
\code{NPS} assembles node properties in to an \R \code{data.frame}. Let's look 
at the first 10 rows of such a table.
<<>>=
head(NPS(TL84, c('category', 
                 'Log10MNBiomass', 
                 TS='TrophicSpecies', 
                 TL='PreyAveragedTrophicLevel')), 10)
@

\section{Community plots}
\code{NPS} has a corresponding plot function \code{PlotNPS}, which plots one 
node property against another. \code{PlotNPS} takes the names of node 
properties to plot on the x and y axes. Just as with \code{NPS}, node 
properties can be either `first-class' or computed. The example below plots 
$\log_{10}$-transformed numerical abundance against 
$\log_{10}$-transformed body mass.
\begin{center}
<<fig=TRUE>>=
PlotNPS(TL84, 'Log10M', 'Log10N')
@
\end{center}
Producers are shown by green circles, invertebrates by blue squares and 
vertebrate ectotherms by purple diamonds, cannibals shown by lighter-coloured 
circles and trophic links shown by grey lines. 
The \code{NvMLinearRegressions} and \code{PlotLinearModels} functions can be 
used to add regression lines through each of the three categories.
\begin{center}
<<fig=TRUE>>=
PlotNvM(TL84)
models <- NvMLinearRegressions(TL84)
colours <- PlotLinearModels(models)
legend("topright", sapply(models, FormatLM), lty=1, col=colours)
@
\end{center}
The following example shows trophic level against $\log_{10}$-transformed body 
mass.
\begin{center}
<<fig=TRUE>>=
PlotNPS(TL84, 'Log10M', 'PreyAveragedTrophicLevel')
@
\end{center}
Similarly, \code{PlotTLPS} plots one trophic-link property against another. 
Names prefixed with either `resource.' or `consumer.' are taken to be node 
properties. The following example therefore plots the $\log_{10}$-transformed 
body mass of the consumer against that of the resource for every trophic link 
in the community.
\begin{center}
<<fig=TRUE>>=
PlotTLPS(TL84, 'resource.Log10M', 'consumer.Log10M')
@
\end{center}
Colours in this plot are the same as in the \code{PlotNPS} examples and denote 
the resource's category. The example below shows the food web as a 
predation matrix: a binary matrix with species shown in node order, starting at 
the top-left. Points on the dashed line indicate cannibals. 
\begin{center}
<<fig=TRUE>>=
PlotPredationMatrix(TL84)
@
\end{center}

\section{Collections of communities}
Cheddar's \code{pHWebs} dataset contains ten of the 20 webs sampled across a 
wide pH gradient by \cite{LayerEtAl2010AER}. This example assembles a table 
of properties for this collection.

<<>>=
data(pHWebs)
CollectionCPS(pHWebs, 
              c('lat', 
                'long',
                'pH', 
                S='NumberOfNodes', 
                L='NumberOfTrophicLinks', 
                'L/S'='LinkageDensity',  
                C='DirectedConnectance', 
                Slope='NvMSlope', 
                B='FractionBasalNodes', 
                I='FractionIntermediateNodes', 
                T='FractionTopLevelNodes'))
@

\section{Further reading}
\label{sec:further_reading}
You should read the `Community' vignette. Plotting and anlysis of communities 
is covered in the `PlotsAndStats' vignette. The `ImportExport' vignette shows 
how to get your community data in to and out of Cheddar. If you have data from 
several communities and are interested in seeing how community structure changes 
among them, read the `Collections' vignette.

\bibliographystyle{plainnat}
\bibliography{cheddar} 

\end{document}