<<echo=false>>=
options(width=70)
options(continue=" ")
@

\documentclass[a4paper]{article}
\usepackage[OT1]{fontenc}
\usepackage{Sweave}
\usepackage{natbib}
\usepackage{fullpage}
\bibliographystyle{plain}

\DefineVerbatimEnvironment{Sinput}{Verbatim} {xleftmargin=2em}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{xleftmargin=2em}
\DefineVerbatimEnvironment{Scode}{Verbatim}{xleftmargin=2em}
\fvset{listparameters={\setlength{\topsep}{0pt}}}
\renewenvironment{Schunk}{\vspace{\topsep}}{\vspace{\topsep}}

%%\VignetteIndexEntry{Overview of unmarked}

\title{Overview of Unmarked:\\
An R Package for the Analysis of Data from Unmarked Animals}
\author{Ian Fiske and Richard Chandler}


\begin{document}

\maketitle

\abstract{Unmarked aims to be a complete environment for the
  statistical analysis of data from surveys of unmarked
  animals. Currently, the focus is on hierarchical models that
  separately model a latent state (or states) and an observation
  process. This vignette provides a brief overview of the package ---
  for a more thorough treatment see \citep{fiskeChandler_2011}
}


\section{Overview of unmarked}

Unmarked provides methods to estimate site occupancy, abundance, and
density of animals (or possibly other organisms/objects) that cannot be
detected with certainty. Numerous models are available that correspond
to specialized survey methods such as temporally replicated surveys,
distance sampling, removal sampling, and double observer
sampling. These data are often associated with metadata related to the
design of the study. For example, in distance sampling, the study
design (line- or point-transect), distance class break points,
transect lengths, and units of measurement need to be accounted for in
the analysis. Unmarked uses S4 classes to store data and metadata in a
way that allows for easy data manipulation, summarization, and model
specification. Table 1 lists the currently implemented models and
their associated fitting functions and data classes.

\begin{table}[!h] %%\footnotesize
\centering
\begin{tabular}{cccc}
\hline
Model & Fitting Function & Data & Citation \\ \hline
Occupancy & occu & unmarkedFrameOccu & \citep{mackenzie_estimating_2002} \\
Royle-Nichols & occuRN & unmarkedFrameOccu & \citep{royle_estimating_2003} \\
Point Count & pcount & unmarkedFramePCount & \citep{royle_n-mixture_2004} \\
Distance-sampling & distsamp & unmarkedFrameDS & \citep{royle_modeling_2004} \\
Generalized distance-sampling & gdistsamp & unmarkedFrameGDS & \citep{chandlerEA_2011} \\
Arbitrary multinomial-Poisson & multinomPois & unmarkedFrameMPois & \citep{royle_generalized_2004} \\
Colonization-extinction & colext & unmarkedMultFrame & \citep{mackenzie_estimating_2003} \\
Generalized multinomial-mixture & gmultmix & unmarkedFrameGMM & \citep{royle_generalized_2004} \\
\hline
\end{tabular}
\caption{Models handled by unmarked.}
\label{tab:models}
\end{table}

Each data class can be created with a call to the constructor function
of the same name as described in the examples below.

%%\newpage

\section{Typical unmarked session}

The first step is to import the data into R, which we do below using
the \textbf{read.csv} function. Next, the data need to be formatted for
use with a specific model fitting function. This can be accomplished
with a call to the appropriate type of \textbf{unmarkedFrame}. For
example, to prepare the data for a single-season site-occupancy
analysis, the function \textbf{unmarkedFrameOccu} is used.

<<>>=
library(unmarked)
wt <- read.csv(system.file("csv","widewt.csv", package="unmarked"))
y <- wt[,2:4]
siteCovs <-  wt[,c("elev", "forest", "length")]
obsCovs <- list(date=wt[,c("date.1", "date.2", "date.3")],
    ivel=wt[,c("ivel.1",  "ivel.2", "ivel.3")])
wt <- unmarkedFrameOccu(y = y, siteCovs = siteCovs, obsCovs = obsCovs)
summary(wt)
@

Alternatively, the convenience function \textbf{csvToUMF} can be used

<<>>=
wt <- csvToUMF(system.file("csv","widewt.csv", package="unmarked"), long = FALSE, type = "unmarkedFrameOccu")
@

If not all sites have the same numbers of observations, then manual
importation of data in long format can be tricky.  \textbf{csvToUMF}
seamlessly handles this situation.

<<>>=
pcru <- csvToUMF(system.file("csv","frog2001pcru.csv", package="unmarked"), long = TRUE, type = "unmarkedFrameOccu")
@

To help stabilize the numerical optimization algorithm, we recommend
standardizing the covariates.

<<>>=
obsCovs(pcru) <- scale(obsCovs(pcru))
@


Occupancy models can then be fit with the occu() function:

<<>>=
fm1 <- occu(~1 ~1, pcru)
fm2 <- occu(~ MinAfterSunset + Temperature ~ 1, pcru)
fm2
@

Here, we have specified that the detection process is modeled with the
MinAfterSunset and Temperature covariates.  No covariates are
specified for occupancy here.  See ?occu for more details.

Unmarked fitting functions return unmarkedFit objects which can be
queried to investigate the model fit.  Variables can be
back-transformed to the unconstrained scale using backTransform.
Standard errors are computed using the delta method.

<<>>=
backTransform(fm2, 'state')
@

Because the detection component was modeled with covariates, covariate
coefficients must be specified to back-transform.  Here, we request
the probability of detection given a site is occupied and all
covariates are set to 0.

<<>>=
backTransform(linearComb(fm2, coefficients = c(1,0,0), type = 'det'))
@

A predict method also exists.

<<>>=
newData <- data.frame(MinAfterSunset = 0, Temperature = -2:2)
round(predict(fm2, type = 'det', newdata = newData, appendData=TRUE), 2)
@


Confidence intervals are requested with confint, using either the
asymptotic normal approximation or profiling.


<<>>=
confint(fm2, type='det')
confint(fm2, type='det', method = "profile")
@

Model selection and multi-model inference can be implemented after
organizing models using the fitList function.

<<>>=
fms <- fitList('psi(.)p(.)' = fm1, 'psi(.)p(Time+Temp)' = fm2)
modSel(fms)
predict(fms, type='det', newdata = newData)
@


The parametric bootstrap can be used to check the adequacy of model fit.
Here we use a $\chi^2$ statistic appropriate for binary data.

<<>>=
chisq <- function(fm) {
    umf <- getData(fm)
    y <- getY(umf)
    y[y>1] <- 1
    sr <- fm@sitesRemoved
    if(length(sr)>0)
        y <- y[-sr,,drop=FALSE]
    fv <- fitted(fm, na.rm=TRUE)
    y[is.na(fv)] <- NA
    sum((y-fv)^2/(fv*(1-fv)), na.rm=TRUE)
    }

(pb <- parboot(fm2, statistic=chisq, nsim=100))
@

We fail to reject the null hypothesis, and conclude that the model fit
is adequate.

\bibliography{unmarked}

\end{document}
