---
title: "Review new data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Review new data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup,echo=FALSE,message=FALSE,warning=FALSE}
library(mort)
library(ggplot2)
```
morts is a conservative framework to flag potential mortalities. This means that it can overestimate potential mortalities and some flagged mortalities may actually be alive. If new data are available - such as from receivers that were not previously available or an additional year in multiyear studies - movement of incorrectly flagged mortalities may be apparent.

In the example below, the data used to flag potential mortalities is to the left of the dashed line, and the new data are to the right of the dashed line. There is no station change evident for Fish G in the new data, so this fish is still considered a mortality. There is, however, a station change for Fish F, indicating this fish is still alive. 

```{r alive_ex,echo=FALSE,results=FALSE,fig.width=7}
new.events<-rbind(events,new.data)
morts<-morts(data=events,type="mort",ID="ID",station="Station.Name",
             method="all")
plot<-mortsplot(data=new.events,type="mort",ID="ID",station="Station.Name",
                morts=morts)
plot<-plot+
  geom_vline(aes(xintercept=as.POSIXct("2006-10-25")),linetype="dashed")+
  theme(legend.position="none")
plot
```

The `review()` function examines new data to determine if any animals move that were previously flagged as potential mortalities.

## Using `review()` 

Two input dataframes are mandatory for `review()`: 

#. `new.data` - a dataframe with residence events generated from the new dataset

#. `morts` - a dataframe of previously flagged mortalities

The new residence events in `new.data` must be generated using the same method as the original dataset, or must be manipulated to match the format of the original dataset. The format of `new.data` must also match the format of `morts`. 

The other four required arguments, `type`, `ID`, `station`, and `res.start`, are specified in the same way as for `morts()` and `infrequent()`. See the [Identifying potential mortalities](https://rosieluain.github.io/mort/articles/a2_morts.html) vignette for more information about these arguments. 

```{r rev_ex,results=FALSE}
review_example<-review(morts=morts,new.data=new.data,type="mort",
                       ID="ID",station="Station.Name")
```

If there are no station changes between the flagged mortalities and `new.data`, or among the residence events within `new.data`, then nothing is returned. If a station change is found, the residence event with the station change will be returned.

Using the example in the first figure, Fish G is not included in the output of `review()`, because it did not move since it was flagged as a mortality. Fish F is included in the output, because a station change was detected. 

```{r rev_ex_table,echo=FALSE}
row.names(review_example)<-NULL
knitr::kable(review_example,align="c")
```

The user can then review the station change to ensure it is valid before removing the animal from `morts` and including the animal in further analyses. 

## Including previous data

An optional input is `old.data`, which is the original dataset or a subset of the original dataset that includes any residence events that may have occurred between the flagged potential mortality and the beginning of `new.data`. It is strongly recommended to include `old.data` if `backwards=TRUE` when the mortalities were previously identified and/or if drift was applied (see [Drift](https://rosieluain.github.io/mort/articles/a3_drift.html) vignette for more information on applying drift). 
```{r old_data,eval=FALSE}
review_example<-review(morts=morts,new.data=new.data,old.data=events,
                       type="mort",ID="ID",station="Station.Name")
```

## Applying drift

There is the option to apply drift when using `review()`. If applying drift, the arguments `ddd`, `from.station`, and `to.station` must be provided. See [Drift](https://rosieluain.github.io/mort/articles/a3_drift.html) vignette for more information on these arguments. In addition, the arguments `res.end`, `residences`, and `units` must be provided. These arguments are not necessary for identifying station changes with no drift, but are called by the function when drift is applied. 

```{r rev_drift,eval=FALSE}
drift_review<-review(morts=morts,new.data=new.data,old.data=old.data,
                     type="morts",ID="ID",station="Station.Name",
                     res.end="auto",residences="auto",units="auto",
                     ddd=ddd,from.station="From",to.station="To")
```