# Mark-Recapture Distance Sampling using R
### \textit{Practical 8, Intermediate Distance Sampling workshop, CREEM, 2018}

This version of the practical is for those who would like to conduct the analysis using the `mrds` package (Laake \textit{et al}. 2018) in R. There is a separate version describing how to conduct the analysis in Distance (Thomas \textit{et al}. 2010). 

The first part of the practical involves analysis of a survey of a known number of golf tees. This is intended mainly to familiarise you with the double-platform data structure and analysis features in R. The second part of the practical involves analysis of the pack-ice seal survey data of Borchers \textit{et al}. (2006) and Southwell \textit{et al}. (2007).

```{r pdfmakermrds, echo=FALSE}
pdf <- FALSE
```
# I. Golf tee survey

## Golf tee data

These data come from a survey of clusters of golf tees in grass, conducted by statistics students at the University of St Andrews. The data were collected along transect lines, 210 metres in total. A distance of 4 metres out from the centre line was searched and, for the purposes of this exercise, we assume that this comprised the total study area, which was divided into two strata. There were 250 clusters of tees in total and 760 individual tees in total. 

The population was independently surveyed by two observer teams. The following data were recorded for each detected group: perpendicular distance, cluster size, observer (team 1 or 2), 'sex' (males are yellow and females are green and golf tees occur in single-sex clusters) and 'exposure'. Exposure was a subjective judgment of whether the cluster was substantially obscured by grass (exposure=0) or not (exposure=1). The lengths of grass varied along the transect line and the grass was slightly more yellow along one part of the line compared to the rest. 

The golf tee dataset is provided as part of the `mrds` package (as well as in the Distance for Windows project called 'GolfteesExercise').

Open R and load the `mrds` package and golf tee dataset (called `book.tee.data`). The elements required for an MRDS analysis (i.e. observations, samples, region information) are contained within the object dataset. 

```{r preliminaries, message=FALSE, comment=NA, echo=TRUE}
# Load libraries
library(knitr)
library(mrds)

# Access the golf tee data
data(book.tee.data)

# Investigate the structure of the dataset
str(book.tee.data)

# Extract the list elements from the dataset into easy-to-access objects
detections <- book.tee.data$book.tee.dataframe
region <- book.tee.data$book.tee.region
samples <- book.tee.data$book.tee.samples
obs <- book.tee.data$book.tee.obs
```

Let's have a look at the columns in the detections data because it has a particular structure.

```{r headdet, echo=T}
# Check detections
head(detections)
```
Each detected object (in this case the object was a group or cluster of golf tees) is given a unique number in the `object` column. Notice that each `object` occurs twice - once for observer 1 and once for observer 2. The `detected` column indicates whether the object was seen (`detected=1`) or not seen (`detected=0`) by the observer. Perpendicular distance is in the `distance` column and cluster size is in the `size` column. 

To ensure that the variables `sex` and `exposure` are treated correctly, define them as factor variables.

```{r, echo=T}
# Define sex and exposure as factor variables 
detections$sex <- as.factor(detections$sex)
detections$exposure <- as.factor(detections$exposure)
```

## Golf tee survey analyses

### Estimation of \textit{p}(0): distance only

We'll start by analysing these data assuming that Observer 2 was generating trials for Observer 1 but not vice versa, i.e. trial configuration where Observer 1 is the primary and Observer 2 is the tracker. (The data could also be analysed in independent observer configuration - you are welcome to try this for yourself). We also assume full independence (i.e. detections between observers are independent at all distances): this requires only a MR model and to start with only perpendicular distance will be included as a covariate. (This is the "FI - MR dist" model in Distance for Windows project. Indeed, if you did fit that model in Distance, you can look in the Log tab at the R code Distance generated and compare it with the code we use here.)

Remember that `?` or `help` can be used to find out more about any of the functions used -- e.g., `?ddf` will tell you more about the ddf function. 

```{r, fit-nocovar, message=FALSE, comment=NA, fig.height=4, fig.cap="Goodness of fit (FI-trial) to golftee data."}
# Fit the FI-trial model
fi.mr.dist <- ddf(method='trial.fi', mrmodel=~glm(link='logit',formula=~distance),
                data=detections, meta.data=list(width=4))
# Create a set of tables summarizing the double observer data 
detection.tables <- det.tables(fi.mr.dist)
# Print these detection tables
detection.tables
```

The information in detection tables could also be plotted, but, in the interest of space, only one (out of six possible plots) is shown below. 

```{r dettabplot, echo=T, fig.height=3.5}
# Plot detection information, change number to see other plots
plot(detection.tables, which=1)
```
The plot numbers are:

1. Histograms of distances for detections by either, or both, observers. The shaded regions show the number for observer 1. 

2. Histograms of distances for detections by either, or both, observers. The shaded regions show the number for observer 2. 

3.	Histograms of distances for duplicates (detected by both observers).

4. Histogram of distances for detections by either, or both, observers. Not shown for trial configuration. 

5. Histograms of distances for observer 2. The shaded regions indicate the number of duplicates - for example, the shaded region is the number of clusters in each distance bin that were detected by Observer 1 given that they were also detected by Observer 2 (the "|" symbol in the plot legend means "given that"). 

6. Histograms of distances for observer 1. The shaded regions indicate the number of duplicates as for plot 5. Not shown for trial configuration. 

Note that if an independent observer configuration had been chosen, all plots would be available. 

A summary of the detection function model is available using the `summary` function. The Q-Q plot has the same interpretation as a Q-Q plot in a single platform analysis. 

```{r fi.summary, echo=T, fig.height=3.5}
# Produce a summary of the fitted detection function object
summary(fi.mr.dist)

# Produce goodness of fit statistics and a qq plot
gof.result <- ddf.gof(fi.mr.dist, 
                      main="Full independence, trial mode goodness of fit\nGolftee data")

# Extract chi-square statistics
chi.distance <- gof.result$chisquare$chi1$chisq
chi.markrecap <- gof.result$chisquare$chi2$chisq
chi.total <- gof.result$chisquare$pooled.chi
```

Abbreviated $\chi^2$ goodness of fit assessment shows the $\chi^2$ contribution from the distance sampling model to be `r round(chi.distance,1)` and the $\chi^2$ contribution from the mark-recapture model to be `r round(chi.markrecap,1)`.  The combination of these elements produces a total $\chi^2$ of `r round(chi.total$chisq,1)` with `r chi.total$df` degrees of freedom, resulting in a P-value of `r round(chi.total$p,3)`

The (two) detection functions can be plotted:

```{r plotdf, echo=T, fig.height=3.5}
# Divide the plot region
par(mfrow=c(1,2))
# Plot detection functions
plot(fi.mr.dist)
```

The plot headed "Observer=1 detections" shows a histogram of Observer 1 detections with the estimated Observer 1 detection function overlaid on it and adjusted for \textit{p}(0). The dots show the estimated detection probability for all Observer 1 detections.

The plot headed "Conditional detection probability" shows the proportion of Obs 2's detections that were detected by Obs 1 (also see the detection tables). The fitted line is the estimated detection probability function for Obs 1 (given detection by Obs 2) - this is the MR model. Dots are estimated detection probabilities for each Obs 1 detection.

Abundance is estimated using the `dht` function. 

```{r, abund-from-dist}
# Calculate density estimates using the dht function
tee.abund <- dht(model=fi.mr.dist, region.table=region, sample.table=samples, obs.table=obs)

# Print out results in a nice format
kable(tee.abund$individuals$summary, digits=2, 
      caption="Survey summary statistics for golftees")
kable(tee.abund$individuals$N, digits=2, 
      caption="Abundance estimates for golftee population with two strata")
```

### Estimation of \textit{p}(0): distance and other explanatory variables

How about including the other covariates, size, sex and exposure, in the MR model? Which MR model would you use? Don't spend too long on this - just try a couple of models. 

### Point independence

A less restrictive assumption is point independence, that the detections are only independent on the line i.e. at perpendicular distance zero. 

Let's start by seeing if a simple point independence model is better than a simple full independence one. This requires that a distance sampling (DS) model is specified as well a MR model. Here we try a half-normal key function for the DS model. 

```{r pit-nocovar, echo=T, fig.height=3.5}
# Fit the PI-trial model
pi.mr.dist <- ddf(method='trial', mrmodel=~glm(link='logit',formula=~distance),
                  dsmodel=~cds(key='hn'), data=detections,meta.data=list(width=4))

# Summary pf the model 
summary(pi.mr.dist)

# Produce goodness of fit statistics and a qq plot
gof.results <- ddf.gof(pi.mr.dist, main="Point independence, trial mode goodness of fit\nGolftee data")
```

Compare the results with the corresponding full independence model. Which has the lower AIC? Which has an estimate closer to known true abundance. 

To include covariates in the DS detection function, we need to specify an MCDS model as follows:

```{r pit-mod1, echo=T, fig.height=3.5}
# Fit the PI-trial model - DS sex and MR distance 
pi.mr.dist2 <- ddf(method='trial', mrmodel=~glm(link='logit',formula=~distance),
                   dsmodel=~mcds(key='hn',formula=~sex), data=detections,
                   meta.data=list(width=4))
```

Use the `summary` function to check the AIC and decide if you are going to include any additional covariates in the detection function. 

Now try a point independence model that has the preferred MR model from your full independence analyses. Which has the lower AIC and bias? 

# II. Crabeater seal survey

## Crabeater seal data 

This analysis is described in Borchers \textit{et al}. (2006) and Southwell \textit{et al}. (2007). These data come from a helicopter survey of crabeater seals conducted by the Australian Antarctic Division within the pack-ice seals programme. The helicopter could only operate within a relatively short distance from the ice-breaker ship which acted as its base. The ice-breaker could only go where the pack ice was thin enough and so the aerial transects could not be located at random. This means that design-based estimation was not a valid option and so, in the published analysis, abundance was estimated using density surface modelling. For the purposes of this exercise, we concentrate on detection function estimation and create an artificial region as a device to produce abundance estimates. 

There were four independent observers in the helicopter, two on each side (front and back). The front observers were considered to be one 'team' and the back observers were considered to be the other 'team'. Various environmental factors were recorded. In addition to perpendicular distance and cluster size, the following explanatory variables are available:

* side - the side of the helicopter from which seal were seen (L and R)
* exp - the experience (in survey hours) of the observer
* fatigue - the number of minutes the observer had been on duty on the current flight
*  gscat - group size category (1, 2 and greater than or equal to 3)
* vis - visibility category (Poor, Good and Excellent)
* glare - whether there was glare (Yes or No)
* ssmi - a measure of ice cover
* altitude - the height of the aircraft in metres
* obsname - unique identifier of observer

The data from the survey has been saved in a `.csv` file. This file is read into R using `read.csv`.

```{r, crabdat, comment=NA, echo=T, message=F}
library(Distance)
crabseal <- read.csv("crabbieMRDS.csv")

```

## Crabeater seal analyses

The observer teams acted independently and so an 'independent observer' configuration can be specified. To start with, we assume point independence and specify a half-normal key function for the DS model and include only perpendicular distance in the MR model.

```{r crabdet, echo=T}
#  Half normal detection function, 700m truncation distance, 
#      logit function for mark-recapture component
crab.ddf.io <- ddf(method="io", dsmodel=~cds(key="hn"),
                 mrmodel=~glm(link="logit", formula=~distance),
                 data=crabseal, meta.data=list(width=700))
summary(crab.ddf.io)
```

Make a note of the estimated values for $p(0)$ for each observer and the observers combined. 

Goodness of fit could be examined in the same manner as the golf tees by the use of `ddf.gof(crab.ddf.io)` but I have not shown this step.

Following model criticism and selection, estimation of abundance ensues. The estimates of abundance for the study area are arbitrary because inference of the study was restricted to the covered region. Hence the estimates of abundance here are artificial. For illustration, the `checkdata()` function produces the region, sample, and observation tables. From these tables, Horvitz-Thompson like estimators can be applied to produce estimates of $\hat{N}$. The use of `convert.units` adjusts the units of perpendicular distance measurement (m) to units of transect effort (km).  Be sure to perform the conversion correctly or your abundance estimates will be off by orders of magnitude.

```{r, crabsummary, echo=T}
# Create tables for estimating abundance 
# Selecting observer==1 ensures that observations in the obs.table are unique 
tables <- Distance:::checkdata(crabseal[crabseal$observer==1,])

# Estimate abundance in covered region
crab.ddf.io.abund <- dht(model=crab.ddf.io,
                         region=tables$region.table, 
                         sample=tables$sample.table, obs=tables$obs.table,
                         se=TRUE, options=list(convert.units=0.001))

# Pretty tables of data summary
kable(crab.ddf.io.abund$individuals$summary, digits=3,
      caption="Summary information from crabeater seal aerial survey.")
```

```{r, crabestimates}
# Pretty tables of estimates of individual abundance
kable(crab.ddf.io.abund$individual$N, digits=3,
      caption="Crabeater seal abundance estimates for study area of arbitrary size.")
```

### Crabeater seals with MCDS

We can also analyse the crabeater seals data as if it were single platform data (i.e. ignoring that $p(0)$ is less than 1).

Data identical to that available in the Distance project `CrabbieMCDSExercise.zip` has been ported to `crabbieMCDS.csv`, as if you had entered these data yourself into a spreadsheet.

This short exercise guides you through the import of these data into R and fits a simple half-normal detection function examining the possible improvement of the model by incorporating _side of plane_ and _visibility_ covariates.

```{r, message=FALSE, comment=NA}
# Load Distance for MCDS 
library(Distance)
# Read in data
crab.covariate <- read.csv("crabbieMCDS.csv")
# Check data imported OK
head(crab.covariate, n=3)
```

After checking that the data have been read into R appropriately, we are ready to fit a detection function.  

As before, _side of plane_ and _visibility_ are assigned characters and so we need to tell R to treat them as factors. 

```{r, comment=NA}
# Define factor variables
crab.covariate$side <- as.factor(crab.covariate$side)
crab.covariate$vis <- as.factor(crab.covariate$vis)
```

With two potential explanatory variables, there are a number of possible models. We start by fitting a detection function with _side of plane_ as a covariate using a half-normal key function. 

```{r, comment=NA}
# Fit HN key function with side of plane
ds.side <- ds(crab.covariate, key="hn", formula=~side, truncation=700)
```

We would now like to assess the fit of this function to our data. Two visual assessments are provided by the panels below: histogram and fitted function on the left and QQ plot on the right.

```{r, fig.cap="Histogram and fitted half-normal detection function on left.  Q-Q plot of detection function and data on right."}
# Divide plot region
par(mfrow = c(1, 2))
# Create a title for the plot
plot.title <- "Two sets of points\none for each 'side' of plane"
# Plot model
plot(ds.side, pch=19, cex=0.5, main=plot.title)
# Plot qq plot
gof.result <- ds.gof(ds.side, lwd = 2, lty = 1, pch = ".", cex = 0.5)
# Extract gof statistics
message <- paste("CVM GOF p-value=", round(gof.result$dsgof$CvM$p, 4))
# Add gof stats to plot
text(0.6, 0.2, message, cex=0.5)
```

The code below fits the model without any covariates. 

```{r, comment=NA}
# Fit HN key function with no covars
ds.nocov <- ds(crab.covariate, key="hn", formula=~1, truncation=700)
```

AIC score for model without covariates is `r options(scipen=9)` `r round(ds.nocov$ddf$criterion)` and AIC score for model with _side_ as a covariate is  `r round(ds.side$ddf$criterion)` so the model without _side_ as a covariate is preferred.  

We could also fit further detection functions and contrast the resulting models:

* with _visibility_ only
* with _side of plane_ and _visibility_ (excluding an interaction). 

Out of the four possible models which is to be preferred? 

We could go on to produce abundance estimates from our preferred model using the `dht` function if we had provided information about the size of the crabeater seal study area.

For these data would an MCDS analyses have been adequate? 

## References

Borchers DL, Laake JL, Southwell C and Paxton CGM (2006) Accommodating unmodeled heterogeneity in double-observer distance sampling surveys. Biometrics 62: 371-378

Laake JL, Borchers DL, Thomas L, Miller DL and Bishop JRB (2018) mrds: Mark-Recapture Distance Sampling. R package version 2.2.0. https://CRAN.R-project.org/package=mrds

Southwell C, Borchers DL, Paxton CGM, Burt ML and de la Mare W (2007) Estimation of detection probability in aerial surveys of Antarctic pack-ice seals. Journal of Agricultural, Biological and Environmental Statistics 12:41-54

Thomas L, Buckland ST, Rexstad EA, Laake JL, Strindberg S, Hedley SL, Bishop JRB, Marques TA, and Burnham KP (2010)  Distance software: design and analysis of distance sampling surveys for estimating population size. Journal of Applied Ecology 47: 5-14.  DOI: 10.1111/j.1365-2664.2009.01737.x