exp_stats | R Documentation |
Create a summary data frame of termination experience for a given target status.
exp_stats(
.data,
target_status = attr(.data, "target_status"),
expected,
col_exposure = "exposure",
col_status = "status",
wt = NULL,
credibility = FALSE,
conf_level = 0.95,
cred_r = 0.05,
conf_int = FALSE,
control_vars,
control_distinct_max = 25L
)
## S3 method for class 'exp_df'
summary(object, ...)
.data |
A data frame with exposure-level records, ideally of type
|
target_status |
A character vector of target status values |
expected |
A character vector containing column names in |
col_exposure |
Name of the column in |
col_status |
Name of the column in |
wt |
Optional. Length 1 character vector. Name of the column in
|
credibility |
If |
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 |
control_vars |
|
control_distinct_max |
Maximum number of unique values allowed for control variables |
object |
An |
... |
Groups to retain after |
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.
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
or control_vars
, additional
columns are added for expected termination rates and actual-to-expected
(A/E) ratios. A/E ratios are prefixed by ae_
.
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
).
The expected
argument is optional. If provided, this argument must
be a character vector with values corresponding to column names in .data
containing expected experience. More than one expected basis can be provided.
The control_vars
argument is optional. If provided, this argument must
be ".none"
(more on this below) or a character vector with values
corresponding to column names in .data
. Control variables are used to
estimate the impact of any grouping variables on observed experience
after accounting for the impact of control variables.
Mechanically, when values are passed to control_vars
, a separate call
is made to exp_stats()
using the control variables as grouping variables.
This is used to derive a new expected values basis called control
, which is
both added to .data
and appended to the expected
argument. In the final
output, a column called ae_control
shows the relative impact of any
grouping variables after accounting for the control variables.
About ".none"
: If ".none"
is passed to control_vars
, a single
aggregate termination rate is calculated for the entire data set and used to
compute control
and ae_control
.
The control_distinct_max
argument places an upper limit on the number of
unique values that a control variable is allowed to have. This limit exists
to prevent an excessive number of groups on continuous or high-cardinality
features.
It should be noted that usage of control variables is a rough approximation and not a substitute for rigorous statistical models. The impact of control variables is calculated in isolation and does consider other features or possible confounding variables. As such, control variables are most useful for exploratory data analysis.
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.
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()
MethodApplying summary()
to a exp_df
object will re-summarize the
data while retaining any grouping variables passed to the "dots"
(...
).
Herzog, Thomas (1999). Introduction to Credibility Theory
toy_census |> expose("2022-12-31", target_status = "Surrender") |>
exp_stats()
exp_res <- census_dat |>
expose("2019-12-31", target_status = "Surrender") |>
group_by(pol_yr, inc_guar) |>
exp_stats(control_vars = "product")
exp_res
summary(exp_res)
summary(exp_res, inc_guar)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.