```{r echo=FALSE, message=FALSE, warning=FALSE}

library(knitcitations)

options("citation_format" = "pandoc")
bib <- read.bibtex("documentation.bib")

library(AnglerCreelSurveySimulation)
library(dplyr)

set.seed(256)


```

# Introduction

Population and individual-specific data on fisheries is necessary for fisheries managers to manage the fish populations for which they are responsible [@AndersonAndNeumann; @neumannetal2012]. Commercial fishing operations, subsistence fishing, and recreational angling all provide data-collection opportunities for fisheries managers. Given that recreational anglers can often be found angling at a fishing location during every day of the week, interviewing anglers to gather both catch, harvest, and effort data can provide fisheries managers and scientists with needed information to manage fish populations [@Malvestuto1996; @Pollocketal1994; @JonesAndPollock2012].

Recreational angling is an important source of fishing pressure and fishing mortality in many freshwater and marine systems [@MirandaAndBettoli; @JonesAndPollock2012]. In fisheries where commercial fishing does not exist, data to estimate fisheries stocks often comes from a combination of the remaining recreational fishery and from supplemented fisheries stock assessments. Though targeted population stock assessments by regional fisheries managers can readily identify the dynamic rate functions in a fishery (i.e., recruitment, growth, and mortality), standard fisheries stock assessments cannot address the effort, catch, and harvest rates observed by recreational anglers. As a result, sampling recreational anglers and their creels is necessary to estimate catch and harvest rates, as well as the effort involved [@Malvestuto1996; @Pollocketal1994; @JonesAndPollock2012; @Mcormickandmeyer].

Estimating recreational harvest, catch and release, and effort can be complex. Complexity of the survey design increases with the spatial scale of the fishery [@Lyleetal; @Pollock2003; @JonesAndPollock2012] and traditional access and roving surveys are unsuitable for fisheries with large spatial scales [@JonesAndPollock2012]. Research on simplifying the complexity of harvest, catch and release, and effort on fisheries with large spatial scales is ongoing; however, applying well thought-out and reasonable sampling designs to intercept and interview anglers will allow fisheries managers to make statistically-valid inferences from the data collected from those interviews.

Angler populations are generally too large---or too costly---to census completely [@JonesAndPollock2012; @Mcormickandmeyer]. As a result, samples are obtained from a population using probability sampling [@Thompson2002] so that statistical inferences about the properties of a population can be made [@Mcormickandmeyer]. Determining sample size for creel surveys *a priori* is difficult because of the complexities of creel survey design as well as the lack of replication of within-day sampling units [@Mcormickandmeyer]. Further, large sample sizes are not likely to result in precise estimates given that catch and effort are frequently estimates as the product of several random variables [@Mcormickandmeyer]. 

Estimation of effort and catch (or harvest) depend on the survey method used [@Pollocketal1994]. Total effort ($\widehat{E}$) and harvest ($\widehat{H}$) are calculated in traditional access-point surveys using the basic equations

$$\widehat{E} = \sum_{i=1}^{n}\frac{e_i}{\pi_i}$$

and 

$$\widehat{H} = \sum_{i=1}^{n}\frac{h_i}{\pi_i}$$

where $e_i$ is the effort and $h_i$ is the harvest of the $i^{th}$ sampling unit in a sample size of $n_i$; $\pi_i$ is the total probability that the $i^{th}$ sampling unit is included in the sample [@JonesAndPollock2012]. Total released catch ($\widehat{C}$) is calculated using an analogous equation for harvest. The definition of a sampling unit depends on the sampling frame that is used. In a traditional access-point survey, it is the site sampled on a specific day. 

## Types of Creel Surveys

In access-type surveys, creel surveyors are located at angler access point, intercepting anglers as they leave the fishery (i.e., upon trip completion). Surveyors may gather data on a number of topics in addition to catch and effort data (e.g., biological data on harvested fish, distance traveled to reach the fishery, economic data, etc.). On a small, single-access fishery, one surveyor could remain at the access point the entire fishing day and encounter every angler that used the fishery (i.e., $\pi = 1$). Single-access point fisheries are rare. In most cases larger, geographically-disparate fisheries have multiple access points that increase the $n$ in the above equations and, if left unsampled, bias $\widehat{E}$ and $\widehat{H}$ [@Malvestuto1996; @JonesAndRobson; @JonesAndPollock2012].

In large fisheries with multiple access points, multiple surveyors may be deployed to several different locations. As additional surveyors are added to the survey, however, labor costs increase. Bus-route creel surveys [@RobsonAndJones1989] allow surveyors to travel along a predetermined route of access points, arriving at an access point on schedule, waiting for a predetermined amount of time, then moving on to the next point. While at each site, the surveyor measures angler effort (i.e., recording the amount of time that an angling party's car is located at the site) and interviews departing anglers, collecting data on party size and catch (i.e., fish harvested and fish caught-and-released), and collecting additional biological data, if necessary. Robson and Jones [-@RobsonAndJones1989] and Jones and Robson [-@JonesAndRobson] detail the statistical theory behind bus route creel surveys.

Fisheries managers often inherit creel survey designs and constrained budgets in fisheries and wildlife agencies have renewed interest in streamlining survey designs [@Mcormickandmeyer].  The \proglang{R} package \pkg{AnglerCreelSurveySimulation} [@Ranney2024] is designed to help fisheries managers explore their survey design options. The \pkg{AnglerCreelSurveySimulation} package provides fisheries managers the opportunity to use *a priori* data in their simulations, tailoring the inputs to their fishery.

# Simulating surveys

## A trivial survey

In all cases, creel surveys collect data on anglers (including demographic data), their effort, and their catch and harvest. To simulate angler effort and catch, the \pkg{AnglerCreelSurveySimulation} package uses four functions to create the angler population (`make_anglers()`), calculate the surveyor-observed effort and catch and the total effort and catch (`get_total_values()`), simulate the actual survey (`simulate_bus_route()`), and conduct a survey of potentially infinte temporal length (`conduct_multiple_surveys()`). While all functions are accessible through the package, the user need only be familiar with `conduct_multiple_surveys()`. However, it helps to understand the rest of the functions to understand how the simulations are generated.

The angler population is simulated with `make_anglers()`:

```{r}

anglers <- make_anglers(n_anglers = 100, 
                        mean_trip_length = 3.88, 
                        fishing_day_length = 12)

head(anglers, 3)

```

The number of anglers visiting a site is `n_anglers`. The `mean_trip_length` argument is mean trip length of an angling party, calculated from *a priori* data on a fishery. The package defaults are from the Lake Roosevelt Fisheries Evaluation Program [@STOI]. `fishing_day_length` is the length, in hours, of the day available to anglers. The default value for `fishing_day_length` is the length of a mid-summer's sunrise-to-sunset hours. (Many fisheries management agencies limit fishing hours from one-half hour before sunrise to one-half hour after sunset.)

`make_anglers()`returns a dataframe that is `n_anglers` long with the variables `start_time`, `departureTime`, and `tripLength`. These values are the simulated start time of the angler at the fishery, the simulated departure time of the angler from the fishery, and the simulated total time spent on the fishery, respectively. `start_time` for an individual angler is randomly generated for each angler from the uniform distribution and is limited to the length of the fishing day minus `0.25` hours. `tripLength` is randomly generated from the $\gamma$ distribution with `shape = mean_trip_length`. `tripLength` is the difference between `departureTime` and `start_time`.

Once the angler population has been created, the `get_total_values()` function can be used to calculate observed and total values. `get_total_values()` uses the output from `make_anglers()` and requires information about the start, end, and wait times of the surveyor, along with the sampling probability ($\pi$ in the equations above), and the mean catch rate of the fishery. A number of defaults are included in the function but to customize the creel survey, users can specify survey times. For example, for one surveyor staying at a single access point for an 8-hour day:

```{r}

total_values <- get_total_values(anglers, 
                                 start_time = 2, 
                                 wait_time = 8, 
                                 sampling_prob = 8/12, 
                                 mean_catch_rate = 2.5)

total_values

```

Note that all times are related to the fishing day. For example, `start_time` above is `2` which means that the surveyor arrived on site two hours into the fishing day. If the fishing day started at 0600, then the surveyor arrived at 0800. The `sampling_prob` can be calculated from the `wait_time` of the surveyor divided by the length of the fishing day. `mean_catch_rate` is *a priori* data from the fishery. Individual angler catch rates are estimated from the $\gamma$ distribution with `mean_catch_rate` as the `shape` value.

The output from `get_total_values()` is a summary of the observed and "true" data from that access point. A data frame one row long and 10 columns wide, `get_total_values()` produces data that a surveyor would have collected related to catch and effort, as well as the totals for the day, including unobservable data (i.e., data points that fell outside of the creel surveyors time at the access site).

For the data from the theoretical survey, `simulate_bus_route()` will calculate estimated effort (i.e., $\widehat{E}$), the ratio of means catch rate (i.e., $\widehat{C}$), true catch, true effort, and the mean estimated catch rate of the anglers. `simulate_bus_route()` is a wrapper for both `make_anglers()` and `get_total_values()`. As a result, users do not have to call `make_anglers()` or `get_total_values()`.

```{r}

simulate_bus_route(start_time = 2, 
                   wait_time = 8, 
                   n_anglers = 100, 
                   n_sites = 1, 
                   sampling_prob = 8/12, 
                   mean_catch_rate = 2.5)

```
The return from `simulate_bus_route()` contains the estimates and the actual values of the creel survey. 

In this example, $\widehat{E}$ is calculated by the bus route estimator [@JonesAndRobson]

<!--  -->
$$\widehat{E} = T\sum_{i}{\frac{1}{w_{i}}}\sum_{j}{X_{ij}}$$
<!--  -->

where $\widehat{E}$ is the total party hours of fishing effort, $T$ is the total time required for the surveyor to complete the route (including wait times and travel times), $w_i$ is the waiting time at the $i^{th}$ site (where $i = 1, ... n$ sites), $e_{ij}$ is the total time that the $j^{th}$ car is parked at the $i^{th}$ site while the agent is at that site (where $j = 1, ... n$ sites), and $X_{ij}$ is the amount of time that an angling party's car ($j$) is present during the surveyor's wait at site $i$. The bus route estimator equation was developed to estimate fishing where anglers' cars would be seen parked at fishing access sites but the probability of encountering an angler and obtaining a completed-trip interview was low [@JonesAndRobson]. The bus route estimator estimates total angling party count rather than total angler count. To convert party-hours to angler-hours, an estimate of the number of anglers per party must be obtained from interviews [@JonesAndRobson].

The ratio of means catch rate (i.e., `catch_rate_ROM`) is estimated from:

<!--  -->
$$\widehat{R} = \frac{{\sum_{i=1}^n}{h_i}}{{\sum_{i=1}^n}{e_i}}$$
<!--  -->

where $h_i$ is the harvest and $e_i$ is the effort of the $i^{th}$ sampling unit in a sample size of $n$ [@Malvestuto1996].

Like `simulate_bus_route()` is a wrapper function for `make_anglers()` and `get_total_values()`, `conduct_multiple_surveys()` is a wrapper for all three. With `conduct_multiple_surveys()`, users can simulate `n_sims` number of surveys. For example, if a user were interested in simulating a months' worth of 8 hr-long weekday creel surveys (`4` weeks * `5` weekdays/month = `20` days):

```{r}

surveys <- conduct_multiple_surveys(n_sims = 20, 
                                    start_time = 2, 
                                    wait_time = 8, 
                                    n_anglers = 100, 
                                    n_sites = 1, 
                                    sampling_prob = 8/12, 
                                    mean_catch_rate = 2.5)

head(surveys)

```

`conduct_multiple_surveys()` calls `simulate_bus_route()` `n_sims` number of times and compiles all of the data into one data frame.

`simulate_bus_route()` and `conduct_multiple_surveys()` provide the data necessary to compare the estimated values of effort ($\widehat{E}$) and catch to the true values. $\widehat{E}$ can be plotted as a function of `true_effort`. Similarly, $\widehat{C}$ can be calculated as the product of `Ehat x catch_rate_ROM` and plotted as a function of `true_catch`. Comparing each of these two with a simple linear model can provide the user with quantitative evidence of how well the simulated creel survey matches "true" data. For example, intercept values approaching `0` and slope values approaching `1` would provide evidence that the simulation provided an accurate representation of the actual values. Of course, as `sampling_prob` increases, the more likely the samples will approach the `true_...` values.

Precision of the estimated values can be calculated with relative standard error (RSE) [@Malvestuto1996]. Relative standard error is

$$\frac{\frac{s}{\sqrt{n}}}{\bar{x}}$$

where $s$ is the standard deviation, $n$ is the sample size, and $\bar{x}$ is the mean. `calculate_rse()` is provided as a simple method of calculating the RSE from `conduct_multiple_surveys()`

```{r}

calculate_rse(surveys$Ehat)

```

## More complex designs

Though acceptable for a fishery for a single access point, conducting a creel survey on a fishery with $\>1$ access point is still possible with \pkg{AnglerCreelSurveySimulation}. The simulated surveyor could split their 8 hr shift between two access points that require 0.5 hr travel time between them. Simulating a 20 days' worth of creel surveys can be conducted as follows:

```{r}

# Begin at hour 0 of the fishing day at access point 1, 
# then 4.5 hrs into fishing day at access point 2
start_time <- c(0, 4.5) 

# wait time of 4 and 3.5hrs at each access point
wait_time <- c(4, 3.5)

n_sites <- 2

# 50 anglers at each access point
n_anglers <- c(50, 50)

fishing_day_length <- 12
sampling_prob <- sum(wait_time)/fishing_day_length

sim <- conduct_multiple_surveys(n_sims = 20, 
                                start_time = start_time, 
                                wait_time = wait_time,
                                n_sites = n_sites, 
                                n_anglers = n_anglers, 
                                sampling_prob = sampling_prob, 
                                mean_catch_rate = 2.5,
                                fishing_day_length = fishing_day_length)

sim %>% nrow()

sim %>% head()


```

Ultimately, the creel-survey simulation can be as complicated as a creel survey. If a survey requires multiple clerks, several simulations can be coupled together to act as multiple surveyors. For example, To accommodate weekends or holidays (e.g., with increased angler pressure), additional simulations with different wait times and more anglers (to simulate higher pressure) can be built into the simulation. For example, if the fisheries manager knows that angler pressure is 50% higher at the two access points on weekends, they could simulate the outcome of hiring a second, part-time clerk to sample 8 hrs a day on the weekends--one day at each access point--and add the weekend data to the weekday data, for a full months' worth of simulated surveys

```{r}


#Weekend clerks
start_time_w <- 2
wait_time_w <- 10
n_sites <- 1
n_anglers_w <- 75
fishing_day_length <- 12
sampling_prob <- 8/12

n_sims = 8

sim_w <- conduct_multiple_surveys(n_sims = 8, 
                                  start_time = start_time_w, 
                                  wait_time = wait_time_w, 
                                  n_sites = n_sites, 
                                  n_anglers = n_anglers_w, 
                                  sampling_prob = sampling_prob,
                                  mean_catch_rate = 2.5, 
                                  fishing_day_length = fishing_day_length)

#Add the weekday survey and weekend surveys to the same data frame
mon_survey <- 
  sim_w %>%
  mutate(day_type = 'weekend') %>%
  bind_rows(sim %>% 
              mutate(day_type = 'weekday')
            )

mon_survey %>%
  head()

```

# Conclusion

I developed the \pkg{AnglerCreelSurveySimulation} package to provide a simple means for fisheries managers to determine which creel survey design may be best suited to their fishery. If a management agency already has a strategy in place to estimate $\widehat{E}$ and $\widehat{C}$, I do not advocate changing that design unless there are concerns related to estimates of precision. Regardless, with \pkg{AnglerCreelSurveySimulation}, fisheries managers could, at a minimum, evaluate different designs and evaluate the trade-offs associated with adding multiple surveyors in an effort to increase data capture. 

There are a number packages written in \proglang{R} that are used for general analyses general analyses of fisheries data. For example, \pkg{FSA} [@fsa] provides functions to conduct typical introductory fishery analyses and \pkg{RFishBC} [@rfishbc] helps fisheries scientists collect growth data from calcified structures and back-calculate estimated lengths at previous ages. Although both of these packages are helpful for fisheries analyses, neither provide creel survey simulation opportunities. The Fishery Analysis and Modeling Simulator (FAMS) software [@fams] is designed to simulate and evaluate the dynamics of exploited fish populations and is limited to Windows-based computers. FAMS is thorough in its evaluation of length and bag limits in exploited fisheries and calculates yield-per-recruit and uses the entire population over time in simulations. FAMS [@fams] produces analyses related to a number of population parameters over time but requires inputs related to the exploitation level of a fishery (e.g., catch and effort). \pkg{AnglerCreelSurveySimulation} can provide $\widehat{E}$ and $\widehat{C}$ to allow fisheries managers to simlulate *what if?* questions and understand the fish populations for which they are resopnsible more comprehensively.