Package {tidycreel}

Title:	Tidy Interface for Creel Survey Design and Analysis
Version:	8.0.0
Description:	Provides a tidy, pipe-friendly interface for creel survey design, data management, estimation, visualisation, and reporting. A creel survey interviews anglers on site to estimate fishing effort, catch, and harvest for a water body. Built on the 'survey' package for design-based inference, with support for instantaneous, bus-route, ice, camera, and aerial designs. Catch-rate estimators follow Hoenig, Jones, Pollock, Robson and Wade (1997) <doi:10.2307/2533116>; bus-route designs follow Kinloch, McGlennon, Nicoll and Pike (1997) <doi:10.1016/s0165-7836(97)00068-4>.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	checkmate, cli, dplyr, generics, ggplot2, lifecycle, rlang, stats, survey, tibble, tidyselect (≥ 1.2.0)
Suggests:	bench, covr, DBI, duckdb, glmmTMB, hedgehog, htmlwidgets, knitr, lintr, lme4, lubridate (≥ 1.9.0), pkgdown, pkgload, quickcheck, profvis, readxl (≥ 1.4.0), rmarkdown, styler, testthat (≥ 3.0.0), withr, writexl (≥ 1.5.4), zipcodeR
VignetteBuilder:	knitr
Config/testthat/edition:	3
URL:	https://github.com/chrischizinski/tidycreel, https://chrischizinski.com/tidycreel/
BugReports:	https://github.com/chrischizinski/tidycreel/issues
NeedsCompilation:	no
Packaged:	2026-09-30 18:33:31 UTC; cchizinski2
Author:	Christopher Chizinski [aut, cre, cph]
Maintainer:	Christopher Chizinski <cchizinski2@unl.edu>
Repository:	CRAN
Date/Publication:	2026-10-10 11:20:02 UTC

tidycreel: Tidy Interface for Creel Survey Design and Analysis

Description

Provides a tidy, pipe-friendly interface for creel survey design, data management, estimation, visualisation, and reporting. A creel survey interviews anglers on site to estimate fishing effort, catch, and harvest for a water body. Built on the 'survey' package for design-based inference, with support for instantaneous, bus-route, ice, camera, and aerial designs. Catch-rate estimators follow Hoenig, Jones, Pollock, Robson and Wade (1997) doi:10.2307/2533116; bus-route designs follow Kinloch, McGlennon, Nicoll and Pike (1997) doi:10.1016/s0165-7836(97)00068-4.

Author(s)

Maintainer: Christopher Chizinski cchizinski2@unl.edu (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/chrischizinski/tidycreel

• https://chrischizinski.com/tidycreel/

• Report bugs at https://github.com/chrischizinski/tidycreel/issues

Attach age data to a creel design

Description

add_ages() attaches a data frame of individual fish age records (from scale, fin ray, or otolith samples) to a creel_design object. The age data are linked to interviews via a shared identifier, analogous to add_lengths().

Usage

add_ages(design, data, age_uid, interview_uid, species, age, age_type)

Arguments

Value

A creel_design object with age data attached in design$ages and associated column-name slots.

See Also

add_lengths()

Examples

data(example_calendar)
data(example_interviews)
data(example_ages)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
design <- add_ages(design, example_ages,
  age_uid       = interview_id,
  interview_uid = interview_id,
  species       = species,
  age           = age,
  age_type      = age_type
)
head(design$ages)

Attach species-level catch data to a creel design

Description

Attaches a long-format data frame of species-level catch data to a creel_design object. Each row in data represents a species-catch-type combination for a single interview. Data is validated at attach time and stored on the design for use by downstream summary and estimation functions.

Usage

add_catch(design, data, catch_uid, interview_uid, species, count, catch_type)

Arguments

Details

Catch type model: Each species-interview row carries one of three catch types. "caught" is the total; "harvested" and "released" are subsets. A "caught" row is optional — when absent, total catch is inferred as harvested + released. When a "caught" row is present, caught >= harvested + released is enforced (CATCH-04).

Interview ID validation: Every interview ID appearing in data must appear in design$interviews[[interview_uid]]. Interviews with no catch rows are valid (anglers who caught nothing need not appear in catch data).

Counts must be known (CATCH-07): count may not contain NA. A missing row carries a definite meaning here — none of that disposition, or, for a "caught" row, derive the total from harvested + released — so a row that is present but carries an unknown count is silently read as that same definite thing rather than as an unknown. Fill the missing counts, or drop those rows; note that dropping states something, since a dropped "caught" row changes how the total is derived rather than setting it to zero. Aborts with class creel_error_na_catch_count.

Immutability: Returns a new creel_design — the input is not modified. Calling add_catch() on a design that already has $catch is an error.

Value

A new creel_design object with $catch and associated $catch_*_col fields attached.

See Also

Other "Survey Design": add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

data(example_calendar)
data(example_interviews)
data(example_catch)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status, trip_duration = trip_duration
)
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
print(design)

Attach count data to a creel design

Description

Attaches count-side effort data to a creel_design object and constructs the internal survey design object eagerly. The preferred workflow is to standardize raw count-process data into sampled-day effort rows with prep_counts_daily_effort() (or another ⁠prep_counts_*()⁠ helper) before calling add_counts(). This keeps survey-specific count reconstruction logic out of the core estimator path.

Compatibility paths for raw-ish count inputs remain supported: add_counts() can still aggregate multiple within-day observations via count_time_col and can still compute progressive-count daily effort from circuit_time and period_length_col. Eager construction catches design errors at add_counts() time when users have context about what data they are adding.

period_length_col applies to instantaneous counts as well as progressive ones. An instantaneous count is a snapshot of the anglers present at one moment, so it becomes effort only once multiplied by the period it was randomised within; supply that column and the estimate is in angler-hours.

Usage

add_counts(
  design,
  counts,
  count_col = NULL,
  psu = NULL,
  count_time_col = NULL,
  count_type = "instantaneous",
  circuit_time = NULL,
  period_length_col = NULL,
  unit_cols = NULL,
  allow_invalid = FALSE
)

Arguments

Value

A new creel_design object (list) with components:

Immutability

add_counts() follows functional programming patterns and returns a new creel_design object. The original design object is not modified. This prevents accidental data loss and makes the workflow explicit: design2 <- add_counts(design, counts) not add_counts(design, counts)

Validation

add_counts() performs Tier 1 validation:

• Count data schema (Date column, numeric column) via validate_count_schema()

• Design column presence (date_col, strata_cols, PSU in count data)

• No NA values in design-critical columns (date, strata, PSU)

• Survey construction (catches lonely PSU errors, stratification issues)

Party-size expansion carriers

derive_angler_count() attaches expansion_basis, expansion_se, expansion_group, and expansion_of to the counts table so the party-size sampling error can reach the effort standard error. The four are written together and must travel together: add_counts() aborts on a table carrying only some of them, since that state can only come from partial deletion and would otherwise drop the variance component while leaving an expansion_se visible in the data.

add_counts() also aborts when count_col is not the column named in expansion_of. The basis is d(count)/d(party_size), so a count transformed after derive_angler_count() no longer matches the basis carried beside it, and the variance component would come out understated by exactly the scale factor while still reading as propagated. Supply the untransformed count and period_length_col, which scales the count and the basis together.

Dropping all four — which an ordinary select() will do — is indistinguishable here from counts that never had them, and is silent.

PSU Specification

Per user decision (clarified 2026-02-08), PSU is specified only in add_counts(), not in creel_design() constructor. PSU is only meaningful when count data is present, making add_counts() the correct abstraction boundary. This design allows the same creel_design calendar to be used with different PSU structures.

See Also

Other "Survey Design": add_catch(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

# Preferred workflow: standardize sampled-day effort before attachment
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

raw_counts <- data.frame(
  sample_date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend"),
  effort_kind = c("bank", "bank", "bank", "bank"),
  effort_value = c(15, 23, 45, 52)
)

counts_ready <- prep_counts_daily_effort(
  raw_counts,
  date = sample_date,
  strata = day_type,
  effort_type = effort_kind,
  daily_effort = effort_value
)

design_with_counts <- add_counts(design, counts_ready)
print(design_with_counts)

# Compatibility path: raw count rows with a custom PSU column
counts_with_site_psu <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend"),
  site_day = paste0("site_", 1:4),
  count = c(15, 23, 45, 52)
)

design2 <- add_counts(design, counts_with_site_psu, psu = "site_day")

# Compatibility path: multiple counts per day (within-day variance via count_time_col)
# Two circuits per day: "am" and "pm"
calendar2 <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design3 <- creel_design(calendar2, date = date, strata = day_type)

multi_counts <- data.frame(
  date = as.Date(rep(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04"), each = 2)),
  day_type = rep(c("weekday", "weekday", "weekend", "weekend"), each = 2),
  count_time = rep(c("am", "pm"), 4),
  n_anglers = c(12, 18, 20, 26, 40, 50, 48, 56)
)
design_multi <- add_counts(design3, multi_counts,
  count_time_col = count_time # nolint: object_usage_linter
)

# Compatibility path: progressive count type (Ê_d = C x circuit_time x kappa)
calendar3 <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design4 <- creel_design(calendar3, date = date, strata = day_type)

prog_counts <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend"),
  n_anglers = c(15L, 23L, 45L, 52L),
  shift_hours = rep(8, 4)
)
design_prog <- add_counts(
  design4, prog_counts,
  count_type = "progressive",
  circuit_time = 2,
  period_length_col = shift_hours # nolint: object_usage_linter
)

Attach interview data to a creel design

Description

Attaches interview-side trip data (catch, effort, and optionally harvest per fishing trip) to a creel_design object and constructs the internal interview survey design object eagerly. The preferred workflow is to standardize raw interview exports into canonical trip rows with prep_interviews_trips() before calling add_interviews(), and to standardize species-level catch detail with prep_interview_catch() before calling add_catch().

add_interviews() still supports direct attachment of raw-ish interview data with tidy selectors for catch, effort, and trip metadata. This keeps current workflows working while making the prep-helper seam explicit.

Usage

add_interviews(
  design,
  interviews,
  catch,
  effort,
  harvest = NULL,
  trip_status,
  trip_duration = NULL,
  trip_start = NULL,
  interview_time = NULL,
  n_counted = NULL,
  n_interviewed = NULL,
  angler_type = NULL,
  angler_method = NULL,
  species_sought = NULL,
  n_anglers = 1L,
  refused = NULL,
  date_col = NULL,
  interview_type = c("access", "roving"),
  allow_invalid = FALSE
)

Arguments

Value

A new creel_design object (list) with components:

Immutability

add_interviews() follows functional programming patterns and returns a new creel_design object. The original design object is not modified. This prevents accidental data loss and makes the workflow explicit: design2 <- add_interviews(design, interviews, ...) not add_interviews(design, interviews, ...)

Validation

add_interviews() performs Tier 1 validation:

• Interview data schema (Date column, numeric columns) via validate_interview_schema()

• Design column presence (date_col exists in interview data)

• No NA values in date column

• Interview dates exist in design calendar

• Catch and effort columns exist and are numeric

• Harvest column exists and is numeric (if provided)

• Harvest <= catch consistency (if harvest provided)

• Trip status valid ("complete" or "incomplete", case-insensitive)

• Trip status has no NA values

• Trip duration/time inputs are mutually exclusive (error if both provided)

• Trip duration is positive, >= 1 minute, warns if > 48 hours

• Trip start + interview_time are POSIXct/POSIXlt, calculate valid duration

• Interview survey construction (catches stratification issues)

Calendar Integration

Interview dates are automatically linked to the design calendar via date matching. Strata from the calendar are inherited by the interview data, enabling stratified estimation of catch rates.

See Also

Other "Survey Design": add_catch(), add_counts(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

# Preferred workflow: standardize interview rows before attachment
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

raw_interviews <- data.frame(
  survey_date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  catch_total = c(5, 3, 7, 2),
  hours_fished = c(2.0, 2.5, 3.0, 1.5),
  trip_status = c("complete", "complete", "incomplete", "complete"),
  trip_duration = c(2.0, 2.5, 1.5, 1.5),
  interview_id = 1:4
)

interviews_ready <- prep_interviews_trips(
  raw_interviews,
  date = survey_date,
  interview_uid = interview_id,
  effort_hours = hours_fished,
  trip_status = trip_status,
  trip_duration = trip_duration,
  catch_total = catch_total
)

design_with_interviews <- add_interviews(
  design, interviews_ready,
  catch = catch_total,
  effort = effort_hours,
  trip_status = trip_status,
  trip_duration = trip_duration
)
print(design_with_interviews)

# Compatibility path: direct attachment with harvest column and timestamps
interviews2 <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  catch_total = c(5, 3, 7, 2),
  catch_kept = c(2, 1, 5, 2),
  hours_fished = c(2.0, 2.5, 3.0, 1.5),
  trip_status = c("complete", "incomplete", "complete", "complete"),
  trip_start = as.POSIXct(c(
    "2024-06-01 08:00", "2024-06-02 09:00",
    "2024-06-03 07:00", "2024-06-04 10:00"
  )),
  interview_time = as.POSIXct(c(
    "2024-06-01 10:00", "2024-06-02 11:30",
    "2024-06-03 10:00", "2024-06-04 11:30"
  ))
)

design2 <- add_interviews(
  design, interviews2,
  catch = catch_total,
  effort = hours_fished,
  harvest = catch_kept,
  trip_status = trip_status,
  trip_start = trip_start,
  interview_time = interview_time
)

Attach fish length frequency data to a creel design

Description

Attaches a long-format data frame of fish length measurements to a creel_design object. Supports both individual measurements (harvest) and binned counts (release). Data is validated at attach time and stored on the design for use by downstream summary and estimation functions.

Usage

add_lengths(
  design,
  data,
  length_uid,
  interview_uid,
  species,
  length,
  length_type,
  count = NULL,
  release_format = "individual"
)

Arguments

Details

Mixed column type footgun: The length column may contain both numeric values (harvest rows) and character bin labels (release rows). R will coerce the entire column to character when mixing types in a data.frame. add_lengths() validates harvest row lengths by subsetting to harvest rows first, then attempting as.numeric() coercion, to avoid errors from the mixed-type column.

Interview ID validation: Every interview ID appearing in data must appear in design$interviews[[interview_uid]]. Interviews with no length rows are valid.

Immutability: Returns a new creel_design — the input is not modified. Calling add_lengths() on a design that already has $lengths is an error.

Value

A new creel_design object with $lengths and associated $lengths_*_col fields attached.

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

data(example_calendar)
data(example_interviews)
data(example_lengths)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status, trip_duration = trip_duration
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  length = length,
  length_type = length_type,
  count = count,
  release_format = "binned"
)
print(design)

Register spatial sections for a creel survey design

Description

Attaches a sections registry to a creel_design object. Once sections are registered, all subsequent calls to add_counts() and add_interviews() validate that every row's section value matches a registered section name. Unrecognised section values abort with an informative error identifying the bad values and listing valid options.

add_sections() is optional for single-section surveys. Call it when your survey covers multiple named sections and you want early detection of mislabelled data (e.g. "NRTH" instead of "NORTH").

Usage

add_sections(
  design,
  sections,
  section_col,
  description_col = NULL,
  area_col = NULL,
  shoreline_col = NULL
)

Arguments

Value

A new creel_design object with ⁠$sections⁠ and ⁠$section_col⁠ populated. The input design is not modified.

Validation performed by downstream functions

After add_sections() is called, add_counts() and add_interviews() check that every row's section value is present in design$sections[[design$section_col]]. An unrecognised value produces a cli_abort() naming the bad values and listing valid section names.

How sections are named in results

Every sectioned estimate reports its sections in a column named after section_col, as a design declaring strata = day_type reports a day_type column. Register sections under reach and the result's first column is reach, so it joins back to your own section table by name. Read it as est[[design$section_col]] rather than assuming a fixed name (#282).

The lake-wide aggregate row, where requested, is a value in that same column – the reserved name .lake_total – not a separate column.

See Also

creel_design(), add_counts(), add_interviews()

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

cal <- data.frame(
  date = as.Date(c(
    "2024-06-01", "2024-06-02",
    "2024-06-03", "2024-06-04"
  )),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(cal, date = date, strata = day_type)

my_sections <- data.frame(
  section      = c("North Inlet", "Main Basin", "South Outlet"),
  description  = c("Tributary inlet", "Open water", "Dam outlet"),
  area_ha      = c(45.0, 820.0, 12.0),
  shoreline_km = c(8.2, 62.1, 3.4)
)

design2 <- add_sections(design, my_sections,
  section_col     = section,
  description_col = description,
  area_col        = area_ha,
  shoreline_col   = shoreline_km
)

Adjust a creel design for nonresponse bias

Description

Applies nonresponse weighting to a creel_design object by scaling survey weights within each stratum by the inverse of the observed response rate. The adjustment uses postStratify (default) or calibrate to update the internal svydesign object, so all downstream estimators (estimate_effort, estimate_catch_rate, etc.) automatically use the corrected weights.

Usage

adjust_nonresponse(
  design,
  response_rates,
  method = c("postStratify", "calibrate"),
  stratum_col = "stratum"
)

Arguments

Value

The input creel_design with adjusted weights. The updated design includes an attribute "nonresponse_diagnostics" (a tibble with columns stratum, n_sampled, n_responded, response_rate, weight_adjustment) that can be retrieved with attr(result, "nonresponse_diagnostics").

Adjustment method

For each stratum h:

response\_rate_h = n\_responded_h / n\_sampled_h

weight\_adjustment_h = 1 / response\_rate_h

The original weights are multiplied by weight_adjustment_h, which upweights respondents to represent non-respondents (Armstrong & Overton 1977). This assumes that respondents and non-respondents are exchangeable within strata (a missing-at-random assumption). When this is implausible, a sensitivity analysis comparing pre- and post-adjustment estimates is recommended.

References

Armstrong, B.G. and Overton, W.S. 1977. Estimating nonresponse bias in mail surveys. Journal of Marketing Research 14:396–402.

Pollock, K.H., Jones, C.M. and Brown, T.L. 1994. Angler Survey Methods and Their Applications in Fisheries Management. American Fisheries Society, Bethesda, MD.

See Also

Other "Reporting & Diagnostics": check_completeness(), compare_variance(), flag_outliers(), season_summary(), standardize_species(), summarize_boat_composition(), summarize_by_angler_type(), summarize_by_county(), summarize_by_day_type(), summarize_by_method(), summarize_by_species_sought(), summarize_by_trip_length(), summarize_by_zip(), summarize_cws_rates(), summarize_hws_rates(), summarize_length_freq(), summarize_refusals(), summarize_successful_parties(), summarize_trips(), summary.creel_estimates(), tidy.creel_estimates(), validate_creel_data(), validate_design(), validate_incomplete_trips(), validation_report(), write_estimates()

Examples

data("example_counts", package = "tidycreel")
data("example_interviews", package = "tidycreel")
cal <- unique(example_counts[, c("date", "day_type")])
design <- creel_design(cal, date = date, strata = day_type)
design <- suppressWarnings(add_counts(design, example_counts))
design <- suppressWarnings(add_interviews(
  design, example_interviews,
  catch = catch_total, effort = hours_fished,
  trip_status = trip_status, trip_duration = trip_duration
))

resp <- data.frame(
  stratum     = c("weekday", "weekend"),
  n_sampled   = c(80L, 60L),
  n_responded = c(72L, 48L)
)
adj_design <- adjust_nonresponse(design, resp)
attr(adj_design, "nonresponse_diagnostics")

Coerce a creel_data_validation to a plain data frame

Description

Strips the creel_data_validation class, returning the underlying data frame of check results.

Usage

## S3 method for class 'creel_data_validation'
as.data.frame(x, ...)

Arguments

Value

A plain data.frame.

Coerce a creel_design_comparison to a plain data frame

Description

Coerce a creel_design_comparison to a plain data frame

Usage

## S3 method for class 'creel_design_comparison'
as.data.frame(x, ...)

Arguments

Value

A plain data.frame.

Coerce a creel_summary to a data.frame

Description

Coerce a creel_summary to a data.frame

Usage

## S3 method for class 'creel_summary'
as.data.frame(x, ...)

Arguments

Value

A data.frame with human-readable estimate columns.

Coerce a creel_validation_report to a plain data frame

Description

Strips the creel_validation_report class.

Usage

## S3 method for class 'creel_validation_report'
as.data.frame(x, ...)

Arguments

Value

A plain data.frame.

Coerce creel_variance_comparison to data.frame

Description

Coerce creel_variance_comparison to data.frame

Usage

## S3 method for class 'creel_variance_comparison'
as.data.frame(x, ...)

Arguments

Value

A plain data.frame.

Extract internal survey design object for advanced use

Description

Provides power users with direct access to the internal survey.design2 object for advanced analysis using survey package functions. This is an escape hatch for workflows not yet wrapped by tidycreel. Most users should use estimate_effort() instead.

The function issues a once-per-session warning to educate users that this is an advanced feature with risks if the returned object is modified incorrectly.

Usage

as_creel_svydesign(design)

Arguments

Value

A survey.design2 object (from survey::svydesign). Due to R's copy-on-modify semantics, modifications to the returned object will not affect the internal design$survey object.

Warning

This function issues a once-per-session warning explaining:

• This is an advanced feature for power users

• Most users should use estimate_effort() instead

• Modifying the survey design may produce incorrect variance estimates

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

# Basic workflow
library(survey)
cal <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(cal, date = date, strata = day_type)

counts <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend"),
  count = c(15, 23, 45, 52)
)

design2 <- add_counts(design, counts)

# Extract survey object for advanced use
svy <- as_creel_svydesign(design2)

# Use with survey package functions
survey::svytotal(~count, svy)
survey::svymean(~count, svy)

Combine disjoint count frames into one stratified survey design

Description

Usage

as_hybrid_svydesign(
  counts,
  frame_col,
  calendar = NULL,
  date_col = "date",
  strata_col = "day_type",
  count_col = "count",
  fraction = NULL,
  trips_disjoint = NULL,
  fpc = TRUE
)

Arguments

Details

Combines two or more count series covering disjoint parts of one fishery into a single survey::svydesign object. The frames are treated as strata, each carrying its own within-day sampling fraction, and all expanded to the same population of days, so the design total is the stratified sum of the frame totals over the season.

Estimand. The design estimates a period total – the total over every day in calendar, not over the days that happened to be sampled. Two expansions get it there, and both live in the row weight: the within-day fraction expands the part of the frame that the count enumerated to the whole of it, and N_h / n_h expands the sampled days to the days the stratum holds. Only the second is a stage-1 sampling fraction, so only the second drives the finite-population correction.

Disjointness precondition. Adding the frame totals is valid if and only if the frames sample disjoint sets of angler trips – no angler trip may be observed by more than one. What produces that disjointness is a property of the survey protocol (angler type, geography, access mode, or a rule the designer imposes); tidycreel cannot infer it from the counts, the dates, the strata, or the frame labels, so you must affirm it with trips_disjoint = TRUE. The design cannot be constructed otherwise. A boat angler intercepted on the water by a roving route and again at the ramp on the same trip belongs to two frames, and the total double counts that trip.

What a frame is. A frame is a disjoint part of the fishery, enumerated by its own count. In the protocol this design was built for the frames are angler-type domains – boat anglers, and bank anglers dispersed along a shoreline with no well-defined access site (Malvestuto 1996). Pope et al. (Chapter 17) carry exactly this as an anglerType column alongside the stratum, and estimate effort by stratum and angler type; frame_col is that column.

The frame is not an interview mode. In the creel literature access and roving describe how anglers are interviewed: access interviews intercept completed trips as anglers leave, roving interviews intercept incomplete trips while anglers are still fishing, and the two require different catch-rate estimators (Pollock et al. 1994). A survey mixing the two is a hybrid interview design. Counts are not described that way at all – they are instantaneous, progressive, bus-route, camera or aerial, the values creel_schema() accepts for survey_type. tidycreel carries the interview axis on add_interviews()'s interview_type argument, which is where it belongs. Earlier versions of this function named its arguments access_data and roving_data, which borrowed the interview vocabulary for something that is not an interview mode (GH #248).

Estimation route. The returned object is a survey.design2, not a creel_design(), so estimate_effort() does not accept it. Estimate from it with survey::svytotal() and the other survey functions directly, as in the examples below.

Design structure. Rows are stratified on the interaction of strata_col and frame_col, so each count frame carries its own sampled-day count at its own within-day fraction, and clustered on date_col, so the date is the primary sampling unit. The population size is taken from calendar and is shared by every frame: one stratum is one span of the season, whichever frame observed it. A frame that sampled only one date within a stratum leaves that stratum with a single PSU: the design still constructs, but survey refuses to compute a variance for it.

One count row per frame-day. A day-level expansion is only defined when a sampled day is one row per frame, so repeated counts on one date within a frame are refused. Two counts on a date are two looks at that date, not two sampled days; summed, they multiply the total by the number of counts, and the day expansion then multiplies that again. Average them to one row per date before constructing the design, or model them on a path that keeps the count time.

PSU alignment requirement: every frame should sample the same date-stratum combinations. A warning is issued when coverage is asymmetric, because the frames should sample the same days. That is a requirement about when each frame samples, not where – frames covering different water is the condition that makes their sum valid, not a source of bias.

Value

A survey::svydesign object with an additional class attribute "creel_hybrid_svydesign". The design data carries the frame_col column unchanged, a weight column holding both the within-day and the day-to-season expansion, a .hybrid_stratum column holding the stratum-by-frame interaction the design is stratified on, and a .pop_days column holding the stratum population N_h the finite-population correction is taken against. attr(design, "component_col") names the frame column.

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

calendar <- data.frame(
  date = seq(as.Date("2024-06-01"), as.Date("2024-06-30"), by = "day")
)
calendar$day_type <- ifelse(
  format(calendar$date, "%u") %in% c("6", "7"), "weekend", "weekday"
)

counts <- data.frame(
  date = rep(
    as.Date(c("2024-06-03", "2024-06-04", "2024-06-08", "2024-06-09")),
    times = 2
  ),
  day_type = rep(c("weekday", "weekday", "weekend", "weekend"), times = 2),
  angler_type = rep(c("boat", "bank"), each = 4),
  count = c(12L, 15L, 30L, 28L, 8L, 10L, 22L, 25L)
)
design <- as_hybrid_svydesign(
  counts,
  frame_col      = "angler_type",
  calendar       = calendar,
  fraction       = list(
    boat = c(weekday = 0.5, weekend = 0.5),
    bank = c(weekday = 0.4, weekend = 0.4)
  ),
  trips_disjoint = TRUE
)

# estimate_effort() does not accept this object; use survey directly
survey::svytotal(~count, design)

Extract internal survey design object (deprecated)

Description

as_survey_design() was renamed to as_creel_svydesign() in tidycreel 5.0.0. The old name collided with srvyr::as_survey_design(), srvyr's principal entry point: attaching both packages masked one with the other depending on load order, and a user who loaded srvyr second got srvyr's generic failing to dispatch on creel_design with an error that said nothing about masking. The new name also matches the sibling as_hybrid_svydesign() and is more accurate – the function extracts the internal survey object rather than constructing a design.

Usage

as_survey_design(design)

Arguments

Value

A survey.design2 object, identical to as_creel_svydesign().

Examples

data(example_calendar)
data(example_counts)
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
# Deprecated: as_creel_svydesign() is the current name.
svy <- suppressWarnings(as_survey_design(design))
class(svy)

Attach count time windows to a daily sampling schedule

Description

Cross-joins a daily schedule produced by generate_schedule() with a count-time template produced by generate_count_times(), returning a creel_schedule with one row per (date x period x count_window).

Usage

attach_count_times(schedule, count_times)

Arguments

Value

A creel_schedule data frame with all columns from schedule plus start_time, end_time, and window_id from count_times. Row count equals nrow(schedule) * nrow(count_times).

See Also

Other "Scheduling": generate_bus_schedule(), generate_count_times(), generate_progressive_start(), generate_schedule(), new_creel_schedule(), read_schedule(), validate_creel_schedule(), write_schedule()

Examples

sched <- generate_schedule(
  start_date = "2024-06-01", end_date = "2024-06-07",
  n_periods = 2, sampling_rate = 0.5, seed = 1
)
ct <- generate_count_times(
  start_time = "06:00", end_time = "14:00",
  strategy = "systematic", n_windows = 3,
  window_size = 30, min_gap = 10, seed = 1
)
attach_count_times(sched, ct)

Audit per-stratum effort precision from a completed creel design or pilot statistics

Description

audit_strata() is an S3 generic. Two methods are provided:

• audit_strata.creel_design() extracts stratum summaries from a completed design object and computes per-stratum RSE, DEFF, and meets-target flag.

• audit_strata.default() accepts pilot summary statistics (N_h, n_h, ybar_h, s2_h) directly.

Usage

audit_strata(x, ...)

## S3 method for class 'creel_design'
audit_strata(x, rse_target = 0.2, ...)

## Default S3 method:
audit_strata(x, n_h, ybar_h, s2_h, rse_target = 0.2, ...)

Arguments

Details

The per-stratum RSE (relative standard error, equivalent to CV) is computed with the finite-population correction (FPC):

RSE_h = sqrt((1 - n_h / N_h) * s2_h / n_h) / ybar_h

When n_h = 1 for any stratum, var() cannot be estimated; RSE, DEFF, and meets_target are set to NA for those strata and a warning is issued. The function continues processing valid strata.

The per-stratum design effect (DEFF_h) compares the actual stratum variance to the pooled-SRS variance baseline:

DEFF_h = ((1 - n_h/N_h) * s2_h / n_h) / ((1 - n/N) * s2_overall / n)

where n = sum(n_h), N = sum(N_h), and s2_overall = sum(N_h * s2_h) / sum(N_h) (N_h-weighted pooled within-stratum variance). The aggregate DEFF stored in ⁠$deff⁠ is Var_strat / Var_SRS (Cochran 1977).

Value

A creel_strata_audit S3 object. See audit_strata.default() for the complete field description.

A creel_strata_audit S3 object — a named list with fields:

⁠$strata⁠

Tibble with columns: stratum, N_h, n_h, ybar_h, s2_h, RSE, DEFF, meets_target.

⁠$rse_target⁠

Scalar. The RSE threshold supplied by the caller.

⁠$n_total⁠

Integer. Total sampled days across all strata.

⁠$deff⁠

Scalar. Aggregate design effect (Var_strat / Var_SRS).

References

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York.

McCormick, J.L. and Quist, M.C. 2017. Sample size estimation for on-site creel surveys. North American Journal of Fisheries Management 37:970-983. doi:10.1080/02755947.2017.1342723

See Also

Other "Planning & Sample Size": compare_designs(), creel_n_camera(), creel_n_cpue(), creel_n_effort(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Other "Planning & Sample Size": compare_designs(), creel_n_camera(), creel_n_cpue(), creel_n_effort(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# Two-stratum weekday/weekend pilot example
audit <- audit_strata(
  c(weekday = 65, weekend = 28),
  n_h    = c(weekday = 22, weekend = 14),
  ybar_h = c(50, 60),
  s2_h   = c(400, 500),
  rse_target = 0.20
)
audit$strata
audit$deff

Autoplot a creel_design_comparison as a forest plot

Description

Renders a forest plot showing point estimates with confidence intervals for each design, coloured by design name.

Usage

## S3 method for class 'creel_design_comparison'
autoplot(object, title = NULL, ...)

Arguments

Value

A ggplot object.

Plot creel survey estimates with ggplot2

Description

autoplot.creel_estimates() produces a point-and-errorbar plot from a creel_estimates object. For ungrouped estimates a single point with confidence interval is shown. For grouped estimates (when by was supplied to the estimation function) each group level gets its own point, colour-coded and positioned along the x-axis.

Returns a ggplot2 object, which the package imports, so nothing extra needs installing.

Usage

## S3 method for class 'creel_estimates'
autoplot(object, title = NULL, theme = c("default", "creel"), ...)

Arguments

Value

A ggplot object.

See Also

estimate_effort(), estimate_catch_rate(), summary.creel_estimates()

Other "Visualisation": autoplot.creel_length_distribution(), autoplot.creel_schedule(), creel_palette(), plot_design(), theme_creel()

Examples

data(example_calendar)
data(example_counts)
data(example_interviews)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)

est <- estimate_effort(design)
ggplot2::autoplot(est)

est_grp <- estimate_effort(design, by = day_type)
ggplot2::autoplot(est_grp)

Plot a weighted length distribution with ggplot2

Description

autoplot.creel_length_distribution() renders weighted length-frequency estimates as a histogram-style bar chart. Ungrouped results are shown as a single distribution; grouped results are faceted by the grouping variables.

Usage

## S3 method for class 'creel_length_distribution'
autoplot(object, title = NULL, theme = c("default", "creel"), ...)

Arguments

Value

A ggplot object.

See Also

est_length_distribution()

Other "Visualisation": autoplot.creel_estimates(), autoplot.creel_schedule(), creel_palette(), plot_design(), theme_creel()

Examples

data(example_calendar)
data(example_interviews)
data(example_catch)
data(example_lengths)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: length totals are scaled
# onto the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id, interview_uid = interview_id,
  species = species, count = count, catch_type = catch_type
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id, interview_uid = interview_id,
  species = species, length = length, length_type = length_type,
  count = count, release_format = "binned"
)

ld <- est_length_distribution(design, by = species, bin_width = 25)
ggplot2::autoplot(ld)

Plot a creel schedule as a ggplot2 tile calendar

Description

autoplot.creel_schedule() produces a monthly tile calendar showing sampled dates coloured by day type (weekday / weekend) and unsampled dates in grey. Multiple months are shown as faceted panels.

Returns a ggplot2 object, which the package imports, so nothing extra needs installing.

Usage

## S3 method for class 'creel_schedule'
autoplot(object, title = "Creel Schedule", ...)

Arguments

Value

A ggplot object.

See Also

generate_schedule(), print.creel_schedule(), write_schedule()

Other "Visualisation": autoplot.creel_estimates(), autoplot.creel_length_distribution(), creel_palette(), plot_design(), theme_creel()

Examples

sched <- generate_schedule(
  start_date = "2024-06-01", end_date = "2024-07-31",
  n_periods = 1,
  sampling_rate = c(weekday = 0.3, weekend = 0.6),
  seed = 42
)
ggplot2::autoplot(sched)

Check post-season data completeness for a creel design

Description

Dispatches by survey_type to avoid false-positive warnings on aerial and camera designs that do not collect interview data.

Usage

check_completeness(design, n_min = 10L)

Arguments

Value

A creel_completeness_report object (S3 list) with:

$missing_days

data.frame of calendar rows with no count data

$low_n_strata

data.frame of strata below n_min, or NULL for aerial/camera

$refusals

creel_summary_refusals object or NULL

$n_min

integer threshold used

$survey_type

character

$passed

logical – TRUE if no missing days and no low-n strata

See Also

Other "Reporting & Diagnostics": adjust_nonresponse(), compare_variance(), flag_outliers(), season_summary(), standardize_species(), summarize_boat_composition(), summarize_by_angler_type(), summarize_by_county(), summarize_by_day_type(), summarize_by_method(), summarize_by_species_sought(), summarize_by_trip_length(), summarize_by_zip(), summarize_cws_rates(), summarize_hws_rates(), summarize_length_freq(), summarize_refusals(), summarize_successful_parties(), summarize_trips(), summary.creel_estimates(), tidy.creel_estimates(), validate_creel_data(), validate_design(), validate_incomplete_trips(), validation_report(), write_estimates()

Examples

data(example_calendar)
data(example_counts)
data(example_interviews)
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
check_completeness(design)

Compare CPUE estimators (ROM, MOR, Regression)

Description

Runs all three CPUE estimators — Ratio-of-Means (ROM / CPUE_2), Mean-of-Ratios (MOR / CPUE_1), and OLS regression slope with jackknife SE (CPUE_3) — on the same creel design and returns a combined tibble with a cpue_method column for side-by-side comparison.

This implements the Petrere et al. (2010) Table 1 estimator comparison workflow. When the three estimators yield materially different estimates, the choice of estimator matters; compare_cpue_estimators() makes divergence visible.

Usage

compare_cpue_estimators(
  design,
  by = NULL,
  conf_level = 0.95,
  force_origin = TRUE,
  verbose = FALSE
)

Arguments

Details

Estimator definitions following Petrere et al. (2010):

ROM (CPUE_2)

Ratio of means: total catch / total effort (survey::svyratio). Unbiased for complete trips.

MOR (CPUE_1)

Mean of individual ratios: mean(catch_i / effort_i) (survey::svymean). Preferred for incomplete trips.

Regression (CPUE_3)

OLS slope \hat{\beta} from C_i = \beta f_i + \varepsilon_i with leave-one-out jackknife SE. Most robust when proportionality is violated (non-zero intercept).

Value

A tibble with columns cpue_method (character: "rom", "mor", "regression"), plus estimate, se, ci_lower, ci_upper, n, and any grouping columns when by is specified. The tibble has class c("cpue_comparison", "tbl_df", "tbl", "data.frame").

References

Petrere, M. Jr., Giacomini, H.C. & De Marco, P. Jr. (2010). Catch-per-unit-effort: which estimator is best? Braz. J. Biol. 70: 483–491. doi:10.1590/S1519-69842010005000010

See Also

estimate_catch_rate

Other "Estimation": est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

design <- creel_design(example_calendar, date = date, strata = day_type) |>
  add_interviews(example_interviews,
    catch = catch_total, effort = hours_fished,
    trip_status = trip_status, n_anglers = n_anglers
  )

compare_cpue_estimators(design)

Compare multiple survey design estimates side by side

Description

Usage

compare_designs(designs, metric = "estimate")

Arguments

Details

Takes a named list of creel_estimates objects (from different survey designs or methods), extracts key precision metrics from each, and returns a tidy comparison tibble. An autoplot() method renders a forest plot of point estimates with confidence intervals.

Value

A creel_design_comparison object – a data frame with columns:

design

Design name (from names(designs)).

estimate

Point estimate.

se

Standard error.

rse

Relative standard error (⁠se / |estimate|⁠).

ci_lower

Lower confidence interval bound.

ci_upper

Upper confidence interval bound.

ci_width

Width of the confidence interval.

n

Sample size (if present in the estimates frame).

Group columns are retained when all designs share the same by-variable structure.

See Also

autoplot.creel_design_comparison()

Other "Planning & Sample Size": audit_strata(), creel_n_camera(), creel_n_cpue(), creel_n_effort(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

data(example_calendar)
data(example_counts)
data(example_interviews)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)

# Two estimates from the same design: overall, and split by stratum. In
# practice these would come from designs built on different survey types.
est_all <- estimate_effort(design)
est_grp <- estimate_effort(design, by = day_type)

compare_designs(list(overall = est_all, by_day_type = est_grp))

Compare Taylor linearization vs. replicate variance for creel estimates

Description

Takes a creel_estimates object produced with variance = "taylor" and re-estimates using replicate weights (bootstrap or jackknife) to produce a side-by-side comparison of standard errors. A cli_warn() is issued for any row where the two SEs diverge by more than divergence_threshold.

Usage

compare_variance(
  x,
  replicate_method = c("bootstrap", "jackknife"),
  conf_level = 0.95,
  divergence_threshold = 0.1,
  ...
)

Arguments

Value

A creel_variance_comparison S3 object (a tibble subclass) with columns:

se_taylor

Taylor linearization SE from the original estimate.

se_replicate

Replicate-weight SE from the re-estimation.

divergence_ratio

Ratio se_replicate / se_taylor. NA when se_taylor == 0.

diverges_flag

Logical. TRUE when |divergence_ratio - 1| > divergence_threshold.

Group columns (if any) are preserved. The full tibble is returned invisibly via print(). Use as.data.frame() or standard tibble methods for further processing.

Method

The function extracts the Taylor SE from x$estimates$se, then calls the same estimator that produced x (resolved via x$method) with variance = replicate_method. The re-estimation uses x$design and the grouping variables from x$by_vars.

Divergence is computed as:

ratio = se_{replicate} / se_{taylor}

diverges = |ratio - 1| > threshold

A ratio substantially different from 1 indicates that the Taylor approximation may be unreliable for this design (e.g., sparse strata, non-linear estimator). Replication-based variance is generally more robust but slower to compute.

References

Wolter, K.M. 2007. Introduction to Variance Estimation, 2nd ed. Springer.

Lumley, T. 2010. Complex Surveys: A Guide to Analysis Using R. Wiley.

See Also

Other "Reporting & Diagnostics": adjust_nonresponse(), check_completeness(), flag_outliers(), season_summary(), standardize_species(), summarize_boat_composition(), summarize_by_angler_type(), summarize_by_county(), summarize_by_day_type(), summarize_by_method(), summarize_by_species_sought(), summarize_by_trip_length(), summarize_by_zip(), summarize_cws_rates(), summarize_hws_rates(), summarize_length_freq(), summarize_refusals(), summarize_successful_parties(), summarize_trips(), summary.creel_estimates(), tidy.creel_estimates(), validate_creel_data(), validate_design(), validate_incomplete_trips(), validation_report(), write_estimates()

Examples

data("example_counts", package = "tidycreel")
data("example_interviews", package = "tidycreel")
cal <- unique(example_counts[, c("date", "day_type")])
design <- creel_design(cal, date = date, strata = day_type)
design <- suppressWarnings(add_counts(design, example_counts))
design <- suppressWarnings(add_interviews(
  design, example_interviews,
  catch = catch_total, effort = hours_fished,
  trip_status = trip_status, trip_duration = trip_duration
))
taylor_est <- suppressWarnings(estimate_catch_rate(design))
cmp <- suppressWarnings(compare_variance(taylor_est))
print(cmp)

Normalize fishing effort to angler-hours

Description

Multiplies per-trip effort (hours) by party size (number of anglers) to produce angler-hours. This converts party-level effort records to individual-angler units, which are required for CPUE and harvest-rate computations.

This function can be called standalone on a raw data frame or is called internally by add_interviews when constructing the design object.

Usage

compute_angler_effort(data, effort, n_anglers)

Arguments

Value

The input data frame with an added .angler_effort column (numeric, angler-hours). Existing columns are preserved.

See Also

compute_effort(), add_interviews()

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

parties <- data.frame(effort = c(2.0, 3.0), n_anglers = c(2L, 3L))
compute_angler_effort(parties, effort, n_anglers)

Resolve fishing effort from timestamps or self-reported time

Description

Computes fishing effort (hours) for each interview row using a conditional rule: if the time_fished column is present and non-NA for a row, use that value (angler self-reported hours, e.g. after a break); otherwise compute from timestamps as difftime(interview_time, trip_start, units = "hours").

This function can be called standalone on raw data before entering the add_interviews workflow, or used to preprocess a column that will be passed as the effort argument to add_interviews().

Usage

compute_effort(data, trip_start, interview_time, time_fished = NULL)

Arguments

Value

The input data frame with an added .effort column (numeric, hours). Existing columns are preserved.

See Also

compute_angler_effort(), add_interviews()

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

trips <- data.frame(
  trip_start     = as.POSIXct(c("2024-06-01 08:00:00", "2024-06-01 09:15:00")),
  interview_time = as.POSIXct(c("2024-06-01 10:30:00", "2024-06-01 12:00:00"))
)
compute_effort(trips, trip_start, interview_time)

Confidence interval conventions in tidycreel

Description

Estimators in this package do not all build confidence intervals the same way, because the quantities they estimate do not all live on the same scale or carry the same information about their own uncertainty. This topic states the two rules the package follows, so that a new estimator does not have to pick by coin flip.

Bounded quantities

Effort, catch, harvest, release, biomass, abundance and catch rates are all bounded below by zero, and exploitation rate is bounded on both sides. A symmetric Wald interval respects none of that: once the coefficient of variation exceeds roughly 0.51, the lower bound of a 95% interval falls below zero and the estimator reports a value outside the parameter space.

The package handles this in one of two ways, in this order of preference:

1. Transform, where a principled transform for the quantity exists. estimate_exploitation_rate() builds its interval on the logit scale; estimate_angler_n() uses Sadinle's (2009) 0.5 transformed logit interval for Chapman and Petersen \hat{N}; the product-total paths accept ci_type = "log". A transformed interval is right-skewed and cannot cross the boundary in the first place.

2. Clamp at the feasible limit, where no transform is established for the estimator. This is pmax(0, ...) applied to the lower bound, used by the product totals under ci_type = "symmetric" and by every bus-route path.

Clamping is the weaker of the two and is deliberately not treated as equivalent. It keeps the symmetric width that produced the excursion and truncates the result at the boundary, so it stops the package reporting an impossible number but does not repair the skew that made the bound negative. A clamped lower bound of exactly zero should be read as a signal that the interval is wide relative to the estimate, not as a precise statement that the quantity could be zero.

Upper bounds are never clamped: none of these quantities has a finite upper limit that the package knows.

Two quantities are bounded below by something other than zero and are therefore left alone: est_mean_length() and est_mean_age() are bounded by the smallest occupied bin, so a clamp at zero would be the wrong repair.

Quantile choice

Where an estimator has a finite sample size of its own to appeal to, it uses stats::qt() on an explicit degrees-of-freedom rule. The product-total paths use total interviews minus the number of strata; the section paths use the number of sections minus one; mark-recapture uses the number of occasions.

Six estimators use stats::qnorm() instead — est_biomass(), est_mean_length(), est_compliance(), est_mean_age(), and since #310 est_length_distribution() and est_age_distribution() themselves. This is deliberate, not an oversight.

The first four form a linear combination of the rows of a length or age distribution, and their standard error is propagated from the per-bin standard errors those rows already carry. The two distributions joined them when their totals became two-phase: a bin total is no longer a quantity svytotal() returns directly but a delta-method function of the measured bins and the reported total, so its standard error is likewise propagated rather than design-based. (The interval width is unchanged by that switch — survey's confint() method for a svystat defaults to df = Inf, which is the normal quantile.)

In every case there is no local sample size to key a t-quantile to:

• The number of rows is the number of bins, which is a binning choice made by the caller. Keying degrees of freedom to it would make the interval narrow as the bins got finer, with no additional fish measured.

• The row totals are expanded estimates, not counts of measured fish, so their sum is an estimated abundance rather than a sample size.

The honest degrees of freedom belong to the design that produced the upstream standard errors, and the large-sample argument is made there. These four estimators inherit that uncertainty rather than sampling afresh, so the normal quantile is the consistent choice at this level.

estimate_effort_aerial_glmm() is asymptotic by construction and has no finite df to appeal to. The normal quantile inside Sadinle's logit interval is part of the method, not a quantile choice.

References

Sadinle, M. (2009). Transformed logit confidence intervals for small populations in single capture-recapture estimation. Communications in Statistics - Simulation and Computation, 38(9), 1909-1924.

See Also

estimate_effort(), estimate_total_catch(), estimate_harvest_rate(), estimate_exploitation_rate(), estimate_angler_n(), est_biomass(), est_mean_length()

Toy count data for data validation examples

Description

A small creel count data frame designed for demonstrating validate_creel_data() and related data-cleaning functions. Contains an intentional NA in the count column to trigger the NA-rate check.

Usage

creel_counts_toy

Format

A data frame with 6 rows and 4 columns:

date

Survey date (Date class).

day_type

Day type stratum: "weekday" or "weekend".

section

Survey section: "A" or "B".

count

Instantaneous angler count; one row is intentionally NA.

Source

Simulated data for package examples and vignettes.

See Also

creel_interviews_toy

Other "Example Datasets": creel_interviews_toy, example_aerial_counts, example_aerial_glmm_counts, example_aerial_interviews, example_ages, example_calendar, example_camera_counts, example_camera_interviews, example_camera_timestamps, example_catch, example_counts, example_ice_interviews, example_ice_sampling_frame, example_interviews, example_lengths, example_sections_calendar, example_sections_counts, example_sections_interviews

Examples

data(creel_counts_toy)
validate_creel_data(counts = creel_counts_toy)

Create a creel survey design

Description

Constructs a creel_design object from calendar data with tidy column selection. This is the entry point for all creel survey analysis workflows. The design object stores the survey structure (date, strata, optional site), validates input data (Tier 1 validation), and serves as the foundation for adding count data and estimating effort.

For bus-route surveys with nonuniform site selection probabilities, use survey_type = "bus_route" and supply a sampling_frame data frame specifying sites, circuits, and their sampling probabilities.

Usage

creel_design(
  calendar,
  date,
  strata,
  site = NULL,
  design_type = "instantaneous",
  survey_type = design_type,
  sampling_frame = NULL,
  p_site = NULL,
  p_period = NULL,
  circuit = NULL,
  effort_type = NULL,
  camera_mode = NULL,
  h_open = NULL,
  visibility_correction = NULL,
  visibility_se = NULL,
  angler_ratio = NULL,
  angler_ratio_se = NULL,
  open_start = NULL
)

Arguments

Value

A creel_design S3 object (list) with components:

Tier 1 Validation

The constructor performs fail-fast validation:

• Date column is class Date (not character, numeric, POSIXct)

• Date column contains no NA values

• Strata columns are character or factor (not numeric, logical)

• Site column (if provided) is character or factor

• (bus_route only) All p_site and p_period values are in ⁠(0, 1]⁠

• (bus_route only) p_site values sum to 1.0 within each circuit (tolerance 1e-6)

• (bus_route only) p_period values are constant within each circuit (tolerance 1e-10)

References

Jones, C. M., & Pollock, K. H. (2012). Recreational survey methods: estimating effort, harvest, and abundance. In A. V. Zale, D. L. Parrish, & T. M. Sutton (Eds.), Fisheries Techniques (3rd ed., pp. 883–919). American Fisheries Society. Eq. 19.4 and 19.5 define the bus-route estimators; pp. 883–884 define the inclusion probability \pi_i = p_{\text{site}} \times p_{\text{period}}.

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_schema(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

# Basic design with single stratum
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03")),
  day_type = c("weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

# Multiple strata
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02")),
  day_type = c("weekday", "weekend"),
  season = c("summer", "summer")
)
design <- creel_design(calendar, date = date, strata = c(day_type, season))

# With site column for multi-site survey
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02")),
  day_type = c("weekday", "weekend"),
  lake = c("lake_a", "lake_b")
)
design <- creel_design(calendar, date = date, strata = day_type, site = lake)

# Using tidyselect helpers
calendar <- data.frame(
  survey_date = as.Date(c("2024-06-01", "2024-06-02")),
  day_type = c("weekday", "weekend"),
  day_period = c("morning", "evening")
)
design <- creel_design(
  calendar,
  date = starts_with("survey"),
  strata = starts_with("day")
)

# Bus-route design with scalar p_period
calendar_br <- data.frame(
  date = as.Date("2024-06-01"),
  day_type = "weekday"
)
sf <- data.frame(
  site = c("A", "B", "C"),
  p_site = c(0.3, 0.4, 0.3),
  p_period = 0.5
)
design_br <- creel_design(
  calendar_br,
  date = date,
  strata = day_type,
  survey_type = "bus_route",
  sampling_frame = sf,
  site = site,
  p_site = p_site,
  p_period = p_period
)

Toy interview data for data validation examples

Description

A small creel interview data frame with intentional data quality issues for demonstrating validate_creel_data() and standardize_species(). Includes an empty species string, a negative fish_kept value, and a missing trip_hours value.

Usage

creel_interviews_toy

Format

A data frame with 6 rows and 5 columns:

date

Interview date (Date class).

day_type

Day type stratum: "weekday" or "weekend".

species

Free-text species name; includes empty string and unrecognised value to demonstrate standardize_species() behaviour.

fish_kept

Number of fish kept; one row is intentionally negative.

trip_hours

Trip duration in hours; one row is intentionally NA.

Source

Simulated data for package examples and vignettes.

See Also

creel_counts_toy

Other "Example Datasets": creel_counts_toy, example_aerial_counts, example_aerial_glmm_counts, example_aerial_interviews, example_ages, example_calendar, example_camera_counts, example_camera_interviews, example_camera_timestamps, example_catch, example_counts, example_ice_interviews, example_ice_sampling_frame, example_interviews, example_lengths, example_sections_calendar, example_sections_counts, example_sections_interviews

Examples

data(creel_interviews_toy)
validate_creel_data(interviews = creel_interviews_toy)
standardize_species(creel_interviews_toy, species_col = "species")

Calculate camera-days required to achieve a target CV

Description

Uses the stratified sample size formula from Cochran (1977) to determine how many camera-days are needed to achieve a target coefficient of variation on the camera-effort estimate, given pilot mean and variance estimates per day-type stratum.

Usage

creel_n_camera(cv_target, N_h, ybar_h, s2_h)

Arguments

Details

Implements Cochran (1977) equation 5.25 under proportional allocation. The finite-population correction (FPC) factor is intentionally omitted (standard practice for pre-season planning where the goal is to determine how many days to deploy cameras, not to assess precision of a completed survey).

The per-stratum sample sizes n_h are computed from the total n_total under proportional allocation: n_h = ceiling(n_total * N_h / sum(N_h)). Because each stratum is ceiling-ed independently, sum(n_h) may exceed n_total.

Feltz-Middaugh (2025) empirical benchmark. That study reports the camera-day schedules at which a low-frequency time-lapse deployment performed acceptably. Its two headline scenarios are, per month:

• well-performing (under 20 percent error in at least 80 percent of simulations): 12 weekdays and 7 weekend days, both at 1 count/day;

• best-performing (under 10 percent error in at least 80 percent of simulations): 18 weekdays at 2 counts/day and 8 weekend days at 4 counts/day.

These are reported here as design context, not applied as a check. The function cannot judge a computed n_h against them: N_h is the whole survey period rather than a month, nothing here knows the counts per day the schedule assumes, the error bands are fixed by the study rather than taken from cv_target, and the simulations measured boat-trailer counts on six Arkansas reservoirs, whereas ybar_h and s2_h are whatever the caller piloted. Compare against them by hand, after converting to the same units.

Earlier versions warned when n_h fell below 12 or 7, choosing which benchmark to apply by matching the substring "weekday" or "weekend" in the stratum name. That comparison was between a period-scale allocation and a per-month recommendation, so it under-fired by roughly the number of months in the survey (#234). No sample size ever changed: the check only ever emitted a warning.

Value

A named integer vector. Elements named after strata in N_h give the camera-days required per stratum; element "total" gives Cochran's overall sample size before proportional allocation, and "allocated" the sum of the per-stratum values actually returned. Budget against "allocated"; see creel_n_effort() for why the two differ.

References

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York.

Feltz, C.J. and Middaugh, C.R. 2025. Improving efficiency of estimating angler effort using low-frequency time-lapse camera data. North American Journal of Fisheries Management 45:322-332.

See Also

creel_n_effort() for the equivalent function for angler-contact sampling days.

Other "Planning & Sample Size": audit_strata(), compare_designs(), creel_n_cpue(), creel_n_effort(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# Two-stratum weekday/weekend example
creel_n_camera(
  cv_target = 0.20,
  N_h = c(weekday = 65, weekend = 28),
  ybar_h = c(15, 20),
  s2_h = c(625, 900)
)

Calculate interviews required to achieve a target CV on CPUE

Description

Determines the number of interviews needed to achieve a target coefficient of variation on a CPUE (catch-per-unit-effort) ratio estimate, using the ratio-estimator variance approximation from Cochran (1977).

Usage

creel_n_cpue(cv_catch, cv_effort, rho = 0, cv_target)

Arguments

Details

Implements the ratio-estimator variance approximation from Cochran (1977, Chapter 6) parameterised in terms of coefficients of variation rather than raw variances, which is more natural for pre-season planning:

n = \left\lceil \frac{CV_{catch}^2 + CV_{effort}^2 - 2 \rho \cdot CV_{catch} \cdot CV_{effort}}{CV_{target}^2} \right\rceil

Setting rho = 0 (the default) is conservative: it over-estimates the required sample size when catch and effort are positively correlated. Users with pilot data should supply the observed correlation to obtain a less conservative estimate.

The result is floored at 1L to ensure at least one interview is recommended.

Value

An integer scalar (>= 1): number of interviews required.

References

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York. Chapter 6 (ratio estimator variance approximation).

See Also

Other "Planning & Sample Size": audit_strata(), compare_designs(), creel_n_camera(), creel_n_effort(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# rho = 0 (conservative, no pilot correlation data)
creel_n_cpue(cv_catch = 0.8, cv_effort = 0.5, rho = 0, cv_target = 0.20)

# With known positive correlation (smaller n)
creel_n_cpue(cv_catch = 0.8, cv_effort = 0.5, rho = 0.5, cv_target = 0.20)

Calculate sampling days required to achieve a target CV on effort

Description

Uses the stratified sample size formula from McCormick & Quist (2017) to determine how many sampling days are needed to achieve a target coefficient of variation on the effort estimate, given pilot variance estimates per day-type stratum.

Usage

creel_n_effort(cv_target, N_h, ybar_h, s2_h)

Arguments

Details

Implements Cochran (1977) equation 5.25 under proportional allocation, as applied to creel surveys by McCormick & Quist (2017). The finite-population correction (FPC) factor is intentionally omitted (standard practice for pre-season planning where the goal is to determine how many days to sample, not to assess precision of a completed survey).

The per-stratum sample sizes n_h are computed from the total n_total under proportional allocation: n_h = ceiling(n_total * N_h / sum(N_h)). Because each stratum is ceiling-ed independently, sum(n_h) may exceed n_total.

Value

A named integer vector. Elements named after strata in N_h give the sampling days required per stratum; element "total" gives Cochran's overall sample size before proportional allocation, and "allocated" the sum of the per-stratum values actually returned.

"allocated" is the number of sampling days the returned allocation commits to, and is the one to budget against. It is greater than or equal to "total": each stratum is rounded up independently, so the parts can sum to as much as k - 1 more than the unallocated optimum for k strata. Rounding up is deliberate – it keeps every stratum at or better than its share of cv_target.

References

McCormick, J.L. and Quist, M.C. 2017. Sample size estimation for on-site creel surveys. North American Journal of Fisheries Management 37:970-983. doi:10.1080/02755947.2017.1342723

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York.

See Also

Other "Planning & Sample Size": audit_strata(), compare_designs(), creel_n_camera(), creel_n_cpue(), creel_power(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# Two-stratum weekday/weekend example
creel_n_effort(
  cv_target = 0.20,
  N_h = c(weekday = 65, weekend = 28),
  ybar_h = c(50, 60),
  s2_h = c(400, 500)
)

Package-standard colour palette for tidycreel plots

Description

creel_palette() returns a small set of package-standard colours derived from the tidycreel site palette. Use these colours directly in custom plots or pair them with theme_creel() for a consistent visual style.

Usage

creel_palette(n = NULL)

Arguments

Value

When n is NULL, a named character vector of hex colours. Otherwise, a character vector of length n recycling through the base palette as needed.

See Also

Other "Visualisation": autoplot.creel_estimates(), autoplot.creel_length_distribution(), autoplot.creel_schedule(), plot_design(), theme_creel()

Examples

creel_palette()
creel_palette(3)

Estimate statistical power to detect a change in CPUE between seasons

Description

Calculates the probability of detecting a fractional change in CPUE given a target sample size per season, a historical CV, and a significance level. Uses a two-sample normal approximation with equal group sizes.

Usage

creel_power(
  n,
  cv_historical,
  delta_pct,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided")
)

Arguments

Details

Implements the two-sample normal approximation for power under equal group sizes, parameterised in terms of the CV:

ncp = |\delta| \cdot \sqrt{n/2} \, / \, CV_{historical}

For alternative = "two.sided":

power = \Phi(ncp - z_{\alpha/2}) + \Phi(-ncp - z_{\alpha/2})

For alternative = "one.sided":

power = \Phi(ncp - z_{\alpha})

where delta is the fractional effect size (delta_pct), n is the number of interviews per season, and CV_historical is the pilot CV of CPUE.

A warning is issued when delta_pct > 5 because values greater than 5 are almost certainly input in percentage-point form rather than fractional form (e.g., 20 instead of 0.20).

Value

A numeric scalar in (0, 1): estimated statistical power.

References

Cohen, J. 1988. Statistical Power Analysis for the Behavioral Sciences, 2nd ed. Lawrence Erlbaum Associates, Hillsdale, NJ.

See Also

Other "Planning & Sample Size": audit_strata(), compare_designs(), creel_n_camera(), creel_n_cpue(), creel_n_effort(), cv_from_n(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# Two-sided power at n = 100, CV = 0.5, 20 percent change
creel_power(n = 100, cv_historical = 0.5, delta_pct = 0.20)

# One-sided test (higher power for same inputs)
creel_power(n = 100, cv_historical = 0.5, delta_pct = 0.20, alternative = "one.sided")

Column-mapping contract for tidycreel data sources

Description

creel_schema() constructs a creel_schema S3 object that maps canonical tidycreel column names to actual column and table names in a data source. The schema is the full connection contract consumed by creel_connect() and ⁠fetch_*()⁠ functions in the tidycreel.connect companion package.

Construction is permissive — all column arguments default to NULL. Use validate_creel_schema() to check that required columns for the given survey type are mapped.

Usage

creel_schema(
  survey_type = c("instantaneous", "bus_route", "ice", "camera", "aerial"),
  interviews_table = NULL,
  counts_table = NULL,
  catch_table = NULL,
  lengths_table = NULL,
  date_col = NULL,
  strata_cols = NULL,
  value_maps = NULL,
  catch_col = NULL,
  effort_col = NULL,
  trip_status_col = NULL,
  count_col = NULL,
  count_time_col = NULL,
  catch_uid_col = NULL,
  interview_uid_col = NULL,
  species_col = NULL,
  catch_count_col = NULL,
  catch_type_col = NULL,
  length_uid_col = NULL,
  length_mm_col = NULL,
  length_bin_col = NULL,
  length_count_col = NULL,
  length_type_col = NULL,
  harvest_col = NULL,
  trip_duration_col = NULL,
  trip_start_col = NULL,
  interview_time_col = NULL,
  n_anglers_col = NULL,
  n_counted_col = NULL,
  n_interviewed_col = NULL,
  bank_anglers_col = NULL,
  angler_boats_col = NULL,
  non_ang_boats_col = NULL,
  angler_type_col = NULL,
  site_col = NULL,
  circuit_col = NULL,
  angler_method_col = NULL,
  species_sought_col = NULL,
  refused_col = NULL,
  harvest_lengths_table = NULL,
  release_lengths_table = NULL
)

Arguments

Value

A creel_schema S3 object.

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_vocabulary(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

s <- creel_schema(
  survey_type      = "instantaneous",
  interviews_table = "vwInterviews",
  counts_table     = "vwCounts",
  date_col         = "SurveyDate",
  catch_col        = "TotalCatch",
  effort_col       = "EffortHours",
  trip_status_col  = "TripStatus",
  count_col        = "AnglerCount"
)
print(s)

Canonical vocabularies for the coded columns

Description

The exact values tidycreel matches on for the three columns whose meaning is a fixed vocabulary rather than a number: trip_status, catch_type and length_type. Every downstream filter compares against these literals, so a source that codes one of these columns has to be translated before its values can be trusted — see the value_maps argument of creel_schema().

Exported because tidycreel.connect translates source codes at the fetch and has to check its targets against the same list this package filters on; a second copy of the vocabulary would be free to drift from this one.

Usage

creel_vocabulary(column = NULL)

Arguments

Value

A named list of character vectors, or one character vector when column is given.

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), derive_angler_count(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

creel_vocabulary()
creel_vocabulary("trip_status")

Compute the expected CV achievable with a known sample size

Description

Calculates the coefficient of variation attainable given a fixed sample size, acting as the algebraic inverse of creel_n_effort() (when type = "effort") or creel_n_cpue() (when type = "cpue").

Usage

cv_from_n(type = c("effort", "cpue"), n, ...)

Arguments

Details

Effort branch (type = "effort"):

CV = \frac{\sqrt{N \sum_h N_h s_h^2 / n}}{\sum_h N_h \bar{y}_h}

where N = \sum_h N_h.

This is the inverse of the Cochran (1977) stratified sample-size formula implemented in creel_n_effort().

CPUE branch (type = "cpue"):

CV = \sqrt{(CV_{catch}^2 + CV_{effort}^2 - 2\rho \cdot CV_{catch} \cdot CV_{effort}) / n}

This is the inverse of the ratio-estimator formula implemented in creel_n_cpue().

Because creel_n_effort() and creel_n_cpue() apply ceiling(), the round-trip property is ⁠cv_from_n(type, n = creel_n_*(cv, ...), ...) <= cv⁠ (the recovered CV is at or below the target).

Value

A numeric scalar (> 0): the expected CV achievable at sample size n.

References

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York.

See Also

creel_n_effort(), creel_n_cpue()

Other "Planning & Sample Size": audit_strata(), compare_designs(), creel_n_camera(), creel_n_cpue(), creel_n_effort(), creel_power(), optimal_n(), power_creel(), reallocate_strata(), simulate_strata_collapse()

Examples

# Effort round-trip
n_days <- creel_n_effort(0.20,
  N_h = c(weekday = 65, weekend = 28),
  ybar_h = c(50, 60), s2_h = c(400, 500)
)
cv_from_n("effort",
  n = n_days[["total"]],
  N_h = c(weekday = 65, weekend = 28),
  ybar_h = c(50, 60), s2_h = c(400, 500)
)

# CPUE round-trip
n_int <- creel_n_cpue(cv_catch = 0.8, cv_effort = 0.5, rho = 0, cv_target = 0.20)
cv_from_n("cpue", n = n_int, cv_catch = 0.8, cv_effort = 0.5, rho = 0)

Day length for a latitude and date

Description

Computes the number of hours between sunrise and sunset at a given latitude on a given date, using the CBM model of Forsythe et al. (1995). The calculation is a closed form – no lookup tables, network access, or location database is involved.

Only latitude is needed. Longitude and time zone shift when sunrise and sunset occur but not the interval between them, so they are not arguments.

Usage

day_length(lat, date, horizon = "sunset")

Arguments

Details

Day length is astronomical, and the effort estimators want something else. In Hoenig et al. (1993) and Pope et al. (Ch. 17), the daily expansion factor T_d is the length of the period the counts were randomised within – a property of the survey design, set by regulation, access hours, or the field protocol. It is often close to daylight and it is not the same quantity. Use day_length() to build simulated or planned surveys, and pass the period your protocol actually used to add_counts().

Above the Arctic and Antarctic circles the sun may not rise or set at all. In those cases the result saturates at 0 or 24 rather than erroring.

Value

A numeric vector of day lengths in hours, the length of the longer of lat and date.

References

Forsythe, W.C., Rykiel, E.J., Stahl, R.S., Wu, H., Schoolfield, R.M. (1995). A model comparison for daylength as a function of latitude and day of year. Ecological Modelling 80:87-95. doi:10.1016/0304-3800(94)00034-F

Hoenig, J.M., Robson, D.S., Jones, C.M., Pollock, K.H. (1993). Scheduling counts in the instantaneous and progressive count methods for estimating sportfishing effort. North American Journal of Fisheries Management 13:723-736.

See Also

simulate_creel_data(), add_counts()

Other "Simulation": simulate_creel_catch(), simulate_creel_data()

Examples

# A single day at Kearney, Nebraska
day_length(40.699, as.Date("2024-06-21"))

# A whole season, for use as a simulated expansion factor
season <- seq(as.Date("2024-05-01"), as.Date("2024-08-31"), by = "day")
summary(day_length(40.699, season))

# Anglers fish into twilight; civil twilight adds roughly an hour in June
day_length(40.699, as.Date("2024-06-21"), horizon = "civil")

# Latitude drives the seasonal swing
day_length(c(25, 45, 65), as.Date("2024-12-21"))

Derive an angler count from its components

Description

Builds the single angler-count column that add_counts() needs from the columns a creel clerk actually records. Counts are commonly split across bank anglers and boats, and the estimators need one number per count.

Two forms are supported, matching the two ways a boat's anglers get onto the form:

• Direct counts — supply boat_anglers, the counted number of anglers aboard. Appropriate when the clerk could see and count them.

• Boat-party expansion — supply boat_count and party_size, and the boats are expanded by the mean anglers per boat party. Appropriate when boats were counted but the people aboard could not be counted reliably.

Usage

derive_angler_count(
  counts,
  bank = NULL,
  boat_anglers = NULL,
  boat_count = NULL,
  party_size = NULL,
  party_size_se = NULL,
  to = "angler_count"
)

Arguments

Details

The two boat forms are separate arguments on purpose. boat_count is a count of hulls, not people, and adding it to an angler total is a units error that produces a plausible-looking number. Requiring party_size alongside it makes that mistake impossible to commit by accident.

Components are added with na.rm = FALSE. If bank anglers are missing for a count and boat anglers are 5, the total is unknown, not 5 — a missing count and a count of zero are different observations and are kept different here.

Pooling bank and boat anglers into one count assumes both are detected the same way and are being reported as one quantity. Where detection probabilities or catch rates differ between them, estimate the two as separate domains instead of adding them.

Value

counts with the derived column appended, and the columns consumed to build it (bank, boat_anglers, boat_count) removed — they are superseded by the derived count and, where applicable, by expansion_basis. Leaving them in produced a table that varied between sub-counts of one sampling unit, which add_counts() cannot distinguish from an undeclared structural dimension (GH #162). The destination column is never dropped, even when it is also one of the inputs.

When a party-size standard error is available, four further columns are appended for the estimators to read: expansion_basis (the boat count, which is what the multiplier acts on), expansion_se, expansion_group (which rows share one estimated multiplier, and so carry perfectly correlated error), and expansion_of (the column the basis is the derivative of). add_counts() recognises all four and excludes them from count-column detection.

They must travel together and must reach add_counts() alongside the column named in expansion_of. Transforming that column in between – multiplying a count by a shift length, say – scales the count but not its derivative, and add_counts() refuses rather than propagate a component that is understated by exactly the scale factor. Pass the per-day count and let period_length_col do the multiplication instead.

All four are written by the package and are not user inputs. In particular, editing expansion_of to name a transformed column silences that refusal whether or not the basis was actually rescaled, which re-enables the very defect the check exists to catch. Rescale through period_length_col, which scales both together and can be verified, rather than by asserting that you did (GH #148).

The party size is an estimate

A mean party size taken from interviews is itself estimated, and it multiplies the boat component of every count. Its error is therefore perfectly correlated across counts and does not shrink as counts are added – averaging more counts will not reduce it. Left out, the reported effort standard error is too small; the estimate itself is unaffected.

Supply party_size_se to carry that term through to the effort standard error. mean_party_size() returns it as a "se" attribute, which is picked up automatically when its output is passed as party_size, so the usual pipeline propagates the term without any extra argument.

When no standard error is available the term is omitted rather than set to zero. A zero would produce a standard error identical to an unpropagated one while looking propagated, which is worse than a documented omission. The returned table carries no expansion columns in that case, and ⁠attr(<estimates>, "se_expansion")⁠ is NULL rather than 0.

See Also

mean_party_size(), add_counts(), prep_counts_boat_party()

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

counts <- data.frame(
  date = as.Date("2024-06-01") + 0:1,
  day_type = c("weekday", "weekend"),
  bank_anglers = c(4L, 9L),
  angler_boats = c(3L, 7L),
  boat_anglers = c(7L, 16L)
)

# Direct counts
derive_angler_count(counts, bank = bank_anglers, boat_anglers = boat_anglers)

# Boat-party expansion with a single mean
derive_angler_count(
  counts,
  bank = bank_anglers,
  boat_count = angler_boats,
  party_size = 2.4
)

# Expansion with a stratum-specific mean
mps <- data.frame(day_type = c("weekday", "weekend"), mean_party_size = c(2.1, 2.8))
derive_angler_count(
  counts,
  bank = bank_anglers,
  boat_count = angler_boats,
  party_size = mps
)

Estimate a weighted age distribution from creel interview data

Description

est_age_distribution() estimates a pressure-weighted age-frequency distribution from fish age data attached via add_ages(). Age records are aggregated through the internal interview survey design so the result reflects the survey design rather than only the observed sample.

Ages are discrete integers; each unique observed age is its own class. The estimator returns one row per occupied integer age, with weighted totals, standard errors, confidence intervals, and within-group percentages.

Usage

est_age_distribution(
  design,
  by = NULL,
  type = "catch",
  variance = "taylor",
  conf_level = 0.95
)

Arguments

Value

A data.frame with class c("creel_age_distribution", "data.frame") and columns: grouping columns (if any), age (integer), estimate, se, ci_lower, ci_upper, percent, cumulative_percent, and n.

percent and cumulative_percent are shares of the group's estimated total, rounded to one decimal for display; cumulative_percent accumulates the unrounded shares, so it reaches 100 rather than drifting. The exception is a group whose estimated total is zero, where there are no shares to take and both columns are 0 rather than reaching 100.

n is the number of interviews contributing at least one aged fish to the group. It is therefore constant across every age class of a group, and is neither a per-class sample size nor a count of fish.

Two-phase estimation onto the reported catch

Ages are read from a subsample of the catch, exactly as lengths are, so the age-class totals are scaled onto the design-estimated reported total rather than reporting the subsample: \hat{N}_a = \hat{p}_a \hat{T}. See est_length_distribution() for the estimator, its variance, and where \hat{T} comes from. percent and cumulative_percent are unaffected. The call warns when it rescales and aborts when no total is available (GH #310).

See Also

Other "Estimation": compare_cpue_estimators(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_ages)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_ages(design, example_ages,
  age_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  age = age,
  age_type = age_type
)

est_age_distribution(design, by = species)

Estimate total biomass from a creel length distribution

Description

est_biomass() converts a pressure-weighted length-frequency distribution produced by est_length_distribution() into a total biomass estimate using the allometric length-weight equation W = a \cdot L^b.

Variance is propagated via the delta method, carrying the full covariance among the estimated fish counts per length bin and treating the length-weight parameters a and b as known without error unless their standard errors are supplied (see Details). Before GH #311 the bin counts were treated as uncorrelated, which under-estimated the variance.

Since GH #310 the counts supplied by est_length_distribution() describe the reported catch rather than the measured subsample, so biomass_estimate is a catch biomass. It previously described only the fish that were measured.

Usage

est_biomass(
  ld,
  a,
  b,
  conf_level = NULL,
  alpha_se = NULL,
  b_se = NULL,
  L0 = NULL
)

Arguments

Details

For each length bin h with midpoint L_h = (\text{bin\_lower} + \text{bin\_upper}) / 2, per-bin biomass is B_h = a \cdot L_h^b \cdot \hat{N}_h, where \hat{N}_h is the survey-weighted estimated fish count from est_length_distribution(). Total biomass is B = \sum_h B_h.

Variance is the quadratic form \widehat{\text{Var}}(B) = w' \Sigma w with w_h = a \cdot L_h^b and \Sigma the bins' full covariance matrix, carried from the single svytotal() that estimated them. Earlier versions used \sum_h w_h^2 \widehat{\text{SE}}_h^2 — the same expression with every off-diagonal set to zero — which under-estimated the variance, since the bins partition the same fish and are rescaled onto one reported total.

If \Sigma is unavailable — the object was produced by an older version, or was subsetted in a way that dropped the attribute carrying it — the independence form is used and a warning says so. An absent covariance is unknown, not zero.

By default a and b are treated as known constants, so biomass_se carries no contribution from their estimation error. In practice they are point estimates from a length-weight regression, often one fitted to a different water body or year. Because a \cdot L_h^b multiplies every bin, that error is perfectly correlated across bins and does not shrink as bins are added — unlike the cross-bin term above.

The omission is usually minor relative to count variance: on the example below it adds roughly 2–11% to a coefficient of variation of 40–65%, for regression standard errors spanning well- and poorly-determined fits. It becomes material in two situations — a survey precise enough to bring the count CV near 10%, and a/b borrowed from a system whose fish differ in size from those measured here, since the contribution scales with the distance between the two samples' mean log lengths.

Value

A data.frame with class c("creel_biomass", "data.frame") and columns: grouping columns (if any), biomass_estimate, biomass_se, biomass_ci_lower, biomass_ci_upper.

Propagating the length-weight regression error

Supply alpha_se, b_se, and L0 together to carry that term. The allometry is rewritten about a pivot length L_0:

W = \alpha \left(\frac{L}{L_0}\right)^b, \qquad \alpha = a L_0^b

and the delta method is applied in (\alpha, b):

\widehat{\text{Var}}(B) \approx \sum_h (a L_h^b)^2 \widehat{\text{SE}}_h^2 + \left(\frac{B}{\alpha}\right)^2 \text{Var}(\alpha) + \left(\sum_h B_h \ln\frac{L_h}{L_0}\right)^2 \text{Var}(b)

The covariance term is absent by construction rather than by assumption. Fitted on the raw (a, b) scale the two parameters are almost perfectly negatively correlated — typically \text{cor} < -0.99 — so dropping their covariance there would overstate the variance severalfold, in some cases turning a 2–11% contribution into 5–49%. Centring at L_0 makes them near-orthogonal, so the omitted term is genuinely negligible. Take L_0 as the geometric mean length of the calibration sample, and take alpha_se from the intercept of a regression centred there — not the standard error of a itself.

The contribution grows with \ln(L_h / L_0), so borrowing parameters from a system whose fish differ in size from these is penalised automatically, which is the intended behaviour.

There is deliberately no zero default for these arguments. A zero standard error would produce a biomass_se identical to an unpropagated one while appearing to have been propagated — worse than the documented omission it would replace. When they are absent, attr(x, "biomass_se_params") is NULL rather than 0, and biomass_se should be read as a lower bound.

Length and weight units are determined by the user: if lengths are in mm and a is calibrated for mm input, weights are returned in the corresponding unit (e.g., grams).

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_lengths)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  length = length,
  length_type = length_type,
  count = count,
  release_format = "binned"
)

ld <- est_length_distribution(design, by = species, bin_width = 25)
est_biomass(ld, a = 0.0088, b = 3.1)

Estimate design-weighted size-limit compliance from a creel length distribution

Description

est_compliance() estimates the proportion of fish meeting a minimum size limit from a est_length_distribution() object. Fish in bins whose lower bound is at or above min_length are classified as legal (conservative: bins straddling the limit are classified as illegal).

Usage

est_compliance(ld, min_length, conf_level = NULL)

Arguments

Details

A bin is legal when bin_lower >= min_length. The compliance proportion and its variance use the ratio estimator:

P = \frac{\sum_h I_h \hat{N}_h}{\hat{N}}

\widehat{\text{Var}}(P) = \frac{1}{\hat{N}^2} w' \Sigma w, \quad w_h = I_h - P

where I_h = \mathbf{1}(\text{bin\_lower}_h \geq \text{min\_length}) and \Sigma is the bins' full covariance matrix, carried from the single svytotal() that estimated them.

Earlier versions used \sum_h w_h^2 \widehat{\text{SE}}_h^2 — the same expression with every off-diagonal set to zero. The bins partition the same fish and are rescaled onto one reported total, so they are strongly dependent, and on the package's own example data that form reported a standard error 32% below an independently computed survey::svyratio() reference. If \Sigma is unavailable the independence form is used and a warning says so.

Confidence interval bounds are clamped to [0, 1].

Choose bin_width in est_length_distribution() smaller than the typical variation near the legal limit to minimise classification error for bins that straddle the threshold.

Value

A data.frame with class c("creel_compliance", "data.frame") and columns: grouping columns (if any), min_length, n_legal_est, n_total_est, compliance_prop, compliance_se, compliance_ci_lower, compliance_ci_upper. Rows where the total estimated fish is zero or negative return NA for all numeric columns with a warning.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_lengths)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  length = length,
  length_type = length_type,
  count = count,
  release_format = "binned"
)

ld <- est_length_distribution(design, by = species, bin_width = 25)
est_compliance(ld, min_length = 356)  # 14-inch limit in mm

Estimate angler effort from camera/time-lapse count data

Description

Estimates total angler-hours from a camera-based creel survey design. Two estimation modes are supported:

Usage

est_effort_camera(
  design,
  interviews = NULL,
  effort_col = "hours_fished",
  n_anglers = NULL,
  intercept_col = NULL,
  h_open = NULL,
  calibration = NULL,
  variance = c("taylor", "replicate"),
  conf_level = 0.95
)

Arguments

Details

• Ratio calibration (recommended, when interview data are available): Per-stratum calibration ratios (mean interview effort / mean camera count during the interview period) scale raw camera counts to angler-hours. Variance is estimated via Taylor linearisation or replicate weights.

• Raw count expansion (fallback): Camera ingress counts are multiplied by h_open (fishable hours per day). Use when no interview data are available.

Value

A creel_estimates object with columns estimate, se, se_between, se_within, ci_lower, ci_upper, n.

Uncertainty the standard error does not cover

Two cases are reported rather than absorbed, because in both the returned standard error would otherwise understate what is known:

• A stratum with a single paired interview/count day gives its calibration ratio no measurable spread. That variance is unknown rather than zero, so it is carried as NA and the combined standard error and confidence interval are NA too; a warning names the stratum. Add a second matched interview day in that stratum to recover a standard error.

• Counts flagged .imputed by impute_camera_counts() enter the estimator as observations. The imputation model's prediction uncertainty is not propagated, and model predictions vary less than real counts, so the between-day component is understated as well. A warning reports how many days were imputed; the standard error is a lower bound.

Within-day variance

When counts arrive through add_counts(count_time_col = ), several counts on one day are averaged into a daily mean and the within-day components (ss_d, k_d) are stored on the design. Both paths of this function read them and report the Rasmussen (1998) within-day term as se_within, scaling it by the stratum's calibration ratio on the ratio path and by h_open on the raw path.

se_within is 0 only when there is genuinely nothing to measure – one count per day, where the component is nil by construction rather than unknown. It was previously reported as a literal 0 in every case, while the measured components sat unread on the design, so a design with real within-day spread received the same standard error as one with none.

One count row per day on the calibration path

Ratio calibration pairs each interview day to that day's camera count, so it requires the counts table to hold exactly one row per day (per stratum). A repeated day is refused rather than averaged: two counts on one date are either sub-period snapshots or a data error, and the estimator cannot tell which. Before this was checked, a repeated date entered both sides of the calibration ratio twice and moved the point estimate, not merely the standard error.

If the counts are genuine sub-daily observations, pass count_time_col to add_counts(), which averages them into one row per day and retains the within-day variance. Otherwise remove the repeated rows. Raw count expansion (interviews = NULL) does no pairing and is not subject to this requirement.

Where the calibration estimator comes from

The ratio calibration is a double-sampling ratio estimator, applied here to camera calibration by this package. It is not a reproduction of a published fisheries estimator, and no paper in the camera literature derives it in this form.

Within each stratum the estimator forms rho as a ratio of sums – interview hours over camera counts on the paired days – estimates its variance by the ratio-estimator formula on the paired daily residuals, and applies it to that stratum's first-phase count total, combining the two variances by the delta method. The counts are the first-phase sample and the days carrying interviews are the second phase, which is the structure Cochran (1977) Chapter 12 treats; the ratio's variance is Cochran's eq. 2.46 with the finite-population correction omitted.

The practice of calibrating camera counts against paired concurrent creel observations is well established – Hartill et al. (2016), van Poorten et al. (2015), Eckelbecker et al. (2022) – but each of those uses a different estimator: a per-day classification proportion, a hierarchical Bayesian model, and a fitted linear correction respectively. Hartill et al. (2020) is a review of camera monitoring and presents no estimator or variance at all.

In particular this is not Hartill et al.'s (2016) rho. Theirs is the dimensionless proportion of observed boats that were fishing, estimated per day from interviews that are a subsample of the camera's own frame, with a bootstrap variance. The ratio here has units of hours per count, corrects counts to effort rather than classifying them, pools over days within a stratum, and pairs the camera against an independent measurement – a different variance structure, which is why a design-based ratio variance is used rather than a bootstrap.

References

Cochran, W.G. 1977. Sampling Techniques, 3rd ed. Wiley, New York. Section 2.11 gives the ratio estimator and its estimated variance (eq. 2.46), which is the form used here with the finite-population correction omitted. Chapter 12 covers double sampling, and Section 12.9 (p. 343) the ratio estimator applied to a first-phase total.

Hartill, B.W., Payne, G.W., Rush, N., and Bian, R. 2016. Bridging the temporal gap: continuous and cost-effective monitoring of dynamic recreational fisheries by web cameras and creel surveys. Fisheries Research 183:488-497. doi:10.1016/j.fishres.2016.06.002

van Poorten, B.T., Carruthers, T.R., Ward, H.G.M., and Varkey, D.A. 2015. Imputing recreational angling effort from time-lapse cameras using an hierarchical Bayesian model. Fisheries Research 172:265-273. doi:10.1016/j.fishres.2015.07.032

Eckelbecker, R.W., Coleman, T.S., and Catalano, M.J. 2022. Incorporating time-lapse digital cameras into creel surveys at three Alabama reservoirs. North American Journal of Fisheries Management 42:1349-1358. doi:10.1002/nafm.10828

Hartill, B.W., Taylor, S.M., Keller, K., and Weltersbach, M.S. 2020. Digital camera monitoring of recreational fishing effort: applications and challenges. Fish and Fisheries 21:204-215. doi:10.1111/faf.12413

See Also

Other "Survey Design": add_catch(), add_counts(), add_interviews(), add_lengths(), add_sections(), as_creel_svydesign(), as_hybrid_svydesign(), compute_angler_effort(), compute_effort(), creel_design(), creel_schema(), creel_vocabulary(), derive_angler_count(), impute_camera_counts(), mean_party_size(), prep_counts_boat_party(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

library(tidycreel)
data(example_camera_counts)
data(example_camera_interviews)

cal <- data.frame(
  date     = unique(example_camera_counts$date),
  day_type = unique(example_camera_counts[, c("date", "day_type")])[["day_type"]]
)
design <- creel_design(cal,
  date = date, strata = day_type,
  survey_type = "camera", camera_mode = "counter"
)

# Filter to operational rows
ops <- example_camera_counts[
  example_camera_counts$camera_status == "operational",
]
design <- add_counts(design, ops)

# Ratio calibration using interview hours. `example_camera_interviews` has no
# party-size column, so this warns and reports an unknown unit: the estimate
# is in whatever unit `hours_fished` holds, which the package cannot tell.
est <- est_effort_camera(design, interviews = example_camera_interviews)
print(est)

# With party sizes the function does the normalisation itself, so the result
# is angler-hours and is labelled as such.
ints <- example_camera_interviews
ints$party_size <- 2
est_ah <- est_effort_camera(design, interviews = ints, n_anglers = "party_size")
print(est_ah)

Pool camera effort estimates across multiply imputed count data sets

Description

Estimates camera effort once per completed data set produced by impute_camera_counts() with m > 1, then combines the results with Rubin's (1987) rules.

This exists because a single completed data set structurally cannot carry the uncertainty introduced by imputing. Inside survey::svytotal() a predicted count is indistinguishable from an observed one, so the imputation model's own error is dropped; and predictions are smoother than real counts, so the between-day component shrinks as well. The reported SE is therefore biased downward twice over, and can fall below the SE of the same design with the outage days simply deleted — reporting more precision from less information (GH #137).

Usage

est_effort_camera_mi(design, imputations, ..., conf_level = 0.95)

Arguments

Details

Value

A creel_estimates object with method = "camera_mi". Its se_components names the two halves of the pooled variance as within_imputation and between_imputation, so a reader can see how much of the uncertainty came from imputing. The per-imputation results are attached as attr(result, "imputations").

The pooled variance

With M completed data sets giving estimates Q_m and variances U_m = SE_m^2:

\bar{Q} = \frac{1}{M} \sum_m Q_m

\bar{U} = \frac{1}{M} \sum_m U_m

B = \frac{M+1}{M(M-1)} \sum_m (Q_m - \bar{Q})^2

T = \bar{U} + B

\bar{U} is the within-imputation variance — the average of what each completed data set reports, and the only part single imputation can produce. B is the between-imputation term, and it is the one that is structurally missing today: it measures how much the estimate moves when the outage days are filled differently, which a single filled data set cannot express at all.

This is the pooling in Afrifa-Yamoah et al. (2020) equation (5). Their (M+1)/(M(M-1)) factor is the usual Rubin (1 + 1/M) inflation written over the raw sum of squares rather than the sample variance; the two are the same quantity.

Degrees of freedom use Rubin's classic expression \nu = (M-1)(1 + \bar{U}/B)^2, which is finite precisely because B > 0.

References

Afrifa-Yamoah, E., Taylor, S.M., Fisher, A., and Mueller, U. 2020. Imputation of missing data from time-lapse cameras used in recreational fishing surveys. ICES Journal of Marine Science 77(7-8):2984-2994.

Rubin, D.B. 1987. Multiple Imputation for Nonresponse in Surveys. Wiley.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_camera_counts)
data(example_camera_interviews)

cal <- data.frame(
  date     = unique(example_camera_counts$date),
  day_type = unique(example_camera_counts[, c("date", "day_type")])[["day_type"]]
)
design <- creel_design(cal,
  date = date, strata = day_type,
  survey_type = "camera", camera_mode = "counter"
)
# No add_counts() here: each imputation supplies its own completed count
# series, so attaching one of them first would fix the very thing being
# varied.
# Outage days are refilled several times over, so the uncertainty about what
# the camera missed enters the standard error instead of being assumed away.
imps <- impute_camera_counts(
  example_camera_counts,
  count_col  = "ingress_count",
  strata_col = "day_type",
  m          = 5L
)

ints <- example_camera_interviews
ints$party_size <- 2
est_effort_camera_mi(design, imps, interviews = ints, n_anglers = "party_size")

Estimate a weighted length distribution from creel interview data

Description

est_length_distribution() estimates a pressure-weighted length-frequency distribution from fish length data attached via add_lengths(). Unlike summarize_length_freq(), which reports raw sample frequencies, est_length_distribution() aggregates interview-level bin counts through the internal interview survey design so the result reflects the survey design rather than only the observed sample.

The estimator returns one row per occupied length bin, with weighted totals, standard errors, confidence intervals, and within-group percentages.

Lengths are measured on a subsample of the catch, so the bin totals are scaled onto the design-estimated reported catch rather than reporting the subsample itself. See the section below; the call warns whenever it rescales, and aborts when the design carries no total to scale to.

Usage

est_length_distribution(
  design,
  type = "catch",
  by = NULL,
  bin_width = 1,
  length_col = NULL,
  variance = "taylor",
  conf_level = 0.95
)

Arguments

Value

A data.frame with class c("creel_length_distribution", "data.frame") and columns: grouping columns (if any), length_bin (ordered factor), bin_lower, bin_upper, estimate, se, ci_lower, ci_upper, percent, cumulative_percent, and n.

percent and cumulative_percent are shares of the group's estimated total, rounded to one decimal for display; cumulative_percent accumulates the unrounded shares, so it reaches 100 rather than drifting. The exception is a group whose estimated total is zero, where there are no shares to take and both columns are 0 rather than reaching 100.

n is the number of interviews contributing at least one measured fish to the group. It is therefore constant across every bin of a group, and is neither a per-bin sample size nor a count of fish.

Two-phase estimation onto the reported catch

Lengths are a second-phase sample: interviews report how many fish were caught, and some subset of those fish get measured. Expanding the measured fish through the interview design alone estimates the total number of fish that happened to be measured, which is not the catch — on this package's example data it returns 14 against a reported harvest of 77. Because est_biomass() multiplies these counts by weight-at-length and calls the result total biomass, the error propagated to a headline number (GH #310).

The estimator is therefore two-phase (double sampling, Cochran 1977 §12.9 — the same structure used for the camera calibration ratio). For bin h:

\hat{p}_h = \hat{N}_h^{\text{meas}} / \sum_j \hat{N}_j^{\text{meas}}, \qquad \hat{N}_h = \hat{p}_h \hat{T}

where \hat{T} is the design-estimated reported total for the group. Both parts come from a single svytotal() call, so the covariance between a bin and the reported total is estimated rather than assumed away, and the standard error is the delta method over that joint covariance.

What this changes: estimate, se and the confidence bounds now describe the reported catch. percent and cumulative_percent are unchanged — a share is invariant to the subsample size, which is why the shape of the distribution was always correct and only its level was not.

Where \hat{T} comes from depends on the grouping. A species group can only be scaled by that species' own total, which lives in the table attached by add_catch(); grouping by species without it is refused rather than scaled by the all-species total. Any other grouping uses the interview-level column (catch or harvest from add_interviews()), with release implied as caught - harvested so that harvest and release sum back to catch.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_lengths)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  length = length,
  length_type = length_type,
  count = count,
  release_format = "binned"
)

est_length_distribution(design, by = species, bin_width = 25)

Estimate design-weighted mean age from a creel age distribution

Description

est_mean_age() computes the pressure-weighted mean fish age from a est_age_distribution() object using the ratio estimator \bar{A} = \sum_a a \hat{N}_a / \sum_a \hat{N}_a, with delta-method standard error.

Usage

est_mean_age(ad, conf_level = NULL)

Arguments

Details

Each integer age a contributes its survey-weighted count \hat{N}_a. Mean age is the ratio of total age-weighted count to total count:

\bar{A} = \frac{\sum_a a \hat{N}_a}{\hat{N}}

Variance is propagated via the delta method for a ratio estimator, treating cross-class covariances as zero:

\widehat{\text{Var}}(\bar{A}) \approx \frac{1}{\hat{N}^2} \sum_a (a - \bar{A})^2 \, \widehat{\text{SE}}_a^2

Value

A data.frame with class c("creel_mean_age", "data.frame") and columns: grouping columns (if any), mean_age, mean_age_se, mean_age_ci_lower, mean_age_ci_upper. Rows where the total estimated fish is zero or negative return NA for all numeric columns with a warning.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_ages)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_ages(design, example_ages,
  age_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  age = age,
  age_type = age_type
)

ad <- est_age_distribution(design, by = species)
est_mean_age(ad)

Estimate design-weighted mean length from a creel length distribution

Description

est_mean_length() computes the pressure-weighted mean fish length from a est_length_distribution() object using the ratio estimator \bar{L} = \sum_h L_h \hat{N}_h / \sum_h \hat{N}_h, with delta-method standard error.

Usage

est_mean_length(ld, conf_level = NULL)

Arguments

Details

Bin midpoints L_h = (\text{bin\_lower} + \text{bin\_upper}) / 2 serve as representative lengths. Mean length is the ratio of total length-weighted count to total count:

\bar{L} = \frac{\sum_h L_h \hat{N}_h}{\hat{N}}

Variance is propagated via the delta method for a ratio estimator, using the bins' full covariance matrix \Sigma:

\widehat{\text{Var}}(\bar{L}) = \frac{1}{\hat{N}^2} w' \Sigma w, \quad w_h = L_h - \bar{L}

Earlier versions treated the cross-bin covariances as zero, which under-estimated the standard error. If \Sigma is unavailable the independence form is used and a warning says so.

Value

A data.frame with class c("creel_mean_length", "data.frame") and columns: grouping columns (if any), mean_length, mean_length_se, mean_length_ci_lower, mean_length_ci_upper. Rows where the total estimated fish is zero or negative return NA for all numeric columns with a warning.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_calendar)
data(example_interviews)
data(example_lengths)
data(example_catch)


design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
# Species catch is required to group by species: the totals are scaled onto
# the reported catch, and only this table records it per species.
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)
design <- add_lengths(design, example_lengths,
  length_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  length = length,
  length_type = length_type,
  count = count,
  release_format = "binned"
)

ld <- est_length_distribution(design, by = species, bin_width = 25)
est_mean_length(ld)

Estimate angler population size via closed-population mark-recapture

Description

Computes a closed-population mark-recapture estimate of total angler population size (N_hat) using one of three estimators:

• Chapman (default, method = "chapman"): A bias-corrected version of the Petersen estimator recommended when recaptures are small. \hat{N} = \frac{(M+1)(n+1)}{(m+1)} - 1

• Petersen (method = "petersen"): The unadjusted Lincoln-Petersen estimator. Requires at least 7 recaptures (m \geq 7) to avoid large positive bias; use Chapman for smaller recapture counts. \hat{N} = \frac{M \cdot n}{m}

• Schnabel (method = "schnabel"): A multi-occasion weighted estimator for K \geq 2 sampling occasions, carrying Chapman's (1952) small-sample correction by default. \hat{N} = \frac{\sum M_k n_k}{\sum m_k + 1} CI uses the Poisson branch when \sum m_k < 50 and the normal approximation on 1/\hat{N} otherwise, on K - 1 degrees of freedom (Hansen & Van Kirk 2018, eq. A.5).

• Schumacher-Eschmeyer (method = "schumacher"): The regression alternative to Schnabel for K \geq 3 occasions, fitting m_k/n_k against M_k through the origin with slope 1/N. \hat{N} = \frac{\sum n_k M_k^2}{\sum m_k M_k} Interval from Seber (1982) eq. (4.17) on K - 2 degrees of freedom. Also carries Dettloff's (2023) eq. (8) small-sample correction by default.

Usage

estimate_angler_n(
  M,
  n,
  m,
  method = "chapman",
  conf_level = 0.95,
  ci_method = c("logit", "delta", "bootstrap"),
  B = 2000L,
  bias_adjust = TRUE
)

Arguments

Details

Why the Chapman and Petersen default is not a Wald interval. \hat{N} is a ratio with a small integer denominator, so its sampling distribution is strongly right-skewed and a symmetric interval leaves the parameter space. Evans et al. (1996) measured Wald coverage failing on one side 27.9\ and Dettloff (2023) report the same. With M = 200, n = 50 and m = 3 the Wald lower bound is -2124.8; at m = 5 it is 48.7, below the 245 individuals actually observed. Chapman is recommended precisely when recaptures are few, so this is the regime the default estimator is chosen for.

The default "logit" interval is Sadinle's (2009) 0.5 transformed logit, built on the 2 \times 2 capture table (n_{11} = m, n_{12} = M - m, n_{21} = n - m) with 0.5 added to each cell. Sadinle compared nine intervals and found it "the best of the intervals reported here", with near-nominal coverage even for small populations and capture probabilities near 0 or 1, where profile-likelihood and Monte Carlo intervals both degrade. Its lower limit is guaranteed never to fall below n_{11} + n_{12} + n_{21}, the number of individuals actually seen — the property the Wald interval lacks. It is closed-form and always computable, since the 0.5 continuity correction removes every zero-count division.

One consequence worth knowing. When m = n — every individual in the second sample was already marked — the estimator saturates at \hat{N} = M, which is also the observed count. The logit lower limit then sits fractionally above \hat{N}, because the data imply N > M rather than N = M. This is the interval being informative at a boundary, not an error; pass ci_method = "delta" if a bound that brackets the point estimate matters more than coverage.

ci_method = "delta" reproduces the pre-3.0.0 bounds exactly.

Choosing between Schnabel and Schumacher-Eschmeyer, and a warning about how not to. They use identical field data and differ in how they pool it: Schnabel is a ratio of sums, Schumacher-Eschmeyer a weighted regression through the origin. Seber (1982) expects the regression form "to be robust with regard to departures from the underlying assumptions" and recommends using it "in conjunction with the other methods" — as a cross-check, not a replacement. That is a weaker claim than it is sometimes reported as; Seber neither demonstrates the robustness nor calls it the most robust method. Dettloff (2023) found the two adjusted forms "effectively equivalent at larger sample sizes", with Schumacher-Eschmeyer less variable and Schnabel reaching unbiasedness slightly sooner.

Do not pick whichever gives the narrower interval. Hansen & Van Kirk (2018) computed both and "selected the mark-recapture estimator that produced the smallest 95\ the narrower of two intervals after seeing them conditions on the luckier draw, so the reported interval is narrower than its nominal level. tidycreel therefore does not implement the selection rule. Decide between the estimators on design grounds before looking at the answer, or report both.

The Schnabel upper bound at very few recaptures. The Poisson interval inverts the distribution of \sum m_k, so it needs the lower quantile q_{\alpha/2} in its denominator. That quantile is zero whenever \sum m_k \leq 3 at the 95\ Inf. Following Hansen & Van Kirk (2018) eq. (A.4), tidycreel substitutes Ilienko's (2013) continuous Poisson in exactly that case — it has distribution function \Gamma(x, \lambda)/\Gamma(x), is positive there, and so returns a finite bound. The substitution fires only where the discrete quantile is zero; from \sum m_k \geq 4 the continuous quantile sits just above the discrete one, so this is a targeted patch rather than a change of method.

Read that bound for what it is. It comes from a continuous interpolation of a discrete distribution at one to three total recaptures, not from the data, and it is wide. It stands in for "the data do not bound this above" rather than measuring anything, which is why the function still warns when it fires. Ilienko's construction is the genuine interpolant — his eq. (1) shows the same expression returns the discrete Poisson CDF at integer x — but interpolating at \sum m_k = 1 is still interpolating.

Where the Petersen m \geq 7 guard comes from. The threshold is a practical stand-in, not a derivation, and it is worth knowing why no exact one is available. Robson & Regier (1964) give two conditions: Chapman is exactly unbiased when M + n \geq N, and its negative bias stays under 2\ \sqrt{Mn} \geq 2\sqrt{N} — the geometric mean of marks and captures at least twice the square root of the population size. Both depend on N, the unknown being estimated. Dettloff (2023) calls this "paradoxical" and treats such rules as "a way of avoiding inaccurate estimates from absurdly small sample sizes based on an educated guess of the order of magnitude" of N. A fixed m threshold is that guess made concrete; it rules out the regime where Petersen's positive bias is severe without pretending to a precision the conditions cannot deliver. Chapman is the better default at any recapture count and is what the error message points to.

Why Schnabel is bias-adjusted by default. Each m_k is approximately Poisson with parameter M_k n_k / N, which motivated Chapman's (1952) +1 correction to the recapture total. Dettloff (2023) simulated both forms and found the unadjusted estimator turns biased high at moderate sample sizes before settling, whereas the adjusted form has bias that "approaches zero as the sample size increases without ever becoming positive", with lower variance and no cost at large samples; he recommends the adjusted estimators "in place of the originals in all scenarios". The package already defaults to the analogous +1 correction at two occasions (method = "chapman"), and Schnabel reduces exactly to Lincoln-Petersen at K = 2, so leaving Schnabel unadjusted made bias handling depend on how many occasions were sampled. The relative shift is -1/(\sum m_k + 1): -33\ 500. Pass bias_adjust = FALSE for the previous form.

Value

A creel_estimates S3 object with method = "mark-recapture-chapman" (or petersen/schnabel) and an estimates tibble with columns: parameter, estimate, se, ci_lower, ci_upper, n (total recaptures).

References

Hansen, J. M., & Van Kirk, R. W. (2018). A mark-recapture-based approach for estimating angler harvest. North American Journal of Fisheries Management, 38(2), 400–410. doi:10.1002/nafm.10038

Sadinle, M. (2009). Transformed logit confidence intervals for small populations in single capture-recapture estimation. Communications in Statistics - Simulation and Computation, 38(9), 1909–1924. doi:10.1080/03610910903168595

Evans, M. A., Kim, H.-M., & O'Brien, T. E. (1996). An application of profile-likelihood based confidence interval to capture-recapture estimators. Journal of Agricultural, Biological, and Environmental Statistics, 1(1), 131–140. doi:10.2307/1400565

Dettloff, K. (2023). Assessment of bias and precision among simple closed population mark-recapture estimators. Fisheries Research, 265, 106756. doi:10.1016/j.fishres.2023.106756

Chapman, D. G. (1952). Inverse, multiple and sequential sample censuses. Biometrics, 8(4), 286–306. doi:10.2307/3001864

Robson, D. S., & Regier, H. A. (1964). Sample size in Petersen mark-recapture experiments. Transactions of the American Fisheries Society, 93(3), 215–226. doi:10.1577/1548-8659(1964)93[215:SSIPME]2.0.CO;2

Ilienko, A. (2013). Continuous counterparts of Poisson and binomial distributions and their properties. Annales Universitatis Scientiarum Budapestinensis de Rolando Eotvos Nominatae, Sectio Computatorica, 39, 137–147.

Schnabel, Z. E. (1938). The estimation of the total fish population of a lake. The American Mathematical Monthly, 45(6), 348–352. doi:10.2307/2304025

Chapman, D. G. (1951). Some properties of the hypergeometric distribution with applications to zoological sample censuses. University of California Publications in Statistics, 1(7), 131–160.

Schumacher, F. X., & Eschmeyer, R. W. (1943). The estimation of fish populations in lakes or ponds. Journal of the Tennessee Academy of Science, 18, 228–249.

Seber, G. A. F. (1982). The Estimation of Animal Abundance and Related Parameters, 2nd ed. Macmillan, New York.

De Lury, D. B. (1958). The estimation of population size by a marking and recapture procedure. Journal of the Fisheries Research Board of Canada, 15(1), 19–25. doi:10.1139/f58-003

See Also

Other Estimation: estimate_exploitation_rate(), estimate_mr_harvest()

Examples

# Chapman (default) — bias-corrected Petersen
result <- estimate_angler_n(M = 200L, n = 50L, m = 10L)
print(result)

# Petersen — requires m >= 7
result_p <- estimate_angler_n(M = 200L, n = 50L, m = 10L, method = "petersen")
print(result_p)

# Schnabel — multi-occasion with parallel vectors
result_s <- estimate_angler_n(
  M = c(0L, 47L, 91L, 131L),
  n = c(50L, 50L, 50L, 50L),
  m = c(0L,  4L,  6L,  8L),
  method = "schnabel"
)
print(result_s)

# Schumacher-Eschmeyer — the regression alternative, needs >= 3 occasions
result_se <- estimate_angler_n(
  M = c(0L, 47L, 91L, 131L),
  n = c(50L, 50L, 50L, 50L),
  m = c(0L,  4L,  6L,  8L),
  method = "schumacher"
)
print(result_se)

Estimate angler trips from extrapolated effort

Description

Computes estimated trips by dividing extrapolated effort by the mean trip length per stratum, with Delta Method variance propagation (Powell 2007). This is a composable estimator: the effort object must be pre-computed via estimate_effort before calling this function.

The divisor is hours per trip, so the result comes back in whichever actor the effort was measured in: angler-hours give angler trips, party-hours give party trips. The returned unit field records which, and is NA when the effort's own unit was unknown. The method string is "angler-trips" in every case and so is not a guide to the actor.

Usage

estimate_angler_trips(effort, design, conf_level = 0.95, ...)

Arguments

Value

A creel_estimates object with method = "angler-trips" and variance_method = "delta". The estimates tibble contains:

by_vars columns

Any grouping columns from the effort object (if grouped).

estimate

Estimated trips per stratum (effort / mean trip length), in the actor the effort was measured in.

se

Standard error via Delta Method variance propagation.

ci_lower

Lower confidence interval bound.

ci_upper

Upper confidence interval bound.

n

Number of interviews contributing to mean trip length per stratum.

For grouped effort, an .overall row is appended with estimate = sum(stratum trips) and se propagated by addition in quadrature.

References

Powell, L. A. (2007). Approximating variance of demographic parameters using the delta method. Journal of Wildlife Management, 71(3), 1018-1024.

See Also

estimate_effort, estimate_exploitation_rate

Examples

data(example_calendar)
data(example_counts)
data(example_interviews)
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status, trip_duration = trip_duration
)
effort <- estimate_effort(design)
estimate_angler_trips(effort, design)

Estimate CPUE (Catch Per Unit Effort) from a creel survey design

Description

Computes CPUE estimates with standard errors and confidence intervals from a creel survey design with attached interview data. Supports both ratio-of-means (for complete trips) and mean-of-ratios (for incomplete trips) estimation methods.

Usage

estimate_catch_rate(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  estimator = NULL,
  use_trips = NULL,
  truncate_at = 0.5,
  targeted = TRUE,
  missing_sections = "warn",
  force_origin = TRUE
)

Arguments

Details

Trip Type Selection (use_trips): When trip_status is provided, the use_trips parameter controls which trips are used for estimation. For access-point designs (interview_type = "access", the default), use_trips defaults to "complete": interviews are taken at trip end, so complete trips are representative and avoid length-of-stay bias (Pollock et al. 1994). For roving designs (interview_type = "roving"), use_trips automatically defaults to "all" with the MOR estimator: the clerk intercepts trips mid-stream, so all interviews — complete and incomplete — are valid inputs (Hoenig et al. 1997). Set use_trips = "incomplete" to restrict MOR to incomplete trips only. Set use_trips = "diagnostic" to run both complete and incomplete trip estimation and return a comparison object with difference metrics. Diagnostic mode requires both trip types. When trip_status is not provided, use_trips is ignored for backward compatibility with v0.2.0.

Ratio-of-Means (default): CPUE is estimated as the ratio of total catch to total effort. This is the appropriate estimator for complete trip interviews (interview at trip end). The function uses survey::svyratio() internally, which correctly accounts for the correlation between catch and effort in variance estimation.

Mean-of-Ratios (MOR): When estimator = "mor", CPUE is estimated as the mean of individual catch/effort ratios. This is the statistically appropriate estimator for incomplete trip interviews (interview during trip). MOR automatically filters to incomplete trips only and requires the trip_status field. The function uses survey::svymean() on individual ratios.

Trip Truncation: Very short incomplete trips can produce extreme catch/effort ratios that dominate variance estimation. Following Hoenig et al. (1997), the default truncate_at = 0.5 hours (30 minutes) excludes trips shorter than this threshold before MOR estimation. The survey design is rebuilt with the truncated sample for correct variance computation. Set truncate_at = NULL to disable truncation (research mode only). Truncation only applies to MOR estimator; ratio-of-means ignores this parameter.

The function performs sample size validation before estimation: errors if n < 10 (ungrouped or any group), warns if 10 <= n < 30. For MOR, validation uses the post-truncation sample size. This follows best practices for ratio estimation stability.

When grouped estimation is used (by is not NULL), survey::svyby() correctly accounts for domain estimation variance.

Variance estimation methods:

• "taylor" (default): Taylor linearization, computationally efficient and appropriate for smooth statistics like ratios.

• "bootstrap": Bootstrap resampling with 500 replicates. Appropriate for verifying Taylor assumptions.

• "jackknife": Jackknife resampling (automatic JKn or JK1 selection based on design). Alternative resampling method.

Value

A creel_estimates S3 object (list) with components: estimates (tibble with estimate, se, ci_lower, ci_upper, n columns, plus grouping columns if by is specified), method (character: names the estimator and the shape of the result. The base names are "ratio-of-means-cpue", "mean-of-ratios-cpue", "mean-of-ratios-truncated-cpue" and "regression-cpue", each gaining a "-sections" suffix on a sectioned design. The "-species" suffix, and the "-per-angler" suffix when normalized, mark a species-level and an angler-normalized result respectively; "regression-cpue-species" is returned for a species request under estimator = "regression"), variance_method (character: the variance that actually ran, which is the variance argument for every estimator except "regression" – the regression slope carries a leave-one-out jackknife SE and reports "jackknife" whatever variance was set to), design (reference to source creel_design), conf_level (numeric), and by_vars (character vector of grouping variable names or NULL). The estimator component records the estimator as you asked for it, "mortr" included, which method cannot: it reports mandatory truncation and the default threshold with the same string.

Package Options

Complete Trip Percentage Threshold: The package option tidycreel.min_complete_pct controls the threshold for complete trip percentage warnings (default: 0.10 = 10\ percentage of complete trips falls below this threshold, a warning is issued referencing Pollock et al. roving-access design best practices. Users can set a custom threshold for their session:

options(tidycreel.min_complete_pct = 0.05)

The default 10\ scientifically valid estimation. Lowering the threshold is appropriate only for special cases with documented justification. Warnings help ensure data quality and guide users toward diagnostic validation when complete trip samples are insufficient.

Note

When called on a sectioned design, no .lake_total row is produced. Catch rates (fish per angler-hour) are not additive across sections. Lake-wide catch rate requires a separate unsectioned call on the full design. See estimate_total_catch() for lake-wide total catch estimation.

estimator = "regression" on a sectioned design fits one regression per section, on that section's interviews alone. The leave-one-out jackknife standard error therefore rests on the interviews in that section rather than on the whole sample, so section-level regression standard errors are based on fewer points than the unsectioned form and are correspondingly less stable. This is a property of sectioning rather than of the estimator; a section with fewer than three interviews cannot be fitted at all. species in by fits one regression per species, on that species' catch against the same angler effort, with zero-catch interviews retained by default.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

# Basic ungrouped CPUE
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

interviews <- data.frame(
  date = as.Date(rep(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04"), each = 10)),
  catch_total = rpois(40, lambda = 3),
  hours_fished = runif(40, min = 1, max = 6),
  trip_status = rep(c("complete", "incomplete"), each = 20),
  trip_duration = runif(40, min = 1, max = 6)
)

design_with_interviews <- add_interviews(design, interviews,
  catch = catch_total,
  effort = hours_fished,
  trip_status = trip_status,
  trip_duration = trip_duration
)
result <- estimate_catch_rate(design_with_interviews)
print(result)

# Grouped by day_type
result_grouped <- estimate_catch_rate(design_with_interviews, by = day_type)
print(result_grouped)

# Custom confidence level
result_90 <- estimate_catch_rate(design_with_interviews, conf_level = 0.90)

# Bootstrap variance estimation
result_boot <- estimate_catch_rate(design_with_interviews, variance = "bootstrap")

# Mean-of-ratios for incomplete trips
result_mor <- estimate_catch_rate(design_with_interviews, estimator = "mor")

# Mean-of-ratios with custom truncation threshold
result_mor_1h <- estimate_catch_rate(design_with_interviews, estimator = "mor", truncate_at = 1.0)

Estimate total effort from a creel survey design

Description

Computes total effort estimates with standard errors and confidence intervals from a creel survey design with attached count data. Wraps survey::svytotal() (ungrouped) or survey::svyby() (grouped) with Tier 2 validation and domain-specific output formatting.

Usage

estimate_effort(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  target = c("sampled_days", "stratum_total", "period_total"),
  verbose = FALSE,
  aggregate_sections = TRUE,
  method = "correlated",
  missing_sections = "warn"
)

Arguments

Details

The function performs Tier 2 validation before estimation, issuing warnings (not errors) for: zero values in count variables, negative values in count variables, and sparse strata (< 3 observations). When grouped estimation is used (by is not NULL), additional warnings are issued for sparse groups (< 3 observations per group level).

Grouped estimation uses survey::svyby() internally, which correctly accounts for domain estimation variance. This is different from naive subsetting, which would underestimate variance.

Variance estimation methods:

• "taylor" (default): Taylor linearization, computationally efficient and appropriate for most smooth statistics. This is the recommended default.

• "bootstrap": Bootstrap resampling with 500 replicates. Appropriate for non-smooth statistics or verifying Taylor assumptions. More computationally intensive than Taylor.

• "jackknife": Jackknife resampling (automatic JKn or JK1 selection based on design). Alternative resampling method, deterministic unlike bootstrap.

Value

A creel_estimates S3 object (list) with components: estimates (tibble with estimate, se, se_between, se_within, ci_lower, ci_upper, n columns, plus grouping columns if by is specified), method (character: "total"), variance_method (character: reflects the variance parameter value used), design (reference to source creel_design), conf_level (numeric), and by_vars (character vector of grouping variable names or NULL). se_between is the between-day standard error from survey::svytotal() (equals se when a single count is recorded per PSU). se_within is the within-day standard error from the Rasmussen two-stage formula; it is zero when a single count is recorded per PSU and nonzero when count_time_col is supplied to add_counts(). For bus-route designs, a "site_contributions" attribute is also present containing per-site e_i, pi_i, and e_i_over_pi_i columns.

For sectioned designs the tibble carries one row per registered section plus, when aggregate_sections = TRUE, a .lake_total row, and gains section, prop_of_lake_total, se_prop_of_lake_total and data_available columns. prop_of_lake_total is the section's share of the lake-wide total and se_prop_of_lake_total its standard error; both come from one survey::svyratio() call, which accounts for the correlation between a domain total and the overall total containing it. On the .lake_total row the share is exactly 1 with a standard error of 0, which is structural rather than an unpropagated component: that row's share of itself was never estimated. A section registered by add_sections but absent from the counts reports NA for both, alongside data_available = FALSE.

Camera designs are refused

This function estimates instantaneous, bus-route, ice, aerial and sectioned designs. It refuses a camera design, with condition class creel_error_camera_generic_estimator.

A camera count is a daily total of arrivals, not an instantaneous count of anglers present, so summing it over days gives arrivals rather than effort. Because camera had no branch in the dispatch below, such a design used to fall through to the instantaneous path and return that sum – a plausible number with a plausible standard error, and no indication that it was not effort.

Use est_effort_camera, which calibrates the counts against interview effort and propagates the calibration's uncertainty, or est_effort_camera_mi to pool over multiply imputed counts. The same refusal is raised by estimate_total_catch, estimate_total_harvest and estimate_total_release, which build their own effort by this route.

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

# Basic ungrouped usage
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

counts <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend"),
  effort_hours = c(15, 23, 45, 52)
)

design_with_counts <- add_counts(design, counts)
result <- estimate_effort(design_with_counts)
print(result)

# Grouped by day_type
result_grouped <- estimate_effort(design_with_counts, by = day_type)
print(result_grouped)

# Several grouping variables can be combined in `by` when the data carry them

# Custom confidence level
result_90 <- estimate_effort(design_with_counts, conf_level = 0.90)

# Bootstrap variance estimation
result_boot <- estimate_effort(design_with_counts, variance = "bootstrap")
print(result_boot)

# Jackknife variance estimation
result_jk <- estimate_effort(design_with_counts, variance = "jackknife")
print(result_jk)

# Grouped estimation with bootstrap variance
result_grouped_boot <- estimate_effort(design_with_counts, by = day_type, variance = "bootstrap")

# Verbose dispatch message (shows which estimator was used for bus-route designs)
result_verbose <- estimate_effort(design_with_counts, verbose = TRUE)

GLMM-based aerial effort estimation with diurnal correction

Description

Estimates total angler effort from aerial creel surveys using a generalized linear mixed model (GLMM), following the approach of Askey et al. (2018). When flights occur at non-random times of day, simple scaling of instantaneous counts can over- or under-estimate daily effort. This function fits a negative-binomial GLMM (or user-specified family) to model how angler counts change through the day, then integrates the fitted diurnal curve over the fishing day to obtain a bias-corrected effort estimate.

The default model is the quadratic temporal model from Askey (2018): count ~ poly(time_col, 2) + (1 | date), fitted via lme4::glmer.nb(). Variance is propagated via the delta method (default) or parametric bootstrap (lme4::bootMer()).

Usage

estimate_effort_aerial_glmm(
  design,
  time_col,
  formula = NULL,
  family = NULL,
  boot = FALSE,
  nboot = 500L,
  conf_level = 0.95,
  target = c("sampled_days", "mean_day")
)

Arguments

Details

The fitted curve is a fixed-effects prediction: the day whose random intercept is zero. On a log link that is the median day rather than the mean one, so summing it across days would understate the total. Both targets therefore carry a factor of exp(sigma^2 / 2), where sigma^2 is the day-level intercept variance — 4% on the package's own fixture, and larger where days vary more.

That factor treats sigma^2 as known. The reported standard error scales with the expansion but does not carry the uncertainty in the variance component itself, so it is mildly optimistic; quantifying that would need a variance method neither the delta nor the bootstrap path offers today.

Value

A creel_estimates object with:

• estimate: total angler effort integrated over the fishing day

• se: standard error (delta method or bootstrap SD)

• se_between: same as se (fixed-effect SE component)

• se_within: always NA_real_ — no Rasmussen within-day decomposition is performed for GLMM estimates

• ci_lower, ci_upper: confidence interval bounds, and NA_real_ whenever se is, on both the delta and bootstrap paths. If the visibility correction or the angler-to-people ratio was declared unknown, the total's uncertainty was never fully propagated, so no unconditional interval exists to report. Reporting the remaining spread would be an interval conditional on the unknown multiplier being exact – indistinguishable from declaring it known with zero uncertainty, which is precisely the confusion NA exists to prevent.

• n: number of count observations used to fit the model

• method: "aerial_glmm_total"

References

Askey, P.J., Ward, H., Godin, T., Boucher, M., and Northrup, S. (2018). Angler effort estimates from instantaneous aerial counts: use of high-frequency time-lapse camera data to inform model-based estimators. North American Journal of Fisheries Management, 38, 194-209. doi:10.1002/nafm.10010

See Also

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

data(example_aerial_glmm_counts)

aerial_cal <- unique(example_aerial_glmm_counts[, c("date", "day_type")])
aerial_cal <- aerial_cal[order(aerial_cal$date), ]
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
)
design <- add_counts(design, example_aerial_glmm_counts, count_col = n_anglers)

# Default Askey quadratic model with delta-method SE
result <- estimate_effort_aerial_glmm(design, time_col = time_of_flight)
print(result)

# Bootstrap CIs. `nboot` is held low here so the example stays fast on a
# check machine; use at least 1000 replicates for real inference. The block
# is wrapped in \donttest{} for runtime alone -- it needs no resource the
# example cannot reach.

result_boot <- estimate_effort_aerial_glmm(
  design,
  time_col = time_of_flight,
  boot = TRUE,
  nboot = 25L
)
print(result_boot)

Compute effort density as effort per acre

Description

Divides all effort estimate columns in a pre-computed creel_estimates object by a surface area scalar (acres). Standard error propagates linearly because acres is a constant (not a random variable), so no Delta Method is needed: se_per_acre = se_effort / acres.

acres is a constant divisor, so the result is whatever the effort was, per acre: the returned unit field composes the effort's own unit ("angler-hours/acre", "party-hours/acre"), and stays NA when the effort's unit was unknown.

This is a composable estimator: the effort object must be pre-computed via estimate_effort before calling this function.

Usage

estimate_effort_per_acre(effort, acres, ...)

Arguments

Value

A creel_estimates object with method = "effort-per-acre". The estimates tibble has the same rows as the input but with estimate, se, ci_lower, ci_upper (and se_between, se_within when present in the input) all divided by acres. Grouping columns (by_vars) and n are carried through unchanged. variance_method and conf_level are inherited from the input effort object.

See Also

estimate_effort, estimate_angler_trips

Examples

data(example_calendar)
data(example_counts)
data(example_interviews)
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, harvest = catch_kept,
  trip_status = trip_status
)
effort <- estimate_effort(design)
# Surface area of the water body, in acres.
estimate_effort_per_acre(effort, acres = 120)

Estimate exploitation rate using the Pollock et al. moment estimator

Description

Computes the seasonal exploitation rate from a combination of a tagging study and creel-survey harvest data using the moment estimator described in Pollock et al. (1994) and Jones & Pollock (2012, Ch. 19).

When strata is supplied the function takes the stratified path and returns per-stratum estimates plus a T-weighted aggregate (.overall row).

Usage

estimate_exploitation_rate(
  T = NULL,
  C = NULL,
  se_C = NULL,
  n = NULL,
  m = NULL,
  conf_level = 0.95,
  reporting_rate = 1,
  reporting_rate_se = NULL,
  strata = NULL,
  by = NULL,
  aggregate = TRUE,
  ci_type = c("symmetric", "logit")
)

Arguments

Details

Unstratified Formula

Let:

• p = m / n — proportion of tagged fish among inspected fish,

• r = C / T — ratio of estimated harvest to tagged fish released.

The point estimate is:

\hat{u} = r \cdot p = \frac{C \cdot m}{T \cdot n}

Delta-method variance:

\widehat{\mathrm{Var}}(\hat{u}) \approx r^2 \cdot \frac{p(1-p)}{n} + p^2 \cdot \frac{s_C^2}{T^2}

where s_C is se_C, the standard error of the creel harvest estimate.

Stratified Formula

For stratum h, the per-stratum exploitation rate is:

\hat{u}_h = \frac{C_h \cdot m_h}{T_h \cdot n_h}

with delta-method variance:

\widehat{\mathrm{Var}}(\hat{u}_h) \approx r_h^2 \cdot \frac{p_h(1-p_h)}{n_h} + p_h^2 \cdot \frac{s_{C_h}^2}{T_h^2}

The T-weighted aggregate over H strata is:

\hat{u} = \frac{\sum_h T_h \hat{u}_h}{\sum_h T_h}

with variance:

\widehat{\mathrm{Var}}(\hat{u}) = \frac{\sum_h T_h^2 \, \widehat{\mathrm{Var}}(\hat{u}_h)}{(\sum_h T_h)^2}

This is the estimator from Jones CM & Pollock KH (2012, Ch. 19) and Pollock KH, Jones CM & Brown TL (1994).

Reporting Rate Adjustment

When reporting_rate = \lambda < 1, the adjusted estimate is \hat{u}_{adj} = \hat{u} / \lambda and the variance is divided by \lambda^2.

\lambda is treated as known without error unless reporting_rate_se is supplied. When it is, a third delta term is added, since \partial \hat{u} / \partial \lambda = -\hat{u}/\lambda:

\widehat{\mathrm{Var}}(\hat{u}) = \frac{r^2 \widehat{\mathrm{Var}}(p) + p^2 \widehat{\mathrm{Var}}(r)}{\lambda^2} + \frac{\hat{u}^2}{\lambda^2} \widehat{\mathrm{Var}}(\lambda)

That term is added once, at the total. \lambda is a single estimate dividing every stratum, so it is perfectly correlated across them; adding it per stratum and summing in quadrature would treat a shared divisor as independent and understate it. On the stratified path it therefore enters on the aggregate, not inside the per-stratum variances.

Natural mortality between tagging and the creel survey is not corrected for.

Bounds

Exploitation rate must lie in [0, 1]. If the point estimate or CI endpoints fall outside this range, a warning is issued and CI bounds are clamped to [0, 1].

Value

A creel_estimates S3 object with method = "exploitation-rate" and an estimates tibble. For the unstratified path columns are: estimate, se, ci_lower, ci_upper, n, T, C, m. For the stratified path the stratum label column comes first, followed by the same columns.

References

Pollock KH, Jones CM & Brown TL (1994). Angler Survey Methods and Their Applications in Fisheries Management. AFS Special Publication 25. American Fisheries Society.

Jones CM & Pollock KH (2012). Recreational survey methods: estimating effort, harvest, and abundance. In Zale AV et al. (eds), Fisheries Techniques (3rd ed., Ch. 19). American Fisheries Society.

See Also

Other Estimation: estimate_angler_n(), estimate_mr_harvest()

Examples

# Unstratified exploitation rate
result <- estimate_exploitation_rate(
  T    = 200L,
  C    = 450.0,
  se_C = 42.0,
  n    = 180L,
  m    = 15L
)
print(result)

# Stratified exploitation rate
strata_df <- data.frame(
  stratum = c("weekday", "weekend"),
  T_h     = c(120L, 80L),
  C_h     = c(280.0, 170.0),
  se_C_h  = c(28.0, 22.0),
  n_h     = c(110L, 70L),
  m_h     = c(9L, 6L)
)
result_strat <- estimate_exploitation_rate(
  strata = strata_df,
  by     = "stratum"
)
print(result_strat)

Estimate harvest (HPUE: Harvest Per Unit Effort) from a creel survey design

Description

Computes HPUE estimates with standard errors and confidence intervals from a creel survey design with attached interview data. Uses ratio-of-means estimation via survey::svyratio() to properly account for ratio variance. HPUE measures the rate of kept fish (harvest) per unit effort, distinguished from total catch rate (CPUE which includes both kept and released fish).

Usage

estimate_harvest_rate(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  verbose = FALSE,
  use_trips = NULL,
  estimator = NULL,
  truncate_at = 0.5,
  missing_sections = "warn",
  targeted = TRUE
)

Arguments

Details

HPUE is estimated as the ratio of total harvest (kept fish) to total effort (ratio-of-means estimator). This is the appropriate estimator for average harvest rates when trip lengths (effort) vary. The function uses survey::svyratio() internally, which correctly accounts for the correlation between harvest and effort in variance estimation.

HPUE will always be less than or equal to CPUE for the same data, since harvest (kept fish) is a subset of total catch.

The function performs sample size validation before estimation: errors if n < 10 (ungrouped or any group), warns if 10 <= n < 30. This follows best practices for ratio estimation stability.

When grouped estimation is used (by is not NULL), survey::svyby() with svyratio correctly accounts for domain estimation variance.

Variance estimation methods:

• "taylor" (default): Taylor linearization, computationally efficient and appropriate for smooth statistics like ratios.

• "bootstrap": Bootstrap resampling with 500 replicates. Appropriate for verifying Taylor assumptions.

• "jackknife": Jackknife resampling (automatic JKn or JK1 selection based on design). Alternative resampling method.

Value

A creel_estimates S3 object (list) with components: estimates (tibble with estimate, se, ci_lower, ci_upper, n columns, plus grouping columns if by is specified), method (character: "ratio-of-means-hpue", with "-per-angler" suffix when normalized), variance_method (character: reflects the variance parameter value used), design (reference to source creel_design), conf_level (numeric), and by_vars (character vector of grouping variable names or NULL). The estimator component records the estimator as you asked for it, "mortr" included, which method cannot: it reports mandatory truncation and the default threshold with the same string. For bus-route designs, a "site_contributions" attribute is also present.

Note

Bus-route designs use a different estimator for each trip type, because each is the estimator that trip type supports. use_trips = "complete" returns the ratio of the two Horvitz-Thompson totals (Jones & Pollock 2012, Eq. 19.4 and 19.5). use_trips = "incomplete" returns a truncated, design-weighted mean of the individual angler rates (Hoenig et al. 1997), whose expectation is the ratio of total harvest to total effort; the ratio of means is biased for anglers intercepted mid-trip, weighting individual rates by the square of completed trip length. Both report fish per angler-hour, so use_trips = "diagnostic" compares like with like.

When called on a sectioned design, no .lake_total row is produced. Harvest rates (fish per angler-hour) are not additive across sections. Lake-wide harvest rate requires a separate unsectioned call.

This function defaults to using completed-trip interviews only for HPUE estimation (use_trips = "complete"). Incomplete-trip HPUE underestimates harvest when anglers continue fishing and keep additional fish after being interviewed (Hansen & Van Kirk 2010), so restricting to completed trips is the statistically preferred default. Fish already in the livewell at interview time are directly observable, so use_trips = "all" remains available to include incomplete-trip interviews.

See Also

estimate_catch_rate for total catch rate estimation

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_release_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

# Basic ungrouped HPUE
calendar <- data.frame(
  date = as.Date(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04")),
  day_type = c("weekday", "weekday", "weekend", "weekend")
)
design <- creel_design(calendar, date = date, strata = day_type)

set.seed(123)
interviews <- data.frame(
  date = as.Date(rep(c("2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04"), each = 10)),
  catch_total = rpois(40, lambda = 3),
  hours_fished = runif(40, min = 1, max = 6),
  trip_status = rep(c("complete", "incomplete"), each = 20),
  trip_duration = runif(40, min = 1, max = 6)
)
# Harvest is subset of catch (kept fish)
interviews$catch_kept <- pmax(0, interviews$catch_total - rbinom(40, size = 2, prob = 0.3))

design_with_interviews <- add_interviews(design, interviews,
  catch = catch_total,
  harvest = catch_kept,
  effort = hours_fished,
  trip_status = trip_status,
  trip_duration = trip_duration
)
result <- estimate_harvest_rate(design_with_interviews)
print(result)

# Grouped by day_type
result_grouped <- estimate_harvest_rate(design_with_interviews, by = day_type)
print(result_grouped)

# Custom confidence level
result_90 <- estimate_harvest_rate(design_with_interviews, conf_level = 0.90)

# Bootstrap variance estimation
result_boot <- estimate_harvest_rate(design_with_interviews, variance = "bootstrap")

# Verbose dispatch message (shows which estimator was used for bus-route designs)
result_verbose <- estimate_harvest_rate(design_with_interviews, verbose = TRUE)

Estimate total harvest from a mark-recapture population estimate

Description

Computes a total harvest estimate and its uncertainty using the delta method, given a closed-population angler population estimate from estimate_angler_n and a known harvest rate.

The point estimate is \hat{H} = \hat{N} \times r where r is the harvest rate in fish per angler. The delta-method standard error is SE(\hat{H}) = r \times SE(\hat{N}), propagating only the uncertainty in \hat{N} (harvest-rate uncertainty is not propagated in this release).

Usage

estimate_mr_harvest(
  angler_n,
  harvest_rate,
  harvest_rate_se = NULL,
  conf_level = 0.95,
  ci_method = c("logit", "delta", "bootstrap")
)

Arguments

Details

The harvest rate is treated as a known constant. This is a simplification made by this implementation, not by the cited method: Hansen & Van Kirk (2018) estimate both factors of the rate, give each a log-normal sampling distribution, and resample them alongside \hat{N} in the bootstrap that produces their harvest CIs. Holding the rate fixed therefore makes the reported se a lower bound on the true uncertainty. Propagation of harvest-rate uncertainty via a two-source delta method is a planned future extension.

The delta-method interval is also symmetric, which for a mark-recapture estimate is optimistic at the lower end and can place ci_lower below zero when recaptures are few; see the same note under estimate_angler_n.

Value

A creel_estimates S3 object with method = "mark-recapture-harvest" and an estimates tibble with columns: parameter, estimate, se, ci_lower, ci_upper.

References

Hansen, J. M., & Van Kirk, R. W. (2018). A mark-recapture-based approach for estimating angler harvest. North American Journal of Fisheries Management, 38(2), 400–410. doi:10.1002/nafm.10038

See Also

Other Estimation: estimate_angler_n(), estimate_exploitation_rate()

Examples

# Step 1: estimate angler population
result <- estimate_angler_n(M = 200L, n = 50L, m = 10L)

# Step 2: compute total harvest
harvest <- estimate_mr_harvest(angler_n = result, harvest_rate = 0.35)
print(harvest)

Estimate release rate (RPUE: Released fish Per Unit Effort) from a creel survey design

Description

Computes release rate estimates with standard errors and confidence intervals from a creel survey design with attached interview and catch data. Uses ratio-of-means estimation via survey::svyratio(). RPUE measures the rate of released fish per unit effort, analogous to HPUE for harvested fish.

Usage

estimate_release_rate(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  use_trips = NULL,
  estimator = NULL,
  truncate_at = 0.5,
  missing_sections = "warn",
  targeted = TRUE
)

Arguments

Details

RPUE is estimated as the ratio of total released fish to total effort (ratio-of-means). Release data comes from add_catch() records with catch_type = "released". Interviews with no releases contribute 0 to the numerator (zero-fill), ensuring the effort denominator is correct.

Value

A creel_estimates S3 object with method = "ratio-of-means-rpue". Estimates tibble has columns: estimate, se, ci_lower, ci_upper, n (plus any grouping columns). The estimator component records the estimator as you asked for it, "mortr" included, which method cannot: it reports mandatory truncation and the default threshold with the same string.

Note

Bus-route designs use a different estimator for each trip type, matching estimate_harvest_rate. use_trips = "complete" returns the ratio of the two Horvitz-Thompson totals (Jones & Pollock 2012, Eq. 19.5 / Eq. 19.4) and reports method = "ratio-of-means-rpue"; use_trips = "incomplete" returns the truncated, Hajek-weighted mean of per-angler rates (Hoenig et al. 1997) and reports method = "mean-of-ratios-rpue". Both are releases per angler-hour.

When called on a sectioned design, no .lake_total row is produced. Release rates (fish per angler-hour) are not additive across sections. Lake-wide release rate requires a separate unsectioned call.

This function defaults to using completed-trip interviews only for RPUE estimation (use_trips = "complete"). Incomplete-trip RPUE may underestimate releases if anglers release additional fish after the interview (Hansen & Van Kirk 2010), so restricting to completed trips is the statistically preferred default. Released fish counted at interview time are directly observable, so use_trips = "all" remains available to include incomplete-trip interviews.

See Also

estimate_harvest_rate for harvest rate, add_catch

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_total_catch(), estimate_total_harvest(), estimate_total_release()

Examples

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

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished,
  trip_status = trip_status, trip_duration = trip_duration
)
design <- add_catch(design, example_catch,
  catch_uid = interview_id,
  interview_uid = interview_id,
  species = species,
  count = count,
  catch_type = catch_type
)

# Overall release rate (all species combined)
rpue <- estimate_release_rate(design)
print(rpue)

# Per-species release rates
rpue_by_species <- estimate_release_rate(design, by = species)
print(rpue_by_species)

Estimate total catch by combining effort and CPUE

Description

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

Usage

estimate_total_catch(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  target = c("sampled_days", "stratum_total", "period_total"),
  use_trips = NULL,
  estimator = NULL,
  truncate_at = 0.5,
  aggregate_sections = TRUE,
  missing_sections = "warn",
  verbose = FALSE,
  ci_method = c("delta", "bootstrap"),
  product_variance = c("goodman", "first_order"),
  ci_type = c("symmetric", "log")
)

Arguments

Details

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

Var(E \times C) \approx E^2 \cdot Var(C) + C^2 \cdot Var(E)

Variance is computed via a stratified delta-method sum in compute_stratum_product_sum(), not via survey::svycontrast().

Sectioned designs: When add_sections has been called on the design, each section is estimated independently using its own count survey (via rebuild_counts_survey) and interview survey (via rebuild_interview_survey). The lake-wide total is the arithmetic sum sum(TC_i), not E_total * CPUE_pooled. The lake-wide SE uses the zero-covariance assumption: sqrt(sum(se_i^2)). Cross-section covariance between count-based effort and interview-based CPUE designs is not identified and is therefore assumed zero.

by = <species> is supported on a sectioned design: catch is apportioned against each section's own whole effort, giving one row per section per species. As with any other grouping, the sectioned result then carries no .lake_total row and no prop_of_lake_total.

Design compatibility requirements:

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

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

• Grouped estimation requires identical grouping variables for both estimates

• Calendar stratification must be shared between counts and interviews

Value

A creel_estimates S3 object with method = "product-total-catch". The estimator component records the rate estimator this total is a product of, as you asked for it: method names the product form and is the same string whichever estimator produced it. For bus-route and ice designs, returns a bus-route HT estimate with method = "ht-total-catch" and a "site_contributions" attribute. For sectioned designs, returns per-section rows plus (by default) a .lake_total row. The lake-wide total is computed as sum(TC_i) over sections, never as E_total * CPUE_pooled.

For sectioned designs the per-section rows carry prop_of_lake_total, the section's share of the lake-wide total, and se_prop_of_lake_total, its standard error. The share is a ratio whose numerator is one of its own denominator's terms, and whose numerator and denominator are each products of an effort and a rate estimated from different designs, so the error is derived by delta method from the same section variances and covariance the .lake_total row's own standard error is built from. The .lake_total row reports se_prop_of_lake_total = 0: its share of itself is exactly 1 by construction and was never estimated. A section with no data reports NA for both. Neither column is produced on the grouped path.

Why there is no targeted argument

The rate functions accept targeted = FALSE, which restricts the domain to the interviews that recorded some of the species being estimated. The totals deliberately do not, because a total is a rate multiplied by an effort base and the two would no longer describe the same set of trips.

A targeted rate is conditional on having recorded the species; total effort is not. Multiplying one by the other applies a conditional rate to an unconditional base. On the package's own example data one species' rate is 0.48 fish/hr over all 50 trips and 2.00 fish/hr over the 12 that caught it, so expanding the targeted rate by total effort returns roughly 223 fish where 30 were actually caught.

The domain-consistent product — the targeted rate times the effort of the trips that recorded the species — is well defined in the sample but cannot be expanded: it needs the season-wide effort of species-catching trips, which no creel design observes.

So a targeted rate is available and a targeted total is not, and that is a property of the estimand rather than a gap in the implementation (GH #307).

What the pooled total assumes

Effort comes from the counts, so a total can only be broken down by an attribute the counts classify. When a domain appears in the interviews but not in the counts, the only available total is E_total * rate_pooled, where the pooled rate is a ratio of means weighted by the interview sample's composition over that domain. Had the domain been classified in the counts it would be a stratum and the total would be sum(E_h * rate_h), which is unbiased whatever the interview composition happens to be.

The two agree only when the interview sample's effort composition matches the true effort composition, and interview selection is not proportional to effort by construction of the standard designs. Access interviews intercept completed trips, over-representing anglers who must return to a fixed point: Malvestuto (1996) notes that it is “usually impossible to sample all angler types proportional to their level of effort”, a particular problem for bank anglers who may be “widely dispersed along the shoreline and not associated with well-defined access sites”. Roving interviews are length-biased toward longer trips. So the mix differs by design rather than by accident, and where levels differ in rate the pooled total inherits that difference.

None of this is verifiable from within the data, because the counts carry no composition to compare against. Where it is detectable – the interviews hold an unclassified categorical domain and the crude rate differs materially across its levels – a warning of class creel_warning_pooled_domain_mix is raised. It flags a risk, not a defect. Classifying the domain in the count data is what removes the assumption.

Unit of the total

The reported unit is derived from the two factors, never declared. A total is "fish" only when a per-angler-hour rate multiplies an effort in angler-hours; anything else reports NA_character_, meaning unknown.

Two ways to fail to cancel:

• The effort unit is unknown. design$effort_unit is NA whenever add_counts() received no period_length_col, because a bare count column may be an instantaneous head count or effort the caller already expanded, and nothing can tell the two apart. Unknown times known is unknown. Supply period_length_col to make the total's unit derivable.

• The denominators disagree. A rate per party-hour times an effort in angler-hours is not a count of fish. Pass n_anglers to add_interviews() so the rate is per angler-hour.

The estimate itself is unaffected in both cases – only the label changes. Until version 5.2.0 the unit was the literal "fish" regardless of either factor (GH #213).

See Also

estimate_effort, estimate_catch_rate

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), estimate_catch_rate(), estimate_effort(), estimate_effort_aerial_glmm(), estimate_harvest_rate(), estimate_release_rate(), estimate_total_harvest(), estimate_total_release()

Examples

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

# Create design with both counts and interviews
design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)
design <- add_interviews(design, example_interviews,
  catch = catch_total, effort = hours_fished, n_anglers = n_anglers,
  trip_status = trip_status, trip_duration = trip_duration
)

# Estimate total catch
total_catch <- estimate_total_catch(design)
print(total_catch)

# Compare components
effort_est <- estimate_effort(design)
cpue_est <- estimate_catch_rate(design)
# The total is close to, but not exactly, effort times CPUE
c(
  total = total_catch$estimates$estimate,
  effort_x_cpue = effort_est$estimates$estimate * cpue_est$estimates$estimate
)

# Grouped estimation needs at least 10 interviews per group, so check
# the sample sizes before grouping
table(design$interviews$day_type)

# Verbose dispatch message (shows which estimator was used for bus-route designs)
result_verbose <- estimate_total_catch(design, verbose = TRUE)

Estimate total harvest by combining effort and HPUE

Description

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"),
  use_trips = NULL,
  estimator = NULL,
  truncate_at = 0.5,
  aggregate_sections = TRUE,
  missing_sections = "warn",
  ci_method = c("delta", "bootstrap"),
  product_variance = c("goodman", "first_order"),
  ci_type = c("symmetric", "log")
)

Arguments

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)

Variance is computed via a stratified delta-method sum in compute_stratum_product_sum(), not via survey::svycontrast().

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)).

by = <species> is supported on a sectioned design: catch is apportioned against each section's own whole effort, giving one row per section per species. As with any other grouping, the sectioned result then carries no .lake_total row and no prop_of_lake_total.

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

Value

A creel_estimates S3 object with method = "product-total-harvest". The estimator component records the rate estimator this total is a product of, as you asked for it: method names the product form and is the same string whichever estimator produced it. For bus-route and ice designs, returns a bus-route HT estimate with method = "ht-total-harvest" and a "site_contributions" attribute.

For sectioned designs the per-section rows carry prop_of_lake_total, the section's share of the lake-wide total, and se_prop_of_lake_total, its standard error. The share is a ratio whose numerator is one of its own denominator's terms, and whose numerator and denominator are each products of an effort and a rate estimated from different designs, so the error is derived by delta method from the same section variances and covariance the .lake_total row's own standard error is built from. The .lake_total row reports se_prop_of_lake_total = 0: its share of itself is exactly 1 by construction and was never estimated. A section with no data reports NA for both. Neither column is produced on the grouped path.

Why there is no targeted argument

The rate functions accept targeted = FALSE, which restricts the domain to the interviews that recorded some of the species being estimated. The totals deliberately do not, because a total is a rate multiplied by an effort base and the two would no longer describe the same set of trips.

A targeted rate is conditional on having recorded the species; total effort is not. Multiplying one by the other applies a conditional rate to an unconditional base. On the package's own example data one species' rate is 0.48 fish/hr over all 50 trips and 2.00 fish/hr over the 12 that caught it, so expanding the targeted rate by total effort returns roughly 223 fish where 30 were actually caught.

The domain-consistent product — the targeted rate times the effort of the trips that recorded the species — is well defined in the sample but cannot be expanded: it needs the season-wide effort of species-catching trips, which no creel design observes.

So a targeted rate is available and a targeted total is not, and that is a property of the estimand rather than a gap in the implementation (GH #307).

What the pooled total assumes

Effort comes from the counts, so a total can only be broken down by an attribute the counts classify. When a domain appears in the interviews but not in the counts, the only available total is E_total * rate_pooled, where the pooled rate is a ratio of means weighted by the interview sample's composition over that domain. Had the domain been classified in the counts it would be a stratum and the total would be sum(E_h * rate_h), which is unbiased whatever the interview composition happens to be.

The two agree only when the interview sample's effort composition matches the true effort composition, and interview selection is not proportional to effort by construction of the standard designs. Access interviews intercept completed trips, over-representing anglers who must return to a fixed point: Malvestuto (1996) notes that it is “usually impossible to sample all angler types proportional to their level of effort”, a particular problem for bank anglers who may be “widely dispersed along the shoreline and not associated with well-defined access sites”. Roving interviews are length-biased toward longer trips. So the mix differs by design rather than by accident, and where levels differ in rate the pooled total inherits that difference.

None of this is verifiable from within the data, because the counts carry no composition to compare against. Where it is detectable – the interviews hold an unclassified categorical domain and the crude rate differs materially across its levels – a warning of class creel_warning_pooled_domain_mix is raised. It flags a risk, not a defect. Classifying the domain in the count data is what removes the assumption.

Unit of the total

The reported unit is derived from the two factors, never declared. A total is "fish" only when a per-angler-hour rate multiplies an effort in angler-hours; anything else reports NA_character_, meaning unknown.

Two ways to fail to cancel:

• The effort unit is unknown. design$effort_unit is NA whenever add_counts() received no period_length_col, because a bare count column may be an instantaneous head count or effort the caller already expanded, and nothing can tell the two apart. Unknown times known is unknown. Supply period_length_col to make the total's unit derivable.

• The denominators disagree. A rate per party-hour times an effort in angler-hours is not a count of fish. Pass n_anglers to add_interviews() so the rate is per angler-hour.

The estimate itself is unaffected in both cases – only the label changes. Until version 5.2.0 the unit was the literal "fish" regardless of either factor (GH #213).

See Also

estimate_effort, estimate_harvest_rate, estimate_total_catch

Other "Estimation": compare_cpue_estimators(), est_age_distribution(), est_biomass(), est_compliance(), est_effort_camera_mi(), est_length_distribution(), est_mean_age(), est_mean_length(), 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)
design <- add_interviews(design, example_interviews,
  catch = catch_total, harvest = catch_kept, effort = hours_fished,
  n_anglers = n_anglers,
  trip_status = trip_status, trip_duration = trip_duration
)

# Estimate total harvest
total_harvest <- estimate_total_harvest(design)
print(total_harvest)

# Compare components
effort_est <- estimate_effort(design)
hpue_est <- estimate_harvest_rate(design)
# The total is close to, but not exactly, effort times HPUE
c(
  total = total_harvest$estimates$estimate,
  effort_x_hpue = effort_est$estimates$estimate * hpue_est$estimates$estimate
)

# Grouped estimation needs at least 10 interviews per group, so check
# the sample sizes before grouping
table(design$interviews$day_type)

Estimate total extrapolated release by combining effort and release rate

Description

Computes total release estimates by multiplying effort x RPUE with variance propagation via the delta method. Requires a creel design with count data (for effort estimation), interview data (for effort), and catch data (via add_catch) containing released records.

Usage

estimate_total_release(
  design,
  by = NULL,
  variance = "taylor",
  conf_level = 0.95,
  target = c("sampled_days", "stratum_total", "period_total"),
  use_trips = NULL,
  estimator = NULL,
  truncate_at = 0.5,
  aggregate_sections = TRUE,
  missing_sections = "warn",
  product_variance = c("goodman", "first_order"),
  ci_type = c("symmetric", "log")
)

Arguments

Details

Total release is computed as Effort x RPUE. Variance is propagated using the delta method: Var(E x R) = E^2 * Var(R) + R^2 * Var(E).

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

by = <species> is supported on a sectioned design: catch is apportioned against each section's own whole effort, giving one row per section per species. As with any other grouping, the sectioned result then carries no .lake_total row and no prop_of_lake_total.

Value

A creel_estimates S3 object with method = "product-total-release". The estimator component records the rate estimator this total is a product of, as you asked for it: method names the product form and is the same string whichever estimator produced it. Estimates tibble has columns: estimate, se, ci_lower, ci_upper, n (plus any grouping columns). For bus-route and ice designs, returns a bus-route HT estimate with method = "ht-total-release" and a "site_contributions" attribute.

For sectioned designs the per-section rows carry prop_of_lake_total, the section's share of the lake-wide total, and se_prop_of_lake_total, its standard error. The share is a ratio whose numerator is one of its own denominator's terms, and whose numerator and denominator are each products of an effort and a rate estimated from different designs, so the error is derived by delta method from the same section variances and covariance the .lake_total row's own standard error is built from. The .lake_total row reports se_prop_of_lake_total = 0: its share of itself is exactly 1 by construction and was never estimated. A section with no data reports NA for both. Neither column is produced on the grouped path.

Why there is no targeted argument

The rate functions accept targeted = FALSE, which restricts the domain to the interviews that recorded some of the species being estimated. The totals deliberately do not, because a total is a rate multiplied by an effort base and the two would no longer describe the same set of trips.

A targeted rate is conditional on having recorded the species; total effort is not. Multiplying one by the other applies a conditional rate to an unconditional base. On the package's own example data one species' rate is 0.48 fish/hr over all 50 trips and 2.00 fish/hr over the 12 that caught it, so expanding the targeted rate by total effort returns roughly 223 fish where 30 were actually caught.

The domain-consistent product — the targeted rate times the effort of the trips that recorded the species — is well defined in the sample but cannot be expanded: it needs the season-wide effort of species-catching trips, which no creel design observes.

So a targeted rate is available and a targeted total is not, and that is a property of the estimand rather than a gap in the implementation (GH #307).

What the pooled total assumes

Effort comes from the counts, so a total can only be broken down by an attribute the counts classify. When a domain appears in the interviews but not in the counts, the only available total is E_total * rate_pooled, where the pooled rate is a ratio of means weighted by the interview sample's composition over that domain. Had the domain been classified in the counts it would be a stratum and the total would be sum(E_h * rate_h), which is unbiased whatever the interview composition happens to be.

The two agree only when the interview sample's effort composition matches the true effort composition, and interview selection is not proportional to effort by construction of the standard designs. Access interviews intercept completed trips, over-representing anglers who must return to a fixed point: Malvestuto (1996) notes that it is “usually impossible to sample all angler types proportional to their level of effort”, a particular problem for bank anglers who may be “widely dispersed along the shoreline and not associated with well-defined access sites”. Roving interviews are length-biased toward longer trips. So the mix differs by design rather than by accident, and where levels differ in rate the pooled total inherits that difference.

None of this is verifiable from within the data, because the counts carry no composition to compare against. Where it is detectable – the interviews hold an unclassified categorical domain and the crude rate differs materially across its levels – a warning of class creel_warning_pooled_domain_mix is raised. It flags a risk, not a defect. Classifying the domain in the count data is what removes the assumption.

Unit of the total

The reported unit is derived from the two factors, never declared. A total is "fish" only when a per-angler-hour rate multiplies an effort in angler-hours; anything else reports NA_character_, meaning unknown.

Two ways to fail to cancel:

• The effort unit is unknown. design$effort_unit is NA whenever add_counts() received no period_length_col, because a bare count column may be an instantaneous head count or effort the caller already expanded, and nothing can tell the two apart. Unknown times known is unknown. Supply period_length_col to make the total's unit derivable.

• The denominators disagree. A rate per party-hour times an effort in angler-hours is not a count of fish. Pass n_anglers to add_interviews() so the rate is per angler-hour.