---
title: "Unextrapolated Interview Summaries"
output:
  rmarkdown::html_vignette:
    highlight: null
vignette: >
  %\VignetteIndexEntry{Unextrapolated Interview Summaries}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

Creel surveys produce two types of summary products: **unextrapolated summaries** and
**extrapolated estimates**. This vignette covers unextrapolated summaries — raw tabulations
of interview records that describe the composition of interviewed parties without applying
survey-design weighting.

**When to use unextrapolated summaries:**

- Describing who was interviewed (angler type, method, species sought)
- Checking for refusals and participation rates
- Examining trip-length distributions
- Computing catch-while-sought and harvest-while-sought rates as quality indicators

All unextrapolated functions are *interview-weighted*, not *pressure-weighted*: every
interview counts once. A day with many interviews therefore counts for more than a day
with few, however many anglers were fishing on each. For pressure-weighted,
design-based estimates, use `estimate_catch_rate()`, `estimate_total_catch()`, and the
related functions in `vignette("interview-estimation")`.

## Build the Design

Start by assembling a design with every data layer the summaries use:

```{r build-design, message = FALSE}
library(tidycreel)

# Load example datasets
data(example_calendar)
data(example_counts)
data(example_interviews)
data(example_catch)
data(example_lengths)

# Step 1: Define the survey calendar and stratification
design <- creel_design(example_calendar, date = date, strata = day_type)

# Step 2: Attach effort. example_counts already holds angler-hours for each
# sampled day, so it goes in through prep_counts_daily_effort()
design <- add_counts(design, prep_counts_daily_effort(example_counts,
  date = date, strata = day_type, daily_effort = effort_hours
))

# Step 3: Attach interview records, with the optional descriptive fields
design <- add_interviews(design, example_interviews,
  catch          = catch_total,
  effort         = hours_fished,
  harvest        = catch_kept,
  trip_status    = trip_status,
  trip_duration  = trip_duration,
  angler_type    = angler_type,
  angler_method  = angler_method,
  species_sought = species_sought,
  n_anglers      = n_anglers,
  refused        = refused
)

# Step 4: Attach species-level catch data
design <- add_catch(design, example_catch,
  catch_uid     = interview_id,
  interview_uid = interview_id,
  species       = species,
  count         = count,
  catch_type    = catch_type
)

# Step 5: Attach fish length data (individual harvest + binned release)
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)
```

The `print()` output shows all five data layers: calendar, counts, interviews, catch, and lengths.

## Interview Participation

Use `summarize_refusals()` to understand how many potential interviewees declined to
participate. High refusal rates can bias estimates if refusers differ systematically
from participants.

```{r refusals}
summarize_refusals(design)
```

All 22 interviews in `example_interviews` were accepted (no refusals). In a field
survey, check whether refusals cluster in a stratum, a site or an angler type; the
estimators assume the interviewed parties stand for the ones that refused.

## Interview Composition

Seven tabulation functions describe the composition of the interview sample.

### Day Type

```{r day-type}
summarize_by_day_type(design)
```

### Angler Type

```{r angler-type}
summarize_by_angler_type(design)
```

### Fishing Method

```{r method}
summarize_by_method(design)
```

### Species Sought

```{r species-sought}
summarize_by_species_sought(design)
```

### Successful Parties

`summarize_successful_parties()` counts parties that caught at least one fish of their
target species (as recorded in catch data), broken down by angler type and species sought.

```{r successful}
summarize_successful_parties(design)
```

### Trip Length Distribution

```{r trip-length}
summarize_by_trip_length(design)
```

The trip-length distribution is useful for detecting outliers and understanding effort
patterns.

## Catch-While-Sought (CWS) and Harvest-While-Sought (HWS) Rates

CWS and HWS rates are the mean, across parties seeking a species, of each party's catch
(CWS) or harvest (HWS) of that species per angler-hour. A party's catch is its `caught` row
when it recorded one, and otherwise its harvested + released fish, as `add_catch()`
documents, so data that record only dispositions give the same CWS. These are useful
quality indicators and
input parameters for population models, but should **not** be treated as pressure-weighted
catch rates for management use — they reflect the interview sample composition, not fishing
pressure across the survey period.

### CWS Rates by Species Sought

```{r cws}
summarize_cws_rates(design, by = species_sought)
```

### CWS Rates Collapsed Across All Groupings

```{r cws-collapsed}
summarize_cws_rates(design, by = NULL)
```

### HWS Rates

```{r hws}
summarize_hws_rates(design, by = species_sought)
```

**Interpretation guidance:** these are rates, not proportions. A CWS of 0.6 means the
parties seeking that species caught, on average, 0.6 of it per angler-hour; rates above
1.0 are common. For the share of parties that caught at least one, use
`summarize_successful_parties()`.

## Length Frequency Distributions

Length data attached via `add_lengths()` can be summarized by catch type and species.

### Harvest Lengths

```{r lfreq-harvest}
summarize_length_freq(design, type = "harvest", by = species, bin_width = 25)
```

### Release Lengths

Release lengths in `example_lengths` are stored in pre-binned format, as `"lower-upper"`
labels in mm. `summarize_length_freq()` converts each bin to its midpoint:

```{r lfreq-release}
summarize_length_freq(design, type = "release", by = species)
```

Many agencies record released fish by **inch group** instead, a single value such as `"12"`
with a count. Declare the unit and the group width when attaching the lengths, and each group
is read as its lower bound (`"12"` is 12.0 to under 13 inches) and converted to mm, so it
combines correctly with harvest lengths measured in mm:

```{r lfreq-inch, eval = FALSE}
design <- add_lengths(design, lengths_with_inch_groups,
  length_uid = interview_id, interview_uid = interview_id,
  species = species, length = length, length_type = length_type, count = count,
  release_format = "binned", release_bin_unit = "inch", release_bin_width = 1
)
```

If your inch groups are rounded to the nearest inch rather than truncated, give
`"lower-upper"` labels (`"11.5-12.5"`) instead.

### All-Catch Lengths

```{r lfreq-catch}
summarize_length_freq(design, type = "catch", by = species, bin_width = 25)
```

## Extrapolated Species-Level Estimates

For pressure-weighted estimates broken down by species, use the estimators. These
combine the effort estimate with species-specific catch rates from the interview and
catch data, using the ratio of means for these complete trips. The calendar lists only
the sampled days, so the totals are totals over those days.

The example is small, 17 complete trips, so the rate calls warn that the sample is
small for a ratio estimator, and the species totals warn that the weekend rate rests on
fewer than 10 trips. Both are about precision, and the standard errors reflect them.

### Catch Per Unit Effort by Species

```{r cpue-species, message = FALSE}
estimate_catch_rate(design, by = species)
```

### Total Catch by Species

```{r total-catch-species, message = FALSE}
estimate_total_catch(design, by = species)
```

### Total Harvest by Species

```{r total-harvest-species, message = FALSE}
estimate_total_harvest(design, by = species)
```

### Release Rate and Total Releases by Species

```{r release-species, message = FALSE}
estimate_release_rate(design, by = species)
estimate_total_release(design, by = species)
```

For grouped estimates combining calendar strata with species, use
`by = c(day_type, species)`. See `vignette("interview-estimation")` for the complete
extrapolated estimation workflow.

## Summary

| Function | Data required | Output |
|----------|---------------|--------|
| `summarize_refusals()` | refused field | month × participation × N × % |
| `summarize_by_day_type()` | strata | month × day_type × N × % |
| `summarize_by_angler_type()` | angler_type | month × angler_type × N × % |
| `summarize_by_method()` | angler_method | month × method × N × % |
| `summarize_by_species_sought()` | species_sought | month × species × N × % |
| `summarize_successful_parties()` | catch + angler_type + species_sought | angler_type × species × success rate |
| `summarize_by_trip_length()` | trip_duration | bin × N × % |
| `summarize_cws_rates()` | catch + species_sought | CWS rate ± SE by grouping |
| `summarize_hws_rates()` | catch + species_sought | HWS rate ± SE by grouping |
| `summarize_length_freq()` | lengths | bin × N × % × cumulative % |