--- title: "Getting Started with tidycreel" output: rmarkdown::html_vignette: highlight: null vignette: > %\VignetteIndexEntry{Getting Started with tidycreel} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## Introduction tidycreel gives fisheries biologists a tidy, pipe-friendly way to design and analyse creel surveys. You work with the terms used in the field (dates, strata, counts, interviews) without handling the internals of the survey package. This tutorial analyses one complete season, start to finish. A clerk worked a lake for 120 days, from May 1 to August 28. On 36 of those days the clerk made an instantaneous count of anglers and interviewed angling parties, both those that had finished fishing and some still fishing. The questions are the usual ones: how much fishing happened over the season, how many fish were caught, and how many were kept. Each answer is built from the one before: ``` calendar -> design counts -> effort (angler-hours) interviews -> catch rate (fish per angler-hour) effort x rate -> total catch (fish) ``` ## The season ```{r data} library(tidycreel) data(example_season_calendar) data(example_season_counts) data(example_season_interviews) head(example_season_calendar) table(example_season_calendar$day_type, example_season_calendar$sampled) ``` The calendar lists every day of the season, not only the sampled ones, and splits them into weekdays and weekends. The clerk sampled 28 of the 86 weekdays and 8 of the 34 weekend days. That list of every day is what lets tidycreel expand from the days that were sampled to the whole season. ## Survey design ```{r design} design <- creel_design(example_season_calendar, date = date, strata = day_type) design ``` `creel_design()` uses tidy selectors, so you name columns without quotes. The design records the 120-day calendar and its two strata. ## Counts ```{r counts} head(example_season_counts) design <- add_counts(design, example_season_counts, count_col = total_anglers, period_length_col = daylight_hours ) ``` Each row is one instantaneous count: the number of anglers fishing at the moment the clerk looked. A count is a number of anglers, not an amount of effort. To turn it into effort, tidycreel needs to know how much time the count stands for. Here the single count on each day represents the whole 14-hour fishing day, so `daylight_hours` is the period length. Effort for a day is the count times that length, in angler-hours. Leaving out `period_length_col` still gives an estimate, but its unit is unknown, and `estimate_effort()` warns that no period length was supplied. tidycreel derives units from what you give it and never assumes one. ## Effort There are two different questions you can ask of these counts. ```{r effort} estimate_effort(design) estimate_effort(design, target = "period_total") ``` The first estimate, the default, is the effort **on the 36 days that were sampled**: 3,066 angler-hours. The second is the effort **over the whole 120-day season**, about 9,994 angler-hours. That season total is the number usually reported. Each stratum's mean daily effort is multiplied by the number of days in that stratum, then the strata are added. For a season total, ask for `target = "period_total"`. The standard error comes from the day-to-day variation among the sampled days within each stratum. With one count per day the within-day variation (when in the day each count happened to fall) cannot be estimated separately, so `se_within` is 0 as a placeholder, not because activity was steady through the day. It becomes non-zero when a day has several counts. With one count per day the standard error also leaves out the finite-population correction, so it is slightly conservative; `vignette("effort-pipeline")` explains why. Estimates can be broken down by any column in the design with `by`: ```{r effort-by} estimate_effort(design, by = day_type, target = "period_total") ``` The 86 weekdays account for most of the season's effort, about 7,900 angler-hours to the weekends' 2,100. Per day, the two are closer: about 92 angler-hours on an average weekday and 61 on an average weekend day. ## Interviews ```{r interviews} head(example_season_interviews) design <- add_interviews(design, example_season_interviews, catch = catch_total, harvest = catch_kept, effort = hours_fished, trip_status = trip_status, n_anglers = n_anglers ) ``` Each row is one party. `add_interviews()` checks the interviews as it attaches them and reports what it found: 172 complete trips, 59 incomplete, and 153 parties that caught nothing. Most anglers on most fisheries go home without a fish, and those zeros belong in the catch rate. The count is shown because, on a real data sheet, a column of zeros can also mean a catch that was never recorded. If your zeros are real, as these are, there is nothing to fix. `n_anglers` matters. `hours_fished` is how long the party fished, so it is in party-hours. A party of three fishing two hours put in six angler-hours, and `n_anglers` lets tidycreel make that conversion. The catch rate is then in fish per angler-hour, the same footing as the counts. Without it the rate would be per party-hour, which cannot be multiplied by effort in angler-hours. ## Catch rates ```{r rates} estimate_catch_rate(design) estimate_harvest_rate(design) ``` The catch rate is about 0.22 fish per angler-hour, and the harvest rate about 0.06. Both are ratio-of-means estimates, total catch divided by total effort across the interviews. By default they use only the 172 complete trips. A party interviewed while still fishing is more likely to be met the longer it stays, so incomplete trips over-represent long trips (length-of-stay bias) and give a biased catch rate unless the rate is steady through a trip. `vignette("incomplete-trips")` covers when and how incomplete trips can be used. ## Total catch and harvest ```{r totals} estimate_total_catch(design, target = "period_total") estimate_total_harvest(design, target = "period_total") ``` A total is effort times rate, with the uncertainty of both carried into its standard error. The unit follows: angler-hours times fish per angler-hour is fish. About 2,230 fish were caught over the season, and about 650 were kept. These totals take `target` too, and need `target = "period_total"` for the season, just as effort does. Totals break down the same way as effort: ```{r totals-by} estimate_total_catch(design, by = day_type, target = "period_total") ``` Released fish come from species-level catch records, attached with `add_catch()`, rather than from the interview totals; see `?estimate_total_release`. ## Using results as data An estimate prints with its method, variance method and unit. It is not itself a data frame, so dplyr verbs do not work on it directly. Convert it first. `as_tibble()` returns one row per estimate, with the metadata copied into columns so it stays attached to every row: ```{r as-tibble} catch_by_day <- estimate_total_catch(design, by = day_type, target = "period_total") catch_tbl <- tibble::as_tibble(catch_by_day) catch_tbl catch_tbl[catch_tbl$day_type == "weekend", c("day_type", "estimate", "se", "unit")] ``` `as.data.frame()` does the same for base R. Use `metadata = FALSE` for the estimates table alone. ## Plotting Estimates have an `autoplot()` method that draws each estimate with its confidence interval: ```{r plot, fig.width = 6, fig.height = 3.5, fig.alt = "Point estimates of total catch on weekdays and weekends, with 95 percent confidence intervals."} ggplot2::autoplot(catch_by_day) ``` `vignette("visualisation")` covers the other plots. ## Variance methods Standard errors use Taylor linearization by default. Bootstrap and jackknife replicates are also available, for effort and for every estimate built on it: ```{r variance} set.seed(123) estimate_effort(design, target = "period_total", variance = "bootstrap") estimate_effort(design, target = "period_total", variance = "jackknife") ``` - **Taylor linearization** (default) is fast and appropriate for most estimates. - **Bootstrap** resamples sampled days. Use it to check the linearization or for statistics that are not smooth. - **Jackknife** is deterministic, so it gives the same answer on every run. `vignette("replicate-designs")` compares them. ## Next steps This tutorial used the most common design: instantaneous counts and access interviews, with weekday and weekend strata. From here: - `vignette("survey-scheduling")` builds the sampling calendar before the season, including high-use periods such as openers. - `vignette("interview-estimation")` and `vignette("incomplete-trips")` cover catch-rate estimators in depth. - `vignette("section-estimation")` handles lakes split into sections. - The **Survey Types** articles cover bus-route, ice, camera, aerial and mark-recapture designs. - `vignette("glossary")` defines the terms used throughout.