as_trx_df: Transaction summary helper functions

Description

Convert aggregate transaction experience studies to the trx_df class.

Usage

as_trx_df(
  x,
  col_trx_amt = "trx_amt",
  col_trx_n = "trx_n",
  col_trx_flag = "trx_flag",
  col_exposure = "exposure",
  col_percent_of = NULL,
  col_percent_of_w_trx = NULL,
  col_trx_amt_sq = "trx_amt_sq",
  start_date = as.Date("1900-01-01"),
  end_date = NULL,
  conf_int = FALSE,
  conf_level = 0.95
)
is_trx_df(x)

Value

For is_trx_df(), a length-1 logical vector. For as_trx_df(), a trx_df object.

Arguments

x: An object. For as_trx_df(), x must be a data frame.
col_trx_amt: Optional. Name of the column in x containing transaction amounts.
col_trx_n: Optional. Name of the column in x containing transaction counts.
col_trx_flag: Optional. Name of the column in x containing the number of exposure records with transactions.
col_exposure: Optional. Name of the column in x containing exposures.
col_percent_of: Optional. Name of the column in x containing a numeric variable to use in "percent of" calculations.
col_percent_of_w_trx: Optional. Name of the column in x containing a numeric variable to use in "percent of" calculations with transactions.
col_trx_amt_sq: Optional and only required when col_percent_of is passed and conf_int is TRUE. Name of the column in x containing squared transaction amounts.
start_date: Experience study start date. Default value = 1900-01-01.
end_date: Experience study end date
conf_int: If TRUE, future calls to summary() will include confidence intervals around the observed utilization rates and any percent_of output columns.
conf_level: Confidence level for confidence intervals

Details

is_trx_df() will return TRUE if x is a trx_df object.

as_trx_df() will coerce a data frame to a trx_df object if that data frame has the required columns for transaction studies listed below.

as_trx_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 trx_df class, summary() can be used to summarize data by any grouping variables, and autoplot() and autotable() are available for reporting.

At a minimum, the following columns are required:

Transaction amounts (trx_amt)
Transaction counts (trx_n)
The number of exposure records with transactions (trx_flag). This number is not necessarily equal to transaction counts. If multiple transactions are allowed per exposure period, trx_flag will be less than trx_n.
Exposures (exposure)

If transaction amounts should be expressed as a percentage of another variable (i.e. to calculate utilization rates or actual-to-expected ratios), additional columns are required:

A denominator "percent of" column. For example, the sum of account values.
A denominator "percent of" column for exposure records with transactions. For example, the sum of account values across all records with non-zero transaction amounts.

If confidence intervals are desired and "percent of" columns are passed, an additional column for the sum of squared transaction amounts (trx_amt_sq) is also required.

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

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

Unlike trx_stats(), as_trx_df() only permits a single transaction type and a single percent_of column.

Examples

Run this code

# convert pre-aggregated experience into a trx_df object
dat <- as_trx_df(agg_sim_dat,
                 col_exposure = "n",
                 col_trx_amt = "wd",
                 col_trx_n = "wd_n",
                 col_trx_flag = "wd_flag",
                 col_percent_of = "av",
                 col_percent_of_w_trx = "av_w_wd",
                 col_trx_amt_sq = "wd_sq",
                 start_date = 2005, end_date = 2019,
                 conf_int = TRUE)
dat
is_trx_df(dat)

# summary by policy year
summary(dat, pol_yr)