```{r include=FALSE}
knitr::opts_chunk$set(eval=TRUE, echo=TRUE, message=FALSE, warnings=FALSE)
```

In this exercise, we use `R` [@r_core_team_r_2019] and the `Distance` package [@miller_distance_2019] to fit different detection function models to point transect survey data of savanna sparrows *(Passerculus sandwichensis)* density and abundance.  These data were part of a study examining the effect of livestock grazing upon vegetation structure and consequently upon the avian community described by Knopf et al. [-@knopf_guild_1988].  This dataset was also used to demonstrate [point transect analysis](https://examples.distancesampling.org/Distance-points/pointtransects-distill.html)

# Objectives

- Fit a detection function pooling data across pastures,
- Fit pasture-specific detection functions,
- Choose most appropriate analysis using model selection.

# Survey design

A total of 373 point transects were placed in three pastures in the Arapaho National Wildlife Refuge in Colorado (Figure \@ref(fig:fig)).  Elevation of these pastures was ~2500m.  In this example, we **will** perform pasture-level analysis of these data.

```{r fig, echo=FALSE, fig.cap="Summer grazed pastures along Illinois River Arapaho National Wildlife Refuge, Colorado.\nFigure from [@knopf_guild_1988]."}
knitr::include_graphics("arapaho.jpg")
```


The fields of the `Savannah_sparrow_1980` data set are:

+ Region.Label - three pastures that constituted sections of the study area.  
+ Area - size of the study region. A place holder, because pasture sizes are not known.  Estimates of density and abundance will be equivalent. 
+ Sample.Label - point transect identifier (total of 273)
+ Effort - number of visits to each point
+ object - unique identifier for each detected savanna sparrow
+ distance - radial distance (metres) to each detection
+ Study.Area - only data for savanna sparrow (SASP) are included in this data set

# Make the data available for R session

This command assumes that the `dsdata` package has been installed on your computer. The R workspace `Savannah_sparrow_1980` contains detections of savanna sparrows from point transect surveys of Knopf et al. [-@knopf_guild_1988].

```{r}
library(Distance)
data(Savannah_sparrow_1980)
conversion.factor <- convert_units("meter", NULL, "hectare")
```


# Separate data into pasture-specific data sets

The simplest way to fit pasture-specific detection functions is to subset the data.  This could be done at the time the `ds()` function is called, but we perform the step here as a data preparation step.

```{r}
sasp.past1 <- subset(Savannah_sparrow_1980, Region.Label == "PASTURE 1")
sasp.past2 <- subset(Savannah_sparrow_1980, Region.Label == "PASTURE 2")
sasp.past3 <- subset(Savannah_sparrow_1980, Region.Label == "PASTURE 3")
```

# Pasture (stratum)-specific detection functions

Fit half-normal  key functions without adjustments to each pasture separately after performing 5\% right truncation.

```{r}
past1.hn <- ds(data=sasp.past1, key="hn", adjustment=NULL,
              transect="point", convert_units=conversion.factor, truncation="5%")
past2.hn <- ds(data=sasp.past2, key="hn", adjustment=NULL,
              transect="point", convert_units=conversion.factor, truncation="5%")
past3.hn <- ds(data=sasp.past3, key="hn", adjustment=NULL,
              transect="point", convert_units=conversion.factor, truncation="5%")
```

The total AIC for the model that fits separate detection functions to each pasture is the sum of the AICs for the individual pastures.

```{r}
model.separate.AIC <- sum(AIC(past1.hn, past2.hn, past3.hn)$AIC) 
```

#  Common detection function across pastures

This model is much simpler to fit because there is only a single call to `ds()` using the original data.

```{r}
model.pooled <- ds(data=Savannah_sparrow_1980, key="hn", adjustment=NULL,
                   transect="point", convert_units = conversion.factor, truncation = "5%")
model.pooled.AIC <- AIC(model.pooled)
```

# Comparison of AIC scores

```{r}
cat(paste("Stratum-specific detection AIC", round(model.separate.AIC),
      "\nCommon detection function AIC", round(model.pooled.AIC$AIC)), sep=" ")
```

Because the AIC for model with stratum-specific detection functions (`r round(model.separate.AIC)`) is less than AIC for model with pooled detection function (`r round(model.pooled.AIC$AIC)`), we base our inference upon the stratum-specific detection function model (depicted in Figure \@ref(fig:threeplot)).

```{r, threeplot, layout="l-body-outset", fig.cap="Pasture-specific detection functions based upon half-normal key function."}
cutpoints <- c(0,5,10,15,20,30,40,53)
par(mfrow=c(1,3))
plot(past1.hn, breaks=cutpoints, pdf=TRUE, main="Pasture 1")
plot(past2.hn, breaks=cutpoints, pdf=TRUE, main="Pasture 2")
plot(past3.hn, breaks=cutpoints, pdf=TRUE, main="Pasture 3")
```


## Absolute goodness of fit

Always best to check the fit of the preferred model to the data.

```{r, results='hold'}
gof_ds(past1.hn, plot = FALSE)
gof_ds(past2.hn, plot = FALSE)
gof_ds(past3.hn, plot = FALSE)
```

Further exploration of analyses involving stratification can be found in the [example of dung survey analysis](https://examples.distancesampling.org/Distance-mult/multipliers-distill.html).

# Comments

Note there is a difference of `r round(model.pooled.AIC$AIC - model.separate.AIC)` AIC units between the model using stratum-specific detection functions and the model using a pooled detection function, with the stratum-specific detection function model being preferrable.  To be thorough, absolute goodness of fit for the three stratum-specific detection functions is checked, and all models fit the data adequately.

This vignette focuses upon use of stratum-specific detection functions as a model selection exercise.  Consequently, the vignette does not examine stratum-specific abundance or density estimates.  That output is not included in this example analysis, but can easily be produced by continuing the analysis begun in this example.

