update precompile and forgot to add .Rmd

vignettes/_ps_estimate_coa_vignette.Rmd → vignettes/_estimate_ps_coa_vignette.Rmd

@@ -19,7 +19,7 @@ knitr::opts_chunk$set(
 ```
 ## Introduction
 
-This vignette will walk you through the analyses presented in [Winton et al. 2018](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13080), who describes the use of spatial point process models to estimate individual centers of activity (COA) from passive acoustic telemetry data. This vignette walks through how to prepare the data, using the models, and interpretating the results. We will be using the simplest case, which assumes that detection probabilities/receiver detection ranges remain constant over time, to a more complex application of a test-tag integrated model, that incorporates detection data from one or more stationary test transmitters to estimate time-varying detection ranges. The models are fitted in a Bayesian framework using the Stan software ([Carpenter et al. 2017](https://www.jstatsoft.org/article/view/v076i01/0)); code was modified from models found in [Royle et al. 2013](https://www.sciencedirect.com/book/monograph/9780124059399/spatial-capture-recapture) for fitting spatial point process models to data from camera traps. We prefer the Bayesian approach for COA estimation due to the treatment of uncertainty, but realize the longer computational time required may be prohibitive for some applications. We'd also like to note that the models described can support varying degrees of complexity - not all applications will require (or have the data to support) the most complex version of the model. The simpler the model, the shorter the run-time.
+This vignette will walk you through the analyses presented in [Winton et al. 2018](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13080), who describes the use of spatial point process models to estimate individual centers of activity (COA) from passive acoustic telemetry data. We will walk through how to prepare the data, using the models, and interpretating the results. We will be using the simplest case, which assumes that detection probabilities/receiver detection ranges remain constant over time, to a more complex application of a test-tag integrated model, that incorporates detection data from one or more stationary test transmitters to estimate time-varying detection ranges. The models are fitted in a Bayesian framework using the Stan software ([Carpenter et al. 2017](https://www.jstatsoft.org/article/view/v076i01/0)); code was modified from models found in [Royle et al. 2013](https://www.sciencedirect.com/book/monograph/9780124059399/spatial-capture-recapture) for fitting spatial point process models to data from camera traps. We prefer the Bayesian approach for COA estimation due to the treatment of uncertainty, but realize the longer computational time required may be prohibitive for some applications. We'd also like to note that the models described can support varying degrees of complexity - not all applications will require (or have the data to support) the most complex version of the model. The simpler the model, the shorter the run-time.
 
 We have tried to make the instructions outlined in this vignette user-friendly since we are a group of applied biologists with varying degrees of statistical experience. If some of the statistical notation outlined here or in [Winton et al. 2018](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13080) remains unclear, feel free to contact us with questions for clarification. This is a new package, so if you find bugs, places where code efficiency could be improved, or instances where the documentation could be made more user-friendly, please let us know through the [issues]( https://github.com/trackyverse/TelemetrySpace) on the GitHub repository! 
 
@@ -39,6 +39,7 @@ To run spatial point process/detection probability models in Stan we need to do
 We have several example datasets along with several functions to assist and streamline the data preparation. First, we need to evaluate the positions of the receivers and create a [Azimuthal Equal Distance projection (aeqd)](https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection). We use an aeqd project set in kilometers (km) for several reasons, the first being that in Stan it is very efficient to calculate distances among receivers, however, the distance between receivers needs to be on the same x and y plane and ranges need to be between 0.2 - 20 km apart. The second is because....(Mike I need you to add stuff here as you know more about aeqd). We will be working with example data for a single Lake Trout (*Salvelinus namaycush*) that was implanted with an acoustic transmitter in Parry Sound which is a large embayment of Georgian Bay, Lake Huron. 
 
 First, we load all the packages needed to carry out the analysis.
+
 ```{r setup, message=FALSE}
 {
   library(bayesplot)
@@ -110,7 +111,7 @@ We can notice that this detection data consists of 5 columns with 577 rows. To b
 
 For our detection data, we have a few things we need to do, the first is we need to build a time bin that we will create COAs. For this data we are going to use 1 hour but this time bin can range from 30 mins - 1 day or more and depends on the questions you are asking and the species you are working with. 
 
-Let's build our time bins
+Let's build our time bins.
 
 ```{r build time bin}
 ps_det_example <- build_time_bin(ps_det_example, unit = "1 hour")
@@ -168,7 +169,7 @@ There are a few things to know about running a Bayesian analysis, we suggest rea
 
 ### Priors
 
-Bayesian analyses rely on supplying uninformed or informed prior distributions for each parameter (coefficient; predictor) in the model. For the puproses of the deteciton probablity model the following priors are assumed and are not adjustable. To learn more about the structure of the priors and likelihoods see [Standard detection probability](https://telemetryspace.trackyverse.org/articles/coa_standard_gaussian_model.html).
+Bayesian analyses rely on supplying uninformed or informed prior distributions for each parameter (coefficient; predictor) in the model. For the puproses of the deteciton probablity model the following priors are assumed and are not adjustable. To learn more about the structure of the priors and likelihoods see [standard detection probability model](https://telemetryspace.trackyverse.org/articles/coa_standard_gaussian_model.html).
 
 $$
 \begin{aligned}
@@ -183,7 +184,7 @@ The Cauchy priors on $\alpha_0$ and $\alpha_1$ are weakly informative and
 regularize the intercept and decay-rate parameters toward zero while
 allowing heavy tails. Because both parameters carry explicit `lower`/`upper`
 bounds in the `parameters` block, the priors are implicitly truncated to
-those bounds — Stan automatically renormalizes the density over the
+those bounds. Stan automatically renormalizes the density over the
 constrained support, so no separate normalizing constant needs to be added
 by hand. The activity-center coordinates $s_{x,i,t}$ and $s_{y,i,t}$ have no
 explicit sampling statement, so they receive Stan's implicit flat (uniform)
@@ -224,6 +225,7 @@ m <- COA_Standard(
 )
 ```
 
+### Convergance and model performance 
 
 We can inspect the object created with the first object containing the Stan model. 
 To view and work with the model itself call `m$model`. However, as you will see there 
@@ -233,7 +235,7 @@ Are a bunch of other objects in the objected created. These objects have pulled
 ```{r summary of model object}
 summary(m)
 ```
-Let's look at our trace plots for the model parameters and posterior distributions to ensure the model converged properly. Remember the trace plots should look grassy or caterpillar like. A trace plot is the posterior draw for a given iteration plotted with the iteration number on the x axis and the posterior value for a given parameter or latent variable on the y. We evaluate this for both chains and want to see that both chains are converging on a smiler posterior draw for a given parameter or latent variable. We will first look at parameters of the model.  
+Let's look at our trace plots for the model parameters and posterior distributions to ensure the model converged properly. Remember the trace plots should look grassy or caterpillar like. A trace plot is the posterior draw for a given iteration plotted with the iteration number on the x-axis and the posterior value for a given parameter or latent variable on the y-axis. We evaluate this for both chains and want to see that both chains are converging on a similar posterior draw for a given parameter or latent variable. We will first look at parameters of the model.  
 
 ``` {r trace plots and post dist, fig.cap=""}
 stan_trace(m$model, pars = c("alpha0", "alpha1", "p0", "sigma"))
@@ -246,12 +248,11 @@ stan_dens(
 )
 ```
 
-We can see our trace plots look good and that the posterior distributions of our paramaters look good. 
+We can see our trace plots look good and that the posterior distributions of our parameters look good. 
 
 Next let’s look at our latent variables which are `sx` and `sy` or the estimated locations of the fish based on the detection probability. For large/lengthy time periods it will become cumbersome to evaluate the posteriors 
 this way and we recommend inspecting $\hat R$ and ESS. 
 
-
 ``` {r trace plots and post dist latent, fig.cap=""}
 stan_trace(m$model, pars = c("sx[1,1]", "sx[1,2]", "sy[1,1]", "sy[1,2]"))
 
@@ -262,8 +263,10 @@ stan_dens(
   linewidth = 0.1
 )
 ```
+
 Again, we can see that everything looks good and our model has converged. 
 
+### Posteriors
 Now moving on to the other elements in the outputted object from `COA_*()`. 
 
 
@@ -293,6 +296,7 @@ The fifth element returned, is `data.frame` of the median values for the latent
 ```{r coas}
 m$coas
 ```
+
 The sixth element returned, is a `data.frame` containing the posterior draws from each non-warm-up iteration from all chains. This contains the posterior distribution for each parameter and latent variable for each individual in each time step. It is unlikely that you will use this object instead we have created further objects that organize this data for specific applications that you are more likely to use. 
 
 ```{r all draws}
@@ -329,7 +333,8 @@ str(yrep)
 First, we are going to plot the posterior draws for locations. Within the package we 
 have a `sf` object that is the shape of Parry Sound. We can use this to plot the posterior draws of `sx` and `sy` to understand the movement of that of lake trout for 8 hours. 
 
-We need to take that `sf` object and transform it into an aeqd projection. 
+We need to take that `sf` object and transform it into an aeqd projection.
+
 ```{r ps aeqd}
 ps_aeqd <- ps |>
   st_transform(aeqd_crs)
@@ -402,15 +407,17 @@ p_param <- ggplot(
 p_param
 ```
 
-We can see that they are all quite tightly distributed with `p0` indicating that detection probability at a distance of `0` is between 48 - 54 %, while the `sigma` is around 1 km. 
+We can see that they are all quite tightly distributed with `p0` indicating that detection probability at a distance of `0` is between 48 - 54 %, while the `sigma` is around 1 km. Considering this is the standard model, `p0` nor other parameters vary. Considering how acoustic telemetry functions, we know that this is an unlikely represenation of these parameters which we can use a time-varying model and a tag-integrated, time-varying model to account for variation in the `p0` and other parameters. 
 
 Lastly, we can plot the predictive posterior check using `{tidybayes}`. First we need to make 
 detection counts as a vector from our `build_count()` object. 
 
 ```{r y_obs}
 y_obs <- as.vector(ps_count_example[!is.na(ps_count_example)])
 ```
+
 Next we can plot the densities using `ppc_dens_overlay()` from `{bayesplot}`.
+
 ```{r ppc dens, fig.cap=""}
 ppc <- ppc_dens_overlay(y = y_obs, yrep = yrep$yrep)
 ppc