---
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 a day's effort using the hours the fishery is open (`h_open`). The
basic estimator for a day is:

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

where $N_{obs}$ is the observed (instantaneous) count, $h_{open}$ is the number
of hours the fishery is open per day, $a$ is the angler ratio (the proportion
of people counted who are anglers; 1 when every person counted is fishing), and $v$ is the
**detection probability** — the proportion of anglers present that are detected
from the aircraft. Effort comes from the counts alone; ground interviews supply
the catch rate.

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 comes from the counts alone: each day's count times `h_open`,
scaled by the angler ratio and the visibility correction. Interviews are not
needed for effort; they supply the catch rate later on. They are attached here
so the same design serves both. Each row is a party, so `n_anglers` gives its
size and the catch rate comes out per angler-hour, the unit of aerial effort.

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

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

The `estimate` column is the total angler-hours over the calendar given to
`creel_design()`, and `se_between` quantifies between-day variability in the
instantaneous counts. This calendar holds only the 16 flown days, so the total
covers those days. If your calendar lists every day of the season, flown or not,
ask for the season total with `target = "period_total"`; the default,
`"sampled_days"`, totals only the days flown (see `vignette("tidycreel")`).

`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 <- add_interviews(
  design_corr,
  example_aerial_interviews,
  catch       = walleye_catch,
  effort      = hours_fished,
  trip_status = trip_status,
  n_anglers   = n_anglers
)

effort_corr <- 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 <- 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 <- 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, and for the visibility correction
and angler ratio, which scale every stratum's effort and so enter the total
once. This design declares `visibility_correction = "none"`, so detection
uncertainty is unknown and the SE prints as `NA`, as the effort SE does; the
`design_corr` design above, with `visibility_se`, gives a finite one.

## Results as Data

Each estimate converts to a tibble with its method, variance method and unit as
columns, and plots with its confidence interval:

```{r results, fig.width = 6, fig.height = 3, fig.alt = "Visibility-corrected aerial effort estimate with its 95 percent confidence interval."}
tibble::as_tibble(total_catch)

ggplot2::autoplot(effort_corr)
```

## 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 angler survey methods:
  estimation of effort, harvest, and released catch. Chapter 19 in *Fisheries
  Techniques* (3rd ed.), pp. 883-919. American Fisheries Society.

- Malvestuto, S. P. (1996). Sampling the recreational creel. 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.