---
title: "Aerial Survey Analysis with tidycreel"
output:
  rmarkdown::html_vignette:
    highlight: null
vignette: >
  %\VignetteIndexEntry{Aerial Survey Analysis with tidycreel}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

Aerial creel surveys estimate total angler effort by conducting an instantaneous
count of anglers on the water from a low-flying aircraft. Because the aircraft
captures a snapshot of angler activity at a single moment, the count must be
expanded to total effort using the hours the fishery is open (`h_open`) and the
mean trip duration of anglers on the water (`L_bar`). The basic estimator is:

$$\hat{E} = N_{obs} \times \frac{h_{open}}{v}$$

where $N_{obs}$ is the observed (instantaneous) angler count, $h_{open}$ is the
number of hours the fishery is open per day, and $v$ is the **detection
probability** — the proportion of anglers present that are detected from the
aircraft. The mean trip duration $\bar{L}$ is estimated from ground interviews
and enters the catch rate estimation step rather than the effort expansion step.

When not all anglers are visible from the air — for example, anglers fishing
under tree cover or in enclosed shelters — a **visibility correction**
adjusts the count upward. If observers detect only 85% of anglers present,
the corrected effort estimate is scaled by $1 / 0.85 \approx 1.18$, yielding a
higher and more accurate total. The `visibility_correction` argument to
`creel_design()` carries $v$, and is required for an aerial design: pass
`"none"` to state explicitly that no correction applies.

### $v$ is the reciprocal of the published ratio

Field studies do not report $v$ directly. The standard ground-truthing method
reports the ratio

$$r = \frac{\text{ground count}}{\text{aerial count}}$$

which is **greater than 1** whenever the aircraft undercounts — Smucker et al.
(2010) report $r = 2.69$ for shore anglers. Because `visibility_correction` is a
probability, convert before supplying it:

$$v = 1 / r \qquad\text{so}\qquad r = 2.69 \;\longrightarrow\; v = 0.372$$

Passing $r$ directly is rejected by the `(0, 1]` check rather than silently
accepted, because the two parameterisations differ by a factor of $r^2$ in the
effort estimate.

### The correction is estimated, so it carries uncertainty

$v$ is estimated from paired air–ground counts, and the standard field method
reports its standard error as routine output. Supply it as `visibility_se` — on
the same probability scale — and that uncertainty is propagated into the effort
SE. For an SE published on the ratio scale, convert with $SE(v) = SE(r) / r^2$.

Because one estimate of $v$ divides every scaled count, it is a *shared*
multiplier: its contribution enters once at the total and does not shrink as
more flights are flown. Omitting `visibility_se` reports the component as
absent rather than as zero — a zero would be indistinguishable from never
having propagated it at all.

## Example Data

This vignette uses two built-in datasets representing a hypothetical summer
walleye and bass fishery at a Nebraska reservoir in June-July 2024.

```{r data}
library(tidycreel)

data(example_aerial_counts)
data(example_aerial_interviews)

head(example_aerial_counts)
head(example_aerial_interviews)
```

`example_aerial_counts` contains 16 sampling days (one overflight per day),
each recording an instantaneous count of anglers on the water. Weekday counts
range from 15 to 40 anglers; weekend counts range from 40 to 80. The
`example_aerial_interviews` dataset contains 48 angler interviews (3 per
sampling day) with trip duration in `hours_fished` and catch by species.

## Design Construction

Build an aerial survey design with `creel_design()`. The `h_open` argument is
required for aerial surveys — it specifies the number of hours the fishery is
open each day, which sets the expansion factor for the instantaneous count.

```{r calendar}
# Build the survey calendar from the unique count dates
aerial_cal <- data.frame(
  date = example_aerial_counts$date,
  day_type = example_aerial_counts$day_type,
  stringsAsFactors = FALSE
)

design <- creel_design(
  aerial_cal,
  date        = date,
  strata      = day_type,
  survey_type = "aerial",
  visibility_correction = "none",
  angler_ratio = 1,
  angler_ratio_se = 0,
  h_open      = 14
)

print(design)
```

The printed design confirms the survey type, `h_open`, and the number of
sampling days in each stratum.

## Adding Count Data and Estimating Effort

Attach the aerial count data with `add_counts()`. The `n_anglers` column is
auto-detected as the count variable.

```{r effort-no-correction}
design <- add_counts(design, example_aerial_counts)
```

Aerial effort estimation requires interview data to be attached before calling
`estimate_effort()`, because the estimator uses the mean trip duration
($\bar{L}$) from ground interviews to confirm the expansion factor. Attach the
interview data with `add_interviews()`, then estimate total effort.

```{r add-interviews}
design <- suppressWarnings(add_interviews(
  design,
  example_aerial_interviews,
  catch       = walleye_catch,
  effort      = hours_fished,
  trip_status = trip_status
))
```

```{r estimate-effort}
effort <- suppressWarnings(estimate_effort(design))
print(effort)
```

The `estimate` column is the projected total angler-hours over the full survey
period, and `se_between` quantifies between-day variability in the instantaneous
counts.

`se`, `ci_lower` and `ci_upper` are `NA`, and that is the correct output for this
design rather than a gap in it. `creel_design()` above was given
`visibility_correction = "none"`, which declares that no detection study was
done. The between-day component is known, but a component of the total's
uncertainty is not, and a standard error that silently omitted it would describe
a survey more precise than this one. `NA` says the uncertainty was never
propagated; `0` would say it was measured and found to be nothing. The next
section supplies a correction *and* its standard error, and the interval appears.

## Visibility Correction

When aerial observers cannot detect all anglers on the water, the raw count
underestimates true effort. Supply a `visibility_correction` to `creel_design()`
to account for this. A value of 0.85 means observers detected 85% of the
anglers actually present; the effort estimate is scaled up by $1 / 0.85$.

Here the correction is accompanied by `visibility_se`, so the reported effort SE
includes the uncertainty in the correction itself rather than treating 0.85 as
exactly known.

```{r visibility-correction}
design_corr <- creel_design(
  aerial_cal,
  date = date,
  strata = day_type,
  survey_type = "aerial",
  h_open = 14,
  visibility_correction = 0.85,
  angler_ratio = 1,
  angler_ratio_se = 0,
  visibility_se = 0.04
)

design_corr <- add_counts(design_corr, example_aerial_counts)
design_corr <- suppressWarnings(add_interviews(
  design_corr,
  example_aerial_interviews,
  catch       = walleye_catch,
  effort      = hours_fished,
  trip_status = trip_status
))

effort_corr <- suppressWarnings(estimate_effort(design_corr))
print(effort_corr)
```

Comparing the two estimates: the corrected effort is higher than the uncorrected
estimate because the visibility correction inflates the count to account for
undetected anglers.

```{r compare}
cat(
  "Uncorrected effort:", round(effort$estimate[[1]], 0), "angler-hours\n",
  "Corrected effort (v=0.85):", round(effort_corr$estimate[[1]], 0), "angler-hours\n"
)
```

## Interview-Based Catch Estimation

Aerial designs use the same interview workflow as other `tidycreel` designs.
The catch rate estimator computes CPUE (walleye per angler-hour) from the
complete-trip interviews already attached to the design.

```{r catch-rate}
catch_rate <- suppressWarnings(estimate_catch_rate(design))
print(catch_rate)
```

`estimate_total_catch()` multiplies the CPUE estimate by the total effort
estimate to project total walleye catch over the survey period.

```{r total-catch}
total_catch <- suppressWarnings(estimate_total_catch(design))
print(total_catch)
```

The delta-method standard error on total catch accounts for variance in both
the effort estimate and the CPUE estimate.

## Summary

The complete aerial survey workflow in `tidycreel` consists of four steps:

1. `creel_design(..., survey_type = "aerial", visibility_correction = v, h_open = N)`
   — define the survey with the required `h_open` expansion factor and the
   required `visibility_correction` (a detection probability, or `"none"` to
   declare that no correction applies). Add `visibility_se` to propagate the
   correction's own uncertainty.
2. `add_counts(design, counts)` — attach the instantaneous angler count data
   from each overflight.
3. `add_interviews(design, interviews, catch = ..., effort = hours_fished, ...)` — attach ground interview data for catch rate estimation.
4. `estimate_effort()`, `estimate_catch_rate()`, `estimate_total_catch()` — run
   the estimators.

All estimators return `creel_estimates` objects with point estimates, standard
errors, and 95% confidence intervals. Use `print()` to display results.

## References

- Jones, C. M., & Pollock, K. H. (2012). Recreational survey methods:
  estimation of effort, harvest, and abundance. Chapter 19 in *Fisheries
  Techniques* (3rd ed.), pp. 883-919. American Fisheries Society.

- Malvestuto, S. P. (1996). Sampling the recreational angler. Chapter 20 in
  *Fisheries Techniques* (2nd ed.), pp. 591-623. American Fisheries Society.

- Pollock, K. H., Jones, C. M., & Brown, T. L. (1994). *Angler Survey Methods
  and Their Applications in Fisheries Management*. American Fisheries Society
  Special Publication 25. Chapter 12: Aerial counts.