Create a creel survey design

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,
  day_start = NULL,
  night_date = "start",
  tz = NULL,
  wait_time = NULL,
  circuit_time = NULL
)

Arguments

calendar

A data frame containing calendar data with date and strata columns. Must have at least one Date column and one character/factor column (validated via internal schema check).

date

Tidy selector for the date column. Must select exactly one column of class Date. Accepts bare column names or tidyselect helpers (e.g., starts_with("date")).

strata

Tidy selector for strata columns. Can select one or more columns of class character or factor. Accepts bare column names or tidyselect helpers (e.g., c(day_type, season) or starts_with("day")).

site

Optional tidy selector for a site column. For instantaneous designs, selects from calendar. For bus-route designs (survey_type = "bus_route"), selects the site ID column from sampling_frame. Must select exactly one column of class character or factor. Default is NULL (single-site survey for instantaneous designs; required for bus-route designs).

design_type

Character string specifying the survey design type. Default is "instantaneous". Kept for backward compatibility; use survey_type for new code.

survey_type

Character string specifying the survey type. Default inherits from design_type ("instantaneous"). Use "bus_route" for nonuniform probability bus-route surveys (BUSRT-06, BUSRT-07). Both survey_type and design_type refer to the same concept; survey_type is the canonical parameter for new designs.

sampling_frame

Data frame with site, circuit, and probability columns. Required when survey_type = "bus_route". Each row represents one site-circuit sampling unit with its inclusion probability components (p_site and p_period).

p_site

Tidy selector for the site sampling probability column in sampling_frame: the probability that a pass of the circuit selects the site. Values must be in (0, 1] and must sum to 1.0 within each circuit (tolerance 1e-6). For a bus route on which the clerk visits every site on every pass, give wait_time and circuit_time instead. A bus-route design needs one of the two.

p_period

Tidy selector for the period sampling probability column in sampling_frame, OR a scalar numeric value in (0, 1] that applies globally to all rows. Required when survey_type = "bus_route".

circuit

Optional tidy selector for the circuit ID column in sampling_frame. A circuit is a route x period combination. If omitted, all rows are treated as belonging to a single unnamed circuit (".default"). Required only for multi-circuit designs.

effort_type

Character string specifying the type of effort measured in ice fishing surveys. Required when survey_type = "ice". Must be one of "time_on_ice" (total hours the angler was on the ice) or "active_fishing_time" (hours actively fishing, excluding travel/setup). The value controls the column name in estimate_effort() output: total_effort_hr_on_ice or total_effort_hr_active.

camera_mode

Character string specifying the camera sub-mode. Required when survey_type = "camera". Must be one of "counter" (camera records a daily ingress total) or "ingress_egress" (camera records individual arrival/departure timestamps, which should be preprocessed with preprocess_camera_timestamps() before calling add_counts()).

h_open

Positive numeric scalar specifying the number of hours the fishery is open per day. Required when survey_type = "aerial". Used as the expansion factor in the aerial effort estimator: $\hat{E} = N_{obs} \times h_{open} / v$.

visibility_correction

Detection probability for the aerial count: the proportion of anglers present that are detected from the aircraft, as a numeric scalar in (0, 1]. Required when survey_type = "aerial"; pass the string "none" to state explicitly that no visibility correction is applied. Used only when survey_type = "aerial". A value of 0.85 means 85% of anglers are detected; the effort estimate is scaled up by $1 / 0.85$.

This is the reciprocal of the ratio published by field studies. The standard ground-truthing method reports $r$ = (ground count) / (aerial count), which is greater than 1 whenever the aircraft undercounts: Smucker et al. (2010) report $r = 2.69$ for shore anglers. visibility_correction is a probability, so convert with $v = 1 / r$ — $r = 2.69$ becomes visibility_correction = 1 / 2.69 = 0.372. The estimator divides by $v$, which scales effort up by $1 / 0.372 = 2.69$ as intended. Passing the published $r$ directly is rejected by the (0, 1] check.

visibility_se

Optional positive numeric scalar: the standard error of visibility_correction, on the same detection-probability scale. Used only when survey_type = "aerial". visibility_correction is estimated from paired air–ground counts, not known, and the standard field method reports its SE as routine output (Smucker et al. 2010, equations 6 and 7); supplying it here propagates that uncertainty into the effort SE (GH #135). All-or-none: visibility_se requires a numeric visibility_correction, and cannot be combined with "none".

To convert an SE published on the ground-truthing-ratio scale, use the delta method for a reciprocal: $SE(v) = SE(r) / r^2$.

When omitted, the correction is treated as supplied without a measured uncertainty and the component is reported as absent — never as zero, which would be indistinguishable from having propagated it.

Note the three distinct claims, which the package keeps separate:

visibility_correction = "none": No correction was studied. The point estimate divides by 1 and visibility_se is NA, so the reported SE is NA — the uncertainty is unpropagated, not zero.
visibility_correction = v alone: A correction was measured but its SE was not supplied. The component is reported as absent.
visibility_correction = v, visibility_se = 0: The correction is asserted to be known exactly. This is the only way to obtain a numeric SE with no visibility uncertainty, and it must be stated deliberately — e.g. visibility_correction = 1, visibility_se = 0 for a fishery where every angler is genuinely detectable.

angler_ratio

The proportion of the people recorded in the aerial count that are anglers, as a numeric scalar in (0, 1]. Required when survey_type = "aerial"; pass the string "none" to state explicitly that no such correction is applied.

An aerial count column is a raw observer count, and observers cannot reliably tell anglers from non-anglers from the air. Smucker et al. (2010) apply an angler-to-people ratio of 0.404 alongside their visibility correction; omitting it overstates shore effort by roughly 2.5x. The two corrections push in opposite directions (0.404 down, 2.69 up), so applying only the visibility correction is not conservative — it is biased in the direction of the correction that was kept (GH #158).

If the count column already records anglers rather than people, say so with angler_ratio = 1, angler_ratio_se = 0, which asserts the ratio is known exactly. That is a claim about how the data were recorded, and only the surveyor can make it.

For a count of boats rather than people, do not use this argument: expand the boat count to anglers with derive_angler_count() before add_counts(), which attaches the party-size multiplier and its standard error as expansion carrier columns that the estimator reads.

angler_ratio_se

Optional positive numeric scalar: the standard error of angler_ratio. All-or-none — it requires a numeric angler_ratio and cannot be combined with "none". Like the visibility correction, the angler-to-people ratio is estimated from ground observation and is a shared multiplier, so its contribution enters once at the total. Omitted means the component is reported as absent, never as zero.

open_start

Optional non-negative numeric scalar specifying the hour of day (decimal, 24-hour clock) when the fishery opens. Used only when survey_type = "aerial" and only by estimate_effort_aerial_glmm() to anchor the numerical integration window. If NULL (default), the GLMM estimator derives the window start from the earliest observed flight time minus 0.5 hours, with an informational message. Supplying open_start fixes the window across surveys for consistent comparisons. Example: open_start = 5.5 means fishing begins at 5:30 AM.

day_start

Clock time ("HH:MM") at which a survey day begins, for night creels whose shifts cross midnight. NULL (default) takes it from the calendar's day_start column, which generate_schedule() writes; without the column the survey day is the calendar day. Given both, they must agree. With a day_start other than "00:00" the design is a night design: add_counts() and add_interviews() then need each record's calendar date and clock time, and map a record timed before day_start to the night that began the previous date (a 00:45 count on Apr 4 belongs to the night of Apr 3). Only survey_type = "instantaneous" supports night designs.

A night creel tidycreel is not told about cannot always be detected: a calendar with no day_start and no shift times, given counts dated by calendar day, is read as a day design, and each night is split across two dates. Declare the night with day_start.

night_date

Which date labels a night. Only "start" (the date the night begins, as field staff say it and as generate_schedule() dates it) is supported.

tz

Time zone of the water, one name from OlsonNames(). Required for night designs; defaults to getOption("tidycreel.tz"), never to the computer's own zone. Shift lengths across a daylight-saving change, and record times given as POSIXct, are read in it.

wait_time, circuit_time

Tidy selectors for two columns of sampling_frame, used together in place of p_site on a bus route where the clerk visits every site on every pass (Robson and Jones 1989). wait_time is the scheduled wait at the site. circuit_time is the time to complete the whole circuit, travel included, and is constant within a circuit. Both must be in the same unit. The site's weight is then p_site = wait_time / circuit_time: the share of the circuit during which a party at that site can be seen. These shares add up to less than 1 when the route has travel time, and the total wait must not exceed the circuit time. This is the weighting in Pollock et al. (1994, eq. 15.10). Encoding the waits as shares of the total wait, so that they add up to 1, would understate the totals by the travelling fraction of the circuit.

Value

A creel_design S3 object (list) with components:

calendar: The original calendar data frame
date_col: Character name of the date column
strata_cols: Character vector of strata column names
site_col: Character name of site column, or NULL
design_type: Character design type
counts: NULL (populated by add_counts() in future)
survey: NULL (populated internally during estimation)
bus_route: List with resolved sampling frame data and column mappings, or NULL for non-bus-route designs. Contains: $data (sampling frame with .pi_i column added), $site_col, $circuit_col, $p_site_col, $p_period_col, $pi_i_col (always ".pi_i").

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)
Strata columns contain no NA values: a day with an unknown stratum belongs to no stratum's population of days
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); or, with wait_time and circuit_time, waits are positive, the circuit time is constant within each circuit, and the waits within a circuit add up to no more than its circuit time
(bus_route only) p_period values are constant within each circuit (tolerance 1e-10)

References

Jones, C. M., & Pollock, K. H. (2012). Recreational angler survey methods: estimation of effort, harvest, and released catch. 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 (pp. 911–912) are the Horvitz–Thompson totals the estimators use, with $\pi_i$ "the total probability that the ith sampling unit is included in the sample".

Pollock, K. H., Jones, C. M., & Brown, T. L. (1994). Angler survey methods and their applications in fisheries management. American Fisheries Society Special Publication 25. Section 15.5.3, eq. 15.10–15.11: the bus-route estimator, with each site weighted by its wait over the circuit time.

Robson, D., & Jones, C. M. (1989). The theoretical basis of an access site angler survey design. Biometrics, 45, 83–98. doi:10.2307/2532036

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
)

# Bus route that visits every site on each pass: a 360-minute circuit with
# 195 minutes of waits, so each site's weight is its wait / 360
sf_wait <- data.frame(
  site = c("A", "B", "C", "D", "E"),
  wait = c(30, 30, 15, 60, 60),
  circuit_minutes = 360
)
design_wait <- creel_design(
  calendar_br,
  date = date,
  strata = day_type,
  survey_type = "bus_route",
  sampling_frame = sf_wait,
  site = site,
  wait_time = wait,
  circuit_time = circuit_minutes,
  p_period = 0.5
)