Standardize boat-party sampled-day effort rows

Converts boat-count rows plus mean anglers-per-boat inputs into canonical sampled-day effort rows for downstream use with add_counts(). This helper is intentionally narrow: it handles the common boat-party expansion (boat_count * mean_party_size) and leaves broader source-specific reconstruction outside estimator internals.

The returned table always contains canonical columns: date, any selected strata columns, effort_type, daily_effort, psu, and correction_factor. Optional columns n_counts, within_day_var, and source_method are included when supplied.

Usage

prep_counts_boat_party(
  data,
  date,
  strata = NULL,
  boat_count,
  mean_party_size,
  mean_party_size_se = NULL,
  effort_type = "boat",
  correction_factor = 1,
  psu = NULL,
  n_counts = NULL,
  within_day_var = NULL,
  source_method = "boat_count_x_mean_party_size"
)

Arguments

data

A data frame containing sampled-day boat-count rows.

date

Tidy selector for the Date column.

strata

Optional tidy selector for one or more strata columns.

boat_count

Tidy selector for the numeric boat count column.

mean_party_size

Tidy selector for the numeric mean anglers-per-boat column.

mean_party_size_se

Optional standard error of mean_party_size. May be a scalar or an expression evaluating to one value per row. Supplying it emits the expansion_* carrier columns, which add_counts() reads so the reported standard error includes the party-size sampling error.

NULL (the default) leaves the component absent rather than zero. A zero would enter the variance as "the multiplier is known exactly" and be indistinguishable from never having propagated, so the two states are kept apart. NA is accepted and propagates as unknown.

Before tidycreel 3.4.0 this argument did not exist, and the component was unreachable on this path: the same expansion through derive_angler_count() reported a larger, correct standard error while this one silently omitted the term (GH #143).

effort_type

Effort-type values for output. Defaults to "boat". May be a scalar string/factor or an expression that evaluates to one value per row.

correction_factor

Optional multiplicative correction applied after the boat-party expansion. May be a scalar (defaults to 1) or an expression that evaluates to a numeric vector with one value per row. Values must be finite and strictly positive.

psu

Optional tidy selector for the PSU column. Defaults to the selected date column when omitted.

n_counts

Optional tidy selector for the number of within-day counts each sampled-day estimate is built from (k_d). Required whenever within_day_var is supplied.

within_day_var

Optional tidy selector for the within-day sum of squares of the counts behind each sampled-day estimate, that is sum((x - mean(x))^2) per PSU. This is not a variance: the divisor is applied downstream by the estimator, which forms sum(ss_d) / (n_sampled * (k_bar - 1)). Supplying a variance here understates the within-day component by a factor of k_d - 1. Must be 0 wherever n_counts is 1, and requires n_counts.

Supply it on the raw boat_count values you pass in; it is rescaled into daily_effort squared units on output, multiplied by (mean_party_size * correction_factor)^2. add_counts() reads the emitted within_day_var and n_counts columns into the design, so the reported SE carries a within-day component. Before tidycreel 2.6.0 both columns were written here and never read, and the SE omitted that component entirely. Do not combine with add_counts(count_time_col = ), which derives the same quantity from raw counts; supplying both is an error.

source_method

Optional source-method values. Defaults to "boat_count_x_mean_party_size". May be a scalar string/factor or an expression that evaluates to one value per row.

Value

A tibble with canonical sampled-day effort columns. Required columns are date, selected strata columns (if any), effort_type, daily_effort, psu, and correction_factor. Optional columns are appended when supplied.

See also

prep_counts_daily_effort(), add_counts()

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(), est_effort_camera(), impute_camera_counts(), mean_party_size(), prep_counts_daily_effort(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

raw <- data.frame(
  sample_date = as.Date(c("2024-06-01", "2024-06-02")),
  day_type    = c("weekend", "weekend"),
  boats       = c(10, 12),
  mean_party  = c(2.5, 2.0)
)
prep_counts_boat_party(raw, date = sample_date, strata = day_type,
                       boat_count = boats, mean_party_size = mean_party)
#> # A tibble: 2 × 7
#>   date       day_type effort_type daily_effort psu        correction_factor
#>   <date>     <chr>    <chr>              <dbl> <date>                 <dbl>
#> 1 2024-06-01 weekend  boat                  25 2024-06-01                 1
#> 2 2024-06-02 weekend  boat                  24 2024-06-02                 1
#> # ℹ 1 more variable: source_method <chr>