nonevaluating vignettes

.gitignore

@@ -1,7 +1,6 @@
 .Rproj.user
 .Rproj
 .Rhistory
-.Rmd
 .RData
 working/
 pkgdown/

R/options.R

@@ -128,8 +128,8 @@ backwards<-function(data,morts,ID,station,res.start,stnchange=NULL){
 #' \dontrun{drift(data=data,format="manual",ID="TagID",station="Receiver",
 #' res.start="ResidenceStart",res.end="ResidenceEnd",ddd=driftstations,
 #' from.station="FrStation",to.station="ToStation")}
-drift<-function(data,type,ID,station,res.start,res.end,
- residences,units,ddd,from.station,to.station,
+drift<-function(data,type,ID,station,res.start="auto",res.end="auto",
+ residences="auto",units="auto",ddd,from.station,to.station,
  cutoff=NULL,cutoff.units=NULL,progress.bar=TRUE){
 
  if (type %in% c("actel","vtrack")){

docs/_pkgdown.yml

@@ -1,4 +1,11 @@
 url: https://rosieluain.github.io/mort/
 template:
  bootstrap: 5
-
+articles:
+ data-prep: data-prep.html
+ morts: morts.html
+ drift: drift.html
+ season: season.html
+ plots: plots.html
+ digging: digging.html
+ review: review.html

vignettes/data-prep.Rmd

@@ -15,7 +15,7 @@ knitr::opts_chunk$set(
 ```
 All mort functions rely on residence events. Residence events are similar to detection data, but include a start time, an end time, and duration. Before proceeding to explore your data and flag potential mortalities in mort, detection data must be converted into residence events. This can be done within mort using the `residences()` function, functions from other packages for acoustic telemetry data, or manually. 
 
-### mort format
+## mort format
 Residence events are generated in morts by the `residences()` function. A residence event either ends when the animal is detected at a new station or when the animal has not been detected longer than a user-defined cutoff. 
 
 ```{r residences, eval=FALSE}
@@ -32,10 +32,10 @@ data$DateTimeUTC<-as.POSIXct(data$DateTimeLocal,format="%Y-%m-%d %H:%M:%S",
 attributes(data$DateTimeUTC)$tzone<-"UTC"
 ```
 
-### Other formats
+## Other formats
 mort functions support the output from other packages for acoustic telemetry data. Note that the following information will be most useful if referenced while exploring the other mort functions. 
 
-#### actel
+### actel
 Residence events are called "movement events" in actel, and are generated using the `explore()` function. 
 
 Actel provides residence duration in the format HH:MM:SS. mort converts the duration to a numeric vector, with units of seconds. 
@@ -46,12 +46,12 @@ Dates in actel are in local time and will be converted to UTC by mort. Users wil
 warning("If actel date/times are in local time, they will be converted to UTC. Verify that time zone in actel output is correct.",call.=FALSE)
 ```
 
-#### glatos
+### glatos
 Residence events are called "detection events" in glatos, and are generated using the `detection_events()` function. 
 
 glatos uses seconds for the units of residence duration and UTC as the timezone for datetimes. 
 
-#### VTrack
+### VTrack
 Residence events are called "residences" in VTrack, and are generated using the `RunResidenceExtraction()` function. 
 
 As of VTrack version 2.10, it looks as though VTrack assigns the local time of the user's computer to datetimes. As detection data are typically downloaded in UTC, mort assumes that the datetimes output by VTrack are actually in UTC, rather than local time. Users will receive a warning when using VTrack residence events: 
@@ -75,10 +75,10 @@ warning("When the duration of an event is 0 s (a single detection) and
 ```
 
 
-#### Other packages?
+### Other packages?
 If we have missed any other packages that generate residence events, please let us know and start a new issue. We will work to incorporate other formats if feasible. To support other formats in mort, the residence events must have, at minimum, four columns: animal ID, station/location name, residence start time, and residence end time. The column names can vary from those used in mort, but must be consistent within the generating package. If the residence events include duration, the units must either be specified or invariant. 
 
-### Manual formatting
+## Manual formatting
 All mort functions will accept manual formatting (using the argument `type="manual"`). Manual formatting must be used if you have your own method for generating residence events. Manual formatting must also be used if you have used `residences()` or a function from another supported package to generate residence events, and then either modified the format (e.g., converted an actel list to a dataframe) or renamed the columns. 
 
 There are five mandatory columns for manually formatted data:

vignettes/digging.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "digging"
+title: "Digging into your data"
 output: rmarkdown::html_vignette
 vignette: >
- %\VignetteIndexEntry{digging}
+ %\VignetteIndexEntry{Digging into your data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
 ---
@@ -14,6 +14,51 @@ knitr::opts_chunk$set(
 )
 ```
 
-```{r setup}
+```{r setup,echo=FALSE}
 library(mort)
 ```
+All the functionality of the morts package is accessible with the `residences()`, `morts()`, `infrequent()`, `mortsplot()`, and `review()` functions, addressed in the other vignettes. Many of these functions rely on output from additional functions. As you are exploring your data, you may want to run these additional functions to better dig through and understand your data. The `drift()` and `season()` functions are respectively addressed in the "Drift" and "Seasonality" vignettes. Here, we address the `stationchange()`, `resmax()`, and `resmaxcml()` functions. 
+
+## `stationchange()` function
+The thresholds in `morts()` rely on identifying the most recent station or location change of each animal, because it is assumed that the animal was alive before this most recent movement. To explore the most recent station changes for each animal, the user can can call `stationchange()` directly. The arguments are used in the same manner as for `morts()`. Drift may also be applied with the argument `drift=TRUE`. See the "Drift" vignette for more information on the other drift arguments.
+
+```{r stnchange,eval=FALSE}
+station_change<-stationchange(data=data,type="mort",ID="ID",station="Station.Name",
+ drift=TRUE,ddd=ddd,units="days",from.station="From",to.station="To")
+```
+<!-- table that is the header of the stationchange output -->
+
+## `resmax()` function
+The threshold for `morts()` when `method` is "last", "any", or "all" is determined by identifying the longest residence event that occurred before a station change. If there are some animals with very long resident events that are not identified as potential mortalities by `morts()`, you may want to look at the longest living residence events to explore how the threshold is being identified. This can be done by calling the `resmax()` function directly. 
+
+Note that `stationchange()` must be run beforehand, and the output provided in the argument `stnchange`.
+
+If drift was applied in generating the residence events, the `drift` argument specifies whether drift events should be included in `resmax()`. If drift was not applied or if `drift="morts"` in `morts()`, then you should include `drift=FALSE`. If `drift="threshold"` or `drift="both"` in `morts()`, then you should include `drift=TRUE`. 
+
+```{r rm_example,eval=FALSE}
+resmax_example<-resmax(data=data,ID="ID",station="Station.Name",
+ res.start="ResidenceStart",residences="ResidenceLength.days",
+ stnchange=station_change,drift=FALSE)
+```
+
+
+## `resmaxcml()` function
+The threshold for `morts()` when the `method` is "cumulative" or "any" is determined by finding the longest cumulative residence event that occurred before a station change. Cumulative residence events are the length of time between when an animal was first detected at a station and when it was last detected at the same station, ignoring any gaps in detection. You may wish to explore the cumulative residence events that contribute to determining this threshold. This can be done by calling the `resmaxcml()` function directly. 
+
+Note that `stationchange()` must be run beforehand, and the output provided in the argument `stnchange`. 
+
+If you have applied drift by using `drift="threshold"` or `drift="both"` in `morts()`, then you should apply drift using the `drift()` function and use the output as the input for the `data` argument in `resmaxcml()`. See the "Drift" vignette for more information on applying drift. 
+
+```{r rmcml_example,eval=FALSE}
+resmaxcml_example<-resmaxcml(data=data,ID="ID",station="Station.Name",
+ res.start="ResidenceStart",res.end="ResidenceEnd",
+ residences="ResidenceLength.days",units="days",
+ stnchange=station_change)
+```
+<!-- Table with header of output -->
+
+Note that the output includes one row for each cumulative residence event, instead of one row for the longest event per animal (as in `resmax()`).
+
+
+
+

vignettes/drift.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "drift"
+title: "Dead and drifting"
 output: rmarkdown::html_vignette
 vignette: >
- %\VignetteIndexEntry{drift}
+ %\VignetteIndexEntry{Dead and drifting}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
 ---
@@ -14,6 +14,93 @@ knitr::opts_chunk$set(
 )
 ```
 
-```{r setup}
+```{r setup,echo=FALSE}
 library(mort)
 ```
+
+There may be situations where a tag that was expelled or from a dead animal may appear to move among stations or locations. This apparent movement could be due to the tag drifting with currents or tides. If a tag is located within range of two overlapping recievers, simultaneous or near-simultaneous detections at the two receivers may be assigned to different residence events. Left unaddressed, these residence events at different stations would be considered by mort to be station changes.
+
+## Specifying drift stations 
+Drift stations must be specified by the user. These can be determined by common sense (e.g., Station 5 is upstream of Station 4, so drift can occur from Station 5 to Station 4). Potential drift stations can also be determined by plotting and exploring residence events (see "Plotting" vignette). A series of long residences at one station that are followed by a series of long residences at another station may indicate drift from unmapped currents in the study area. Brief residence events with numerous station changes between two stations may indicate stations that overlap under certain environmental conditions. 
+
+To apply drift, the user must specify the drift stations in a dataframe. The dataframe must have two columns: the station where the tag is drifting from, and the station where the tag is drifting to. The station names must match those in the `station` argument in all mort functions. Each row will specify one possible drift movement. The movement is directional, so if two stations overlap, both directions must be specified. The drift dataframe is later called with the argument `ddd` - "ddd" for "dead drift direction", as a reminder that drift is applied directionally. 
+
+The table below shows an example drift dataframe. Note that drift between Stations 2 and 3 can be bidirectional, so both drift from Station 2 to Station 3 and drift from Station 3 to Station 2 are included. 
+
+<!-- Example drift table -->
+
+When drift is applied within `morts()` or `infrequent()`, residence events that could be due to drift are combined to form drift residence events. 
+
+Residence events before applying drift: 
+```{r before_drift,eval=FALSE,echo=FALSE}
+plot<-mortsplot(data=data,type="mort",ID="ID",station="Station.Name")
+plot
+```
+
+Residence events, including drift residence events: 
+<!-- How does this plot? Which station is used for the colour -->
+```{r after_drift,eval=FALSE,echo=FALSE}
+drift.data<-drift(data=data,type="mort",ID="ID",station="Station.Name",
+ ddd=drift.dataframe,from.station="From",to.station="To",
+ cutoff=1,cutoff.units="days",progress.bar=FALSE)
+plot<-mortsplot(data=data,type="mort",ID="ID",station="Station.Name")
+plot
+```
+
+## Applying drift 
+Drift is applied in `morts()` and `infrequent()` by including five arguments: 
+
+#. `ddd` - the drift dataframe (see above for preparing a drift dataframe)
+
+#. `from.station` - a character string of the column name in `ddd` with the station names where a tag could be drifting from
+
+#. `to.station` - a character string of the column name in `ddd` with the station names where a tag could be drifting to
+
+#. `drift.cutoff` - the maximum allowable time difference between detections to be considered a single residence event. This is usually the same cutoff that was used to gernerate the residence events from detection data. 
+
+#. `drift.units` - the units of `drift.cutoff`
+
+```{r drift_ex_inf, eval=FALSE}
+drift_ex<-infrequent(data=data,type="mort",ID="ID",station="Station.Name",
+ ddd=drift.dataframe,
+ from.station="From",to.station="To",
+ drift.cutoff=1,drift.units="days")
+```
+
+For `morts()`, there is a sixth argument `drift` that specifies when drift should be applied. Drift can be applied to identifying mortalities only `drift="morts"`, identifying thresholds only `drift="threshold"`, or both identifying mortalities and thresholds `drift="both"`.
+
+Applying drift to thresholds `drift="threshold"` will increase the threshold, and fewer tags may be flagged as mortalities. There are few cases where this will be desirable, but it may be useful for arrays with two or more overlapping receivers. A single drift residence event would be generated for a tag located within range of two receivers, and this drift residence event would be included in identifying thresholds. 
+
+The most conservative option is `drift="morts"`. This is because drift residences are removed from identifying thresholds, and thresholds will likely be shorter than if drift residences were included. Including drift residences in identifying mortalities will likely lengthen residence events, making it easier for an event to exceed the threshold. See below for an example of identifying mortalities with and without applying drift. 
+
+<!-- Evaluate and plot when test dataset is ready -->
+```{r no_drift, eval=FALSE}
+no_drift<-morts(data=data,type="mort",ID="ID",station="Station.Name",method="all")
+
+plot<-mortsplot(data=data,type="mort",ID="ID",station="Station.Name",
+ morts=no_drift)
+plot
+```
+
+```{r drift_ex_morts, eval=FALSE}
+drift_ex<-morts(data=data,type="mort",ID="ID",station="Station.Name",method="all",
+ drift="morts",ddd=drift.dataframe,
+ from.station="From",to.station="To",
+ drift.cutoff=1,drift.units="days")
+
+plot<-mortsplot(data=data,type="mort",ID="ID",station="Station.Name",morts=drift_ex)
+plot
+```
+
+## `drift()` function
+If you are interested in exploring how drift residences are applied, the `drift()` function that is called by `morts()` and `infrequent()` is also available as a standalone function. The arguments for `drift()` are the same as those for the other functions. 
+
+```{r df, eval=FALSE}
+drift.data<-drift(data=data,type="mort",ID="ID",station="Station.Name",
+ ddd=drift.dataframe,from.station="From",to.station="To",
+ cutoff=1,cutoff.units="days")
+```
+
+
+
+