Estimate total harvest by combining effort and HPUE

Computes total harvest estimates by multiplying effort × HPUE with variance propagation via the delta method. Requires a creel design with both count data (for effort estimation) and interview data (for HPUE estimation).

Usage

estimate_total_harvest(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  target = c("sampled_days", "stratum_total", "period_total"),
  aggregate_sections = TRUE,
  missing_sections = "warn"
)

Arguments

design

A creel_design object with both counts (via add_counts) and interviews (via add_interviews) attached. Both count and interview survey objects must exist. Interview data must include harvest column (specified via harvest parameter in add_interviews).

by

Optional tidy selector for grouping variables. When specified, must match across both effort and HPUE estimates (same calendar strata or interview variables). Accepts bare column names, multiple columns, or tidyselect helpers.

variance

Character string specifying variance estimation method: "taylor" (default), "bootstrap", or "jackknife". Applied to BOTH effort and HPUE estimation, then combined via delta method.

conf_level

Numeric confidence level (default: 0.95)

target

Character string specifying the effort domain supplied to estimate_effort(). Options are "sampled_days" (default), "stratum_total", or "period_total". This controls which effort domain is multiplied by HPUE so total harvest stays aligned with the requested temporal target.

aggregate_sections

Logical. When the design was created with add_sections, should a .lake_total row be appended that sums the per-section estimates? Default TRUE. Set to FALSE to return only the per-section rows without the lake total.

missing_sections

Character(1). Action when a registered section is absent from either count data or interview data: "warn" (default) inserts an NA row with data_available = FALSE, "error" raises a hard error.

Value

A creel_estimates S3 object with method = "product-total-harvest"

Details

Total harvest is computed as Effort × HPUE. Variance is propagated using the delta method, which accounts for uncertainty in both estimates. The formula for independent estimates is approximately:

$$Var(E \times H) \approx E^2 \cdot Var(H) + H^2 \cdot Var(E)$$

The function uses survey::svycontrast() to compute variance automatically via symbolic differentiation and Taylor series approximation.

Sectioned designs: When add_sections has been called on the design, each section is estimated independently. The lake-wide total is sum(TH_i), not E_total * HPUE_pooled. The lake-wide SE uses the zero-covariance assumption: sqrt(sum(se_i^2)).

Design compatibility requirements:

• Count data must be attached via add_counts() for effort estimation

• Interview data must be attached via add_interviews() for HPUE estimation

• Harvest column must be specified in add_interviews (harvest parameter)

• Grouped estimation requires identical grouping variables for both estimates

• Calendar stratification must be shared between counts and interviews

See also

estimate_effort, estimate_harvest_rate, estimate_total_catch

Other "Estimation": est_length_distribution(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_release()

Examples

library(tidycreel)
data(example_calendar)
data(example_counts)
data(example_interviews)

# Create design with both counts and interviews including harvest
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
#> Warning: No weights or probabilities supplied, assuming equal probability
design <- add_interviews(design, example_interviews,
  catch = catch_total, harvest = catch_kept, effort = hours_fished,
  trip_status = trip_status, trip_duration = trip_duration
)
#> ℹ No `n_anglers` provided — assuming 1 angler per interview.
#> ℹ Pass `n_anglers = <column>` to use actual party sizes for angler-hour
#>   normalization.
#> ℹ Added 22 interviews: 17 complete (77%), 5 incomplete (23%)

# Estimate total harvest
total_harvest <- estimate_total_harvest(design)
#> Warning: Small sample size for harvest estimation.
#> ! Sample size is 22. Ratio estimates are more stable with n >= 30.
#> ℹ Variance estimates may be unstable with n < 30.
print(total_harvest)
#> 
#> ── Creel Survey Estimates ──────────────────────────────────────────────────────
#> Method: Total Harvest (Effort × HPUE)
#> Variance: Taylor linearization
#> Confidence level: 95%
#> Effort target: sampled_days
#> 
#> # A tibble: 1 × 5
#>   estimate    se ci_lower ci_upper     n
#>      <dbl> <dbl>    <dbl>    <dbl> <int>
#> 1     508.  41.8     426.     590.    22

# Compare components
effort_est <- estimate_effort(design)
hpue_est <- estimate_harvest_rate(design)
#> Warning: Small sample size for harvest estimation.
#> ! Sample size is 22. Ratio estimates are more stable with n >= 30.
#> ℹ Variance estimates may be unstable with n < 30.
# total_harvest$estimates$estimate approximately equals effort_est * hpue_est

# Note: Grouped estimation requires n >= 10 per group
# Check sample sizes before grouping:
# table(design$interviews$day_type)
# total_harvest_by_type <- estimate_total_harvest(design, by = day_type)