---
title: 'CJS Modeling in MRA'
author: "Trent McDonald"
date: "January 4, 2016"
output: pdf_document
vignette: >
 %\VignetteIndexEntry{mra_CJSModeling}
 %\VignetteEngine{knitr::rmarkdown}
 \usepackage[utf8]{inputenc}
---

This vignette repeats and embellishes examples in `help(F.cjs.estim)`. 

# Time-varying Models

The following demonstrates two methods for fitting a time-varying capture and survival model, the so-called "small t" model.  First, we attach the `mra` library and obtain access to the example dipper data. 

```{r}
library(mra)
data("dipper.histories")
dim(dipper.histories)
head(dipper.histories)
```

## Method 1: Using factors
The following code constructs a factor variable containing one level for each capture occasion.  The attribute of this factor tells `mra` the "other"" dimension of the problem.  Internally, `mra` will use this attribute to replicate the factor into matrices that are the appropriate size. 

```{r}
ct <- as.factor( paste("T",1:ncol(dipper.histories), sep=""))
attr(ct,"nan")<-nrow(dipper.histories)
ct
```

Next, call `F.cjs.estim` and specify that `ct` is a time-varying vector covariate using the `tvar` function.  When the vector given to `tvar` is a factor, there are additional options which allow the user to drop certain levels of the factor.  This is useful when coefficients for some levels are not estimable, as in the case of a completely time-varying CJS model.  Here, there are 7 levels in factor `ct`, but only 6 capture and survival parameters are defined (recall, 1st capture parameter is not estimable, and 7th survival parameter between occasions 7 and 8 does not exist). Consequently, we tell `tvar` to drop the first two levels of `ct` from the capture model.  We drop the level 1st because only 6 parameters exist.  We drop the 2nd to break the colinearity of levels and define $p_2$ as the reference level. In the survival model, we drop the first, sixth, and seventh levels of `ct`.  The first level is dropped to break the colinearity of levels and define $\phi_1$ as the reference level.  We drop level 6 because the last survival and capture parameters are confounded in CJS models.  We drop the 7th level because there are only 6 survival parameters.  The call the `F.cjs.estim` is:

```{r}
dipper1.cjs <- F.cjs.estim( ~tvar(ct,drop=c(1,2)), ~tvar(ct,drop=c(1,6,7)), dipper.histories )
dipper1.cjs
```


## Method 2: Using explicit 2-D matricies

While using factors (*Method 1* above) produces the most economical code, it does not adequately illuminate the covariate matrices which are at the heart of CJS modeling.  To illustrate covariates as explicit matricies, this method constructs one 2-D matrix for each paramter, then estimates the same model as *Method 1*. 

First, we construct 6 matricies containing 1's in a single column only.  In *Method 1*, this construction was performed behind-the-scenes by `tvar`. Note that only 6 matricies are required due to the number of parameters, breaking of colinearity, and confounding of CJS paramters mentioned above. 

```{r}
x2 <- matrix(c(0,1,0,0,0,0,0), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
x3 <- matrix(c(0,0,1,0,0,0,0), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
x4 <- matrix(c(0,0,0,1,0,0,0), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
x5 <- matrix(c(0,0,0,0,1,0,0), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
x6 <- matrix(c(0,0,0,0,0,1,0), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
x7 <- matrix(c(0,0,0,0,0,0,1), nrow(dipper.histories), ncol(dipper.histories), byrow=TRUE)
```

Each of the above matrices have a column of 1's corresponding to the effect they estimate. The first six rows of `x3` and `x4` are:

```{r}
head(x3)
head(x4)
```

We now call `F.cjs.extim` without aid of `tvar` by explicitely specifying the matricies in each model.  Note that `x2` is not included in the capture model, and that  `x6` and `x7` are not included in the survival model.

```{r}
dipper2.cjs <- F.cjs.estim( ~x3+x4+x5+x6+x7, ~x2+x3+x4+x5, dipper.histories )
dipper2.cjs
```
Note that parameter estimates produced by *Method 1* and *Method 2* are identical. 

## Plot: $\hat{N}_j$ estimates


Following is a plot of the Horvitz-Thomson population size estimates. 


```{r}
plot(dipper1.cjs)
```


## Plot: $\hat{\phi}_j$ estimates


Following is a plot of survival estimates containing one line per individual. 


```{r}
plot(dipper1.cjs,type="s",ci=FALSE)
```