tidycreel

Tidy Interface for Creel Survey Design, Estimation, and Reporting

tidycreel provides a pipe-friendly interface for creel survey design, data management, estimation, visualisation, and reporting. Built on the survey package for design-based inference, it lets fisheries biologists work in creel vocabulary — dates, strata, counts, effort, catch, lengths, schedules — without managing survey-package internals directly.

Installation

Install the development version from GitHub:

# install.packages("pak")
pak::pak("chrischizinski/tidycreel")

# or with devtools
devtools::install_github("chrischizinski/tidycreel")

Survey Types

Instantaneous Count

Stratified effort estimation from periodic angler counts.

Getting Started →

Bus-Route

PPS site selection with Horvitz-Thompson estimators and enumeration expansion.

Bus-Route vignette →

Ice Fishing

Degenerate bus-route design with certainty site sampling.

Ice Fishing vignette →

Camera-Monitored

Counter and ingress-egress preprocessing, NB GLMM count imputation, and camera effort indexing.

Camera Survey vignette →

Aerial Survey

Single-overflight effort estimation with calibrated open-hours scaling.

Aerial vignette → | GLMM variant →

Key Capabilities

• Design-based inference — wraps the survey package; biologists write creel vocabulary, not survey-package internals.
• Single design entry point — creel_design() dispatches to the correct workflow for each survey type.
• Core estimation surface — effort, catch rate, harvest rate, release rate, and total-catch estimators share a common API.
• Extended estimation methods — camera effort indexing, NB GLMM count imputation, weighted length distributions, mark-recapture population and harvest estimators (Petersen, Schnabel), and exploitation rate from tag returns (Pollock et al.).
• Stratification auditing — audit_strata(), simulate_strata_collapse(), and reallocate_strata() diagnose stratum weights, inclusion probabilities, and coverage; test collapse scenarios before committing to a redesign.
• Validation and cleaning — field-level validation, species standardisation, data-validation summaries, and toy datasets for examples.
• Planning and QA — schedule generation, count-window planning, completeness checks, sample-size tools, and power calculators.
• Visualisation and reporting — autoplot() methods, theme_creel(), creel_palette(), and a flexdashboard report template scaffold.
• Documentation and onboarding — glossary, workflow vignettes, statistical-method articles, and a pkgdown site.

Quick Start

Instantaneous Count Survey

library(tidycreel)

# 1. Define survey structure with tidy selectors
design <- creel_design(example_calendar, date = date, strata = day_type)

# 2. Attach count observations
design <- add_counts(design, example_counts)

# 3. Estimate effort with design-based variance
estimate_effort(design)

Bus-Route Survey

# Probability-proportional-to-size site selection
design <- creel_design(
  example_calendar,
  date = date,
  strata = day_type,
  survey_type = "bus_route",
  sampling_frame = my_site_frame,
  site = site_id
)

design <- add_interviews(design, interview_data,
  catch = catch_total,
  effort = hours_fished,
  harvest = catch_kept
)

estimate_catch_rate(design)

Where to Start

If you want to…	Start here
Learn the package vocabulary	Glossary
See the main end-to-end workflow	Getting Started
Plan a season before sampling starts	Survey Design Toolbox
Estimate angler population or exploitation rate from tag data	Mark-Recapture and Exploitation Rate
Understand plotting and output styling	Visualisation and theme_creel()
Build a report/dashboard	Install the package, then open R Markdown > From Template > Creel Dashboard in RStudio

Functions at a Glance

Survey Design

• creel_design() — single entry point; dispatches on survey_type.
• add_counts(), add_interviews(), add_catch(), add_lengths(), add_sections() — attach observation data.

Estimation

• estimate_effort() — total effort with Taylor linearization, bootstrap, or jackknife variance.
• estimate_catch_rate(), estimate_harvest_rate(), estimate_release_rate() — ratio-based interview estimators.
• estimate_total_catch(), estimate_total_harvest(), estimate_total_release() — totals via delta-method propagation.
• est_effort_camera(), est_length_distribution() — camera effort indexing and weighted size-structure estimation.
• estimate_exploitation_rate() — exploitation rate from tag returns (Pollock et al.; simple and T-weighted stratified paths).
• estimate_angler_n() — Petersen and Schnabel mark-recapture population size estimators.
• estimate_mr_harvest() — population-scale total harvest from mark-recapture data.

Validation and Diagnostics

• validate_creel_data(), validation_report(), standardize_species() — clean and validate real-world creel inputs.
• validate_incomplete_trips(), validate_design(), check_completeness(), compare_variance(), adjust_nonresponse() — QA and estimator diagnostics.
• audit_strata(), simulate_strata_collapse(), reallocate_strata() — stratification diagnostics; verify weights, simulate collapse scenarios, and rebalance allocations.

Planning and Reporting

• generate_schedule(), generate_bus_schedule(), generate_count_times(), attach_count_times() — planning/scheduling helpers.
• creel_n_effort(), creel_n_cpue(), creel_n_camera(), creel_power(), cv_from_n() — sample-size and power tools.
• season_summary(), summary.creel_estimates(), write_estimates() — report-ready summary/export helpers.
• autoplot.creel_estimates(), autoplot.creel_schedule(), autoplot.creel_length_distribution(), theme_creel(), creel_palette() — visualisation helpers.

Vignettes

Get Started

Vignette	Description
Getting Started	Core workflow: design → counts → effort estimation
Glossary	Plain-language guide to tidycreel terms and concepts

Survey Types

Vignette	Description
Bus-Route Surveys	PPS site selection with Horvitz-Thompson estimators
Ice Fishing	Certainty-site (degenerate bus-route) design
Camera Surveys	Counter and ingress-egress preprocessing, count imputation, camera effort
Aerial Surveys	Single-overflight effort with calibrated open-hours scaling
Aerial GLMM	Negative-binomial GLMM aerial effort (Askey 2018)

Estimation

Vignette	Description
Survey Integration	Using tidycreel alongside the survey package directly
Interview Estimation	CPUE, catch, and harvest from interview data
Mark-Recapture and Exploitation Rate	Chapman, Petersen, Schnabel estimators; MR harvest; exploitation rate from tag returns
Incomplete Trips	When and how to use mean-of-ratios and TOST validation
Flexible Count Estimation	Non-standard count configurations and custom time windows
Progressive Count Surveys	Rolling and progressive count workflows
Section Estimation	Spatial section-level effort and catch estimation
Temporal Extrapolation	Extrapolating partial-season data to full-season estimates

Reporting & Planning

Vignette	Description
Unextrapolated Summaries	Raw interview summaries without season-level expansion
Survey Design Toolbox	Sample-size, power, scheduling, and pre-season planning tools
Survey Scheduling	Count windows, schedules, validation, and completeness checks
Visualisation	Plotting patterns and output styling with theme_creel()

Statistical Methods

Vignette	Description
Effort Pipeline	Statistical mechanics of the effort estimation pipeline
Catch Pipeline	Statistical mechanics of the catch estimation pipeline
Replicate Designs	Variance workflows and replicate-design reasoning
Bus-Route Equations	Technical equation derivations for bus-route estimators

Ecosystem

Vignette	Description
tidycreel.connect	Database integration and reproducible data pipelines

Getting Help and Reporting Bugs

Questions about usage

If you have questions about which survey type to use, how to interpret results, or how to structure your data, the best place to start is GitHub Discussions:

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

GitHub Discussions works like a threaded forum attached to the repository. If you do not already have a GitHub account, you can create one for free at https://github.com/signup — it only requires an email address. Once signed in, click New discussion, select the Q&A category, and describe what you are trying to do. Searching existing threads first is worth a moment; your question may already have an answer.

Reporting a bug or unexpected result

If a function returns an error, produces a result that does not look right, or behaves differently from what the documentation describes, please open a GitHub Issue:

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

Step-by-step for first-time GitHub users:

1. Go to the Issues link above. If you are not signed in, click Sign in in the top-right corner (or Sign up if you do not yet have an account).
2. Click the green New issue button.
3. Select the Bug report template — it will open a pre-filled form.
4. Fill in each section of the form:
   • Survey type — which design you are using (instantaneous, bus_route, ice, camera, or aerial)
   • tidycreel version — run packageVersion("tidycreel") in R and paste the result (e.g., 1.6.0)
   • What you expected — describe the output or behavior you expected
   • What actually happened — paste the full error message, or describe the result that does not look right
   • Reproducible example — a short R snippet that shows the problem (see below)
5. Click Submit new issue at the bottom of the form.

Writing a reproducible example

The single most useful thing you can include is a short, self-contained R snippet that demonstrates the problem without needing your real data. Use the package’s built-in example datasets (example_calendar, example_counts, example_interviews, etc.) wherever possible, or create a small data frame that triggers the issue.

A good example looks like this:

library(tidycreel)

design <- creel_design(example_calendar, date = date, strata = day_type)
design <- add_counts(design, example_counts)

# The call that produces the unexpected result
estimate_effort(design)
#> Error: ...  (paste the full error message here)

The snippet should run from scratch without any additional files or setup. If reducing your data to a minimal example is not straightforward, share what you have and describe the context — that is still very helpful. The reprex package can automatically format and share R output if you want a polished submission: install it with install.packages("reprex") and run reprex::reprex() around your code.

For guidance on contributing code, requesting new features, or the development workflow, see CONTRIBUTING.md.

License

MIT License — see LICENSE.md for details.

AI Use Acknowledgement

Artificial intelligence tools were used during the development of tidycreel, primarily through Claude Code (Anthropic), with selected code and outputs reviewed using Codex (OpenAI). These tools supported code refinement, consistency across functions, GitHub Actions workflows, error checking, and the development of testing infrastructure.

All functions and analytical outputs have been reviewed by the author team and validated against real-world creel survey data and expected analytical behavior. Despite these review and testing efforts, errors may still occur. If you identify a problem or unexpected result, please submit an issue so that it can be reviewed and addressed.