---
title: "Conne River 1991 Data"
author: "Carl James Schwarz"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    number_sections: yes
    md_extensions: [ 
      "-autolink_bare_uris" 
    ]
vignette: >
  %\VignetteIndexEntry{Conne River 1991 Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction
This analyzes a dataset from the Conne River, Newfoundland collected in 1991. Smolts are tagged and released at one location in the river.
A fence at a second station also captures fish. Data are stratified on a weekly level.

The Conne River 1992 vignette has larger sample sizes.

A stratified-Petersen estimator (Darroch, 1961; Plante et al. 1996) is found for the original data and some pooling of the rows/columns.

# Load the SPAS package
```{r libraries}
library(SPAS)
```
This will load the SPAS fitting functions and any associated packages needed by SPAS.

# Import the data.
The data  should be stored as an $s+1$ by $t+1$ (before pooling) matrix.
The $s \times t$ upper left matrix is the number of animals released in row stratum $i$ and recovered in
column stratum $j$. 
Row $s+1$ contains the total number of UNMARKED animals recovered in column stratum $j$.
Column $t+1$ contains the number of animals marked in each row stratum but not recovered in any column stratum.
The $rawdata[s+1, t+1]$ is not used and can be set to 0 or NA.
The sum of the entries in each of the first $s$ rows is then the number of animals marked in each row stratum.
The sum of the entries in each of the first $t$ columns is then the number of animals captured (marked and unmarked) in each column stratum.
The row/column names of the matrix may be set to identify the entries in the output.

Here is the raw data for the Conne River. Notice that very small number of releases and recoveries in week 6.

```{r loaddata}
conne.data.csv <- textConnection("
9  ,    21  ,     0  ,    0  ,    0  ,    0  ,   171
0  ,   101  ,    22  ,    1  ,    0  ,    0  ,   763
0  ,     0  ,   128  ,   49  ,    0  ,    0  ,   934
0  ,     0  ,     0  ,   48  ,   12  ,    0  ,   434
0  ,     0  ,     0  ,    0  ,    7  ,    0  ,    49
0  ,     0  ,     0  ,    0  ,    0  ,    0  ,     4
351,  2736  ,  3847  , 1818  ,  543  ,   191 ,     0")
conne.data <- as.matrix(read.csv(conne.data.csv, header=FALSE))
```
A total of `r sum(conne.data[1,])` fish were tagged and released in week 1. Of these fish, `r conne.data[1,1]` were recovered down stream in column stratum 1;
`r conne.data[1,2]` were recovered in column stratum 2; and `r conne.data[1,7]` were never seen again.
A total of `r conne.data[7,1]` UNMARKED fish were recovered in column stratum 1.

Notice the VERY small sample size in row 6 with only 4 fish released and non-recaptured. We will likely have to pool some rows in this problem because
there is virtually no information provided by row 6 which makes the problem ill conditioned and may not converge properly.

You can add row and column names to the matrix which will used when the data are printed.

# Fitting the Stratified-Petersen model
The Stratified-Petersen model can now be fit to the above data object. 
```{r fit1,results="hide"}
mod1 <- SPAS::SPAS.fit.model(conne.data,
                       model.id="No restrictions",
                       row.pool.in=1:6, col.pool.in=1:6)
```
The `row.pool.in` and `col.pool.in` inform the function on which rows or columns to physically pool before the analysis proceeds. 
Both parameters use a vector of codes (length $s$ for row pooing and length $t$ for column pooling) where rows/columns
are pooled that share the same value.

For example. `row.pool.in=c(1,2,3,4,5,6)` would imply that no rows are pooled, while
`row.pool.in=c('a','a','a','b','b','b')` would imply that the first three rows and last three rows are pooled.
The entries in the vector can be numeric or character; however, using character entries implies that the final
pooled matrix is displayed in the order of the character entries. I find that using entries such as `'123'` to represent
pooling rows 1, 2, and 3 to be easiest to use.

**The SPAS system only fits models were the number of rows after pooling is less than or equal to the number of columns after pooling.**

## Results from model 1 (no pooling).
The likelihood is rather flat, so don't be too concerned about messages from the optimization on failing to converge.
As long as the likelihood values seem to be have stabilized and estimates are sensible (i.e. capture rates not 0 or 1;
estimates of movement sensible results), the estimates should be fine.

The results of the model fit is a LARGE list. But the function `SPAS.print.model` produces a nice report
```{r mod1p}
SPAS.print.model(mod1)
```

The original data, the data after pooling, estimates and their standard errors are shown.
Here the stratified-Petersen estimate of the total number of smolts passing the at the first sampling station is
`r formatC(round(mod1$est$real$N), format='f', digits=0, big.mark=',')` with a standard error of 
`r formatC(round(mod1$se $real$N), format='f', digits=0, big.mark=',')`.


Each entry in the output is available in fitted model object. You will need to explore the
structure
```{r str1}
cat("Names of objects at highest level\n")
names(mod1)
cat("\n\nNames of estimates (both beta and real)\n")
names(mod1$est)
cat("\n\nNames of real estimates\n")
names(mod1$est$real)
```
The `N` entries refer to the  population size; the `N.stratum` entries refer to the individual stratum population sizes;
the `cap` entries refer to the estimated probability of capture in each row stratum;
the `exp.factor` entries refer to `(1-cap)/cap`, or the expansion factor for each row;
the `psi` entries refer to the number of animals tagged but never seen again (the right most column in the input data);
and the `theta` entries refer to the expected number of animals that were tagged in row stratum $i$ and recovered in column stratum $j$ (after pooling).

# Physically pooling some rows and columns
As noted by Darroch (1961), the stratified-Petersen will fail if the matrix of movements is close to singular. This often happens if two rows are proportional to each other. In this case, there is no unique MLE for the probability of capture in the last two rows, and they should be pooled.
A detailed discussion of pooling is found in Schwarz and Taylor (1998).

## Pooling the first two rows, the last two rows, and the last two columns
Let us now pool the first two rows and the last two rows, but leave rows 3 and 4 alone.
Similar, let us pool the last two columns.

The code is
```{r fit2,results="hide"}
mod2 <- SPAS.fit.model(conne.data, model.id="Pooling some rows",
                       row.pool.in=c("12","12","3","4","56","56"),
                       col.pool.in=c(1,2,3,4,56,56))
```

Notice how we specify the pooling for rows and columns and the choice of entries for the two corresponding vectors.
I used character entries for the row pooling to ensure that the pooled matrix is sorted properly (see below);
the numeric entries for the columns is ok as is.

The results of the model fit is
```{r mod2p}
SPAS.print.model(mod2)
```

Here the stratified-Petersen estimate of the total number of smolts passing the at the first sampling station is
`r formatC(round(mod2$est$real$N), format='f', digits=0, big.mark=',')` with a standard error of 
`r formatC(round(mod2$se$real$N), format='f', digits=0, big.mark=',')`.
which is a slight reduction
from the unpooled estimates.

## Physically pooling to a single row and complete pooling
You can pool to a single row (and multiple columns) or a single row and single column (which is equivalent to the pooled Petersen estimator).
The code and output follow:

```{r mod3,results='hide'}
mod3 <- SPAS.fit.model(conne.data, model.id="A single row",
                       row.pool.in=rep(1, nrow(conne.data)-1),
                       col.pool.in=c(1,2,3,4,56,56))
```
```{r mod3p}
SPAS.print.model(mod3)
```

```{r mod4,results='hide'}
mod4 <- SPAS.fit.model(conne.data, model.id="Pooled Peteren",
                       row.pool.in=rep(1, nrow(conne.data)-1),
                       col.pool.in=rep(1, ncol(conne.data)-1))
```
```{r mod4p}
SPAS.print.model(mod4)
```
Both models have an estimated abundance of
`r formatC(round(mod3$est$real$N), format='f', digits=0, big.mark=',')` with a standard error of 
`r formatC(round(mod3$se$real$N), format='f', digits=0, big.mark=',')`.
which is a slight reduction
from the unpooled estimates.

## Comparing different physical pooling
**Unfortunately, because pooling actually changes the data (internally), it is not possible to
do likelihood ratio testing or to use AICc to compare different poolings.**
Methods to compare different poolings is under
active investigation.

# Logical pooling
In logical pooling, we do not physically pool rows or columns. As noted elsewhere, it is not possible to implement logical pooling
for columns, so only row will be discussed here. In logical pooling, the capture probabilities in the stratum of release
are forced equal. Logical pooling is specified using the same keywords for physical pooling, but the additional argument
*row.physical.pooling=FALSE* should be set.


## Logical pooling the first two rows, the last two rows, and physical pooling of the  last two columns
Let us now logically pool the first two rows and the last two rows, but leave rows 3 and 4 alone.
Similar, let us physically pool the last two columns.

The code is
```{r fit5,results="hide"}
mod5 <- SPAS.fit.model(conne.data, model.id="Pooling some rows",
                       row.pool.in=c("12","12","3","4","56","56"),
                       row.physical.pool=FALSE,
                       col.pool.in=c(1,2,3,4,56,56))
```

This gives:
```{r }
SPAS.print.model(mod5)
```

# References
Darroch, J. N. (1961). The two-sample capture-recapture census when tagging and sampling are stratified. Biometrika, 48, 241–260.
https://www.jstor.org/stable/2332748

Plante, N., L.-P Rivest, and G. Tremblay. (1988). Stratified Capture-Recapture Estimation of the Size of a Closed Population. Biometrics 54, 47-60.
https://www.jstor.org/stable/2533994

Schwarz, C. J., & Taylor, C. G. (1998). The use of the stratified-Petersen estimator in fisheries management with an illustration of estimating the number of pink salmon (Oncorhynchus gorbuscha) that return to spawn in the Fraser River. Canadian Journal of Fisheries and Aquatic Sciences, 55, 281–296.
https://doi.org/10.1139/f97-238

