as_exp_df: Termination summary helper functions

Description

Convert aggregate termination experience studies to the exp_df class.

Usage

as_exp_df(
  x,
  expected = NULL,
  wt = NULL,
  col_claims,
  col_exposure,
  col_n_claims,
  col_weight_sq,
  col_weight_n,
  target_status = NULL,
  start_date = as.Date("1900-01-01"),
  end_date = NULL,
  credibility = FALSE,
  conf_level = 0.95,
  cred_r = 0.05,
  conf_int = FALSE
)
is_exp_df(x)

Value

For is_exp_df(), a length-1 logical vector. For as_exp_df(), an exp_df object.

Arguments

x: An object. For as_exp_df(), x must be a data frame.
expected: A character vector containing column names in x with expected values
wt: Optional. Length 1 character vector. Name of the column in x containing weights to use in the calculation of claims, exposures, partial credibility, and confidence intervals.
col_claims: Optional. Name of the column in x containing claims. The assumed default is "claims".
col_exposure: Optional. Name of the column in x containing exposures. The assumed default is "exposure".
col_n_claims: Optional and only used used when wt is passed. Name of the column in x containing the number of claims.
col_weight_sq: Optional and only used used when wt is passed. Name of the column in x containing the sum of squared weights.
col_weight_n: Optional and only used used when wt is passed. Name of the column in x containing exposure record counts.
target_status: Character vector of target status values. Default value = NULL.
start_date: Experience study start date. Default value = 1900-01-01.
end_date: Experience study end date
credibility: If TRUE, future calls to summary() 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, future calls to summary() will include confidence intervals around the observed termination rates and any actual-to-expected ratios.

Details

is_exp_df() will return TRUE if x is an exp_df object.

as_exp_df() will coerce a data frame to an exp_df object if that data frame has columns for exposures and claims.

as_exp_df() is most useful for working with aggregate summaries of experience that were not created by actxps where individual policy information is not available. After converting the data to the exp_df class, summary() can be used to summarize data by any grouping variables, and autoplot() and autotable() are available for reporting.

If nothing is passed to wt, the data frame x must include columns containing:

Exposures (exposure)
Claim counts (claims)

If wt is passed, the data must include columns containing:

Weighted exposures (exposure)
Weighted claims (claims)
Claim counts (n_claims)
The raw sum of weights NOT multiplied by exposures
Exposure record counts (.weight_n)
The raw sum of squared weights (.weight_sq)

The names in parentheses above are expected column names. If the data frame passed to as_exp_df() uses different column names, these can be specified using the col_* arguments.

When a column name is passed to wt, the columns .weight, .weight_n, and .weight_sq are used to calculate credibility and confidence intervals. If credibility and confidence intervals aren't required, then it is not necessary to pass anything to wt. The results of as_exp_df() and any downstream summaries will still be weighted as long as the exposures and claims are pre-weighted.

target_status, start_date, and end_date are optional arguments that are only used for printing the resulting exp_df object.

Examples

Run this code

# convert pre-aggregated experience into an exp_df object
dat <- as_exp_df(agg_sim_dat, col_exposure = "exposure_n",
                 col_claims = "claims_n",
                 target_status = "Surrender",
                 start_date = 2005, end_date = 2019,
                 conf_int = TRUE)
dat
is_exp_df(dat)

# summary by policy year
summary(dat, pol_yr)

# repeat the prior exercise on a weighted basis
dat_wt <- as_exp_df(agg_sim_dat, wt = "av",
                    col_exposure = "exposure_amt",
                    col_claims = "claims_amt",
                    col_n_claims = "claims_n",
                    col_weight_sq = "av_sq",
                    col_weight_n = "n",
                    target_status = "Surrender",
                    start_date = 2005, end_date = 2019,
                    conf_int = TRUE)
dat_wt

# summary by policy year
summary(dat_wt, pol_yr)