Create a summary data frame of termination experience for a given target status.

## Arguments

- .data
A data frame with exposure-level records, ideally of type

`exposed_df`

- target_status
A character vector of target status values

- expected
A character vector containing column names in

`.data`

with expected values- col_exposure
Name of the column in

`.data`

containing exposures- col_status
Name of the column in

`.data`

containing the policy status- wt
Optional. Length 1 character vector. Name of the column in

`.data`

containing weights to use in the calculation of claims, exposures, partial credibility, and confidence intervals.- credibility
If

`TRUE`

, the output will include partial credibility weights and credibility-weighted termination rates.- conf_level
Confidence level used for the Limited Fluctuation credibility method and confidence intervals

- cred_r
Error tolerance under the Limited Fluctuation credibility method

- conf_int
If

`TRUE`

, the output will include confidence intervals around the observed termination rates and any actual-to-expected ratios.- object
An

`exp_df`

object- ...
Groups to retain after

`summary()`

is called

## Value

A tibble with class `exp_df`

, `tbl_df`

, `tbl`

,
and `data.frame`

. The results include columns for any grouping variables,
claims, exposures, and observed termination rates (`q_obs`

).

If any values are passed to

`expected`

, expected termination rates and actual-to-expected ratios.If

`credibility`

is set to`TRUE`

, additional columns are added for partial credibility and credibility-weighted termination rates (assuming values are passed to`expected`

). Credibility-weighted termination rates are prefixed by`adj_`

.If

`conf_int`

is set to`TRUE`

, additional columns are added for lower and upper confidence interval limits around the observed termination rates and any actual-to-expected ratios. Additionally, if`credibility`

is`TRUE`

and expected values are passed to`expected`

, the output will contain confidence intervals around credibility-weighted termination rates. Confidence interval columns include the name of the original output column suffixed by either`_lower`

or`_upper`

.If a value is passed to

`wt`

, additional columns are created containing the the sum of weights (`.weight`

), the sum of squared weights (`.weight_qs`

), and the number of records (`.weight_n`

).

## Details

If `.data`

is grouped, the resulting data frame will contain
one row per group.

If `target_status`

isn't provided, `exp_stats()`

will use the same
target status from `.data`

if it has the class `exposed_df`

.
Otherwise, all status values except the first level will be assumed.
This will produce a warning message.

## Expected values

The `expected`

argument is optional. If provided, this argument must
be a character vector with values corresponding to columns in `.data`

containing expected experience. More than one expected basis can be provided.

## Credibility

If `credibility`

is set to `TRUE`

, the output will contain a
`credibility`

column equal to the partial credibility estimate under
the Limited Fluctuation credibility method (also known as Classical
Credibility) assuming a binomial distribution of claims.

## Confidence intervals

If `conf_int`

is set to `TRUE`

, the output will contain lower and upper
confidence interval limits for the observed termination rate and any
actual-to-expected ratios. The confidence level is dictated
by `conf_level`

. If no weighting variable is passed to `wt`

, confidence
intervals will be constructed assuming a binomial distribution of claims.
Otherwise, confidence intervals will be calculated assuming that the
aggregate claims distribution is normal with a mean equal to observed claims
and a variance equal to:

`Var(S) = E(N) * Var(X) + E(X)^2 * Var(N)`

,

Where `S`

is the aggregate claim random variable, `X`

is the weighting
variable assumed to follow a normal distribution, and `N`

is a binomial
random variable for the number of claims.

If `credibility`

is `TRUE`

and expected values are passed to `expected`

,
the output will also contain confidence intervals for any
credibility-weighted termination rates.

`summary()`

Method

Applying `summary()`

to a `exp_df`

object will re-summarize the
data while retaining any grouping variables passed to the "dots"
(`...`

).

## Examples

```
toy_census |> expose("2022-12-31", target_status = "Surrender") |>
exp_stats()
#> Experience study results
#>
#> Target status: Surrender
#> Study range: 1900-01-01 to 2022-12-31
#>
#> # A tibble: 1 × 4
#> n_claims claims exposure q_obs
#> <int> <int> <dbl> <dbl>
#> 1 1 1 35.3 0.0283
exp_res <- census_dat |>
expose("2019-12-31", target_status = "Surrender") |>
group_by(pol_yr, inc_guar) |>
exp_stats()
exp_res
#> Experience study results
#>
#> Groups: pol_yr, inc_guar
#> Target status: Surrender
#> Study range: 1900-01-01 to 2019-12-31
#>
#> # A tibble: 30 × 6
#> pol_yr inc_guar n_claims claims exposure q_obs
#> <int> <lgl> <int> <int> <dbl> <dbl>
#> 1 1 FALSE 56 56 7720. 0.00725
#> 2 1 TRUE 46 46 11532. 0.00399
#> 3 2 FALSE 92 92 7103. 0.0130
#> 4 2 TRUE 68 68 10612. 0.00641
#> 5 3 FALSE 67 67 6447. 0.0104
#> 6 3 TRUE 57 57 9650. 0.00591
#> 7 4 FALSE 123 123 5799. 0.0212
#> 8 4 TRUE 45 45 8737. 0.00515
#> 9 5 FALSE 97 97 5106. 0.0190
#> 10 5 TRUE 67 67 7810. 0.00858
#> # ℹ 20 more rows
summary(exp_res)
#> Experience study results
#>
#> Target status: Surrender
#> Study range: 1900-01-01 to 2019-12-31
#>
#> # A tibble: 1 × 4
#> n_claims claims exposure q_obs
#> <int> <int> <dbl> <dbl>
#> 1 2869 2869 132634. 0.0216
summary(exp_res, inc_guar)
#> Experience study results
#>
#> Groups: inc_guar
#> Target status: Surrender
#> Study range: 1900-01-01 to 2019-12-31
#>
#> # A tibble: 2 × 5
#> inc_guar n_claims claims exposure q_obs
#> <lgl> <int> <int> <dbl> <dbl>
#> 1 FALSE 1601 1601 52123. 0.0307
#> 2 TRUE 1268 1268 80511. 0.0157
```