Standardize sampled-day effort rows for count-based workflows

Converts a data frame that already contains sampled-day effort estimates into a canonical tibble for downstream use with add_counts(). This helper is the preferred seam for count-based workflows where raw within-day count schedules, section probabilities, boat-party-size adjustments, camera multipliers, or similar count-side corrections have already been resolved outside the core estimator.

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_daily_effort(
  data,
  date,
  strata = NULL,
  effort_type,
  daily_effort,
  correction_factor = 1,
  psu = NULL,
  n_counts = NULL,
  within_day_var = NULL,
  source_method = NULL
)

Arguments

data

A data frame containing sampled-day effort rows.

date

Tidy selector for the Date column.

strata

Optional tidy selector for one or more strata columns.

effort_type

Tidy selector for the effort-type column. Common values are "bank" and "boat".

daily_effort

Tidy selector for the numeric sampled-day effort column.

correction_factor

Optional multiplicative correction applied to daily_effort. May be a scalar (defaults to 1) or an expression that evaluates to a numeric vector with one value per row, including a bare column name. 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 daily_effort values you pass in; it is rescaled into daily_effort squared units on output, multiplied by 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 tidy selector for a column describing how the sampled-day effort estimate was derived (e.g. "direct_count", "boat_count_x_mean_party_size", "camera_count_x_detection_correction").

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

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_boat_party(), prep_interview_catch(), prep_interviews_trips(), validate_creel_schema()

Examples

raw_counts <- data.frame(
  sample_date  = as.Date(c("2024-06-01", "2024-06-02", "2024-06-08", "2024-06-09")),
  day_type     = c("weekday", "weekday", "weekend", "weekend"),
  effort_kind  = c("bank", "bank", "bank", "bank"),
  effort_value = c(15, 23, 45, 52)
)
prep_counts_daily_effort(raw_counts, date = sample_date, strata = day_type,
                         effort_type = effort_kind, daily_effort = effort_value)
#> # A tibble: 4 × 6
#>   date       day_type effort_type daily_effort psu        correction_factor
#>   <date>     <chr>    <chr>              <dbl> <date>                 <dbl>
#> 1 2024-06-01 weekday  bank                  15 2024-06-01                 1
#> 2 2024-06-02 weekday  bank                  23 2024-06-02                 1
#> 3 2024-06-08 weekend  bank                  45 2024-06-08                 1
#> 4 2024-06-09 weekend  bank                  52 2024-06-09                 1