ExposedDF.exp_stats

expose.ExposedDF.exp_stats(target_status=None, expected=None, wt=None, conf_int=False, credibility=False, conf_level=0.95, cred_r=0.05, col_exposure='exposure')

Summarize experience study records

Create a summary of termination experience for a given target status (an ExpStats object).

Parameters

Name	Type	Description	Default
`target_status`	str \| list \| numpy.numpy.ndarray	A single string, list, or array of target status values	`None`
`expected`	str \| list \| numpy.numpy.ndarray	A single string, list, or array of column names in the `data` property with expected values	`None`
`wt`	str	Name of the column in the `data` property containing weights to use in the calculation of claims, exposures, and partial credibility.	`None`
`conf_int`	bool	If `True`, the output will include confidence intervals around the observed termination rates and any actual-to-expected ratios.	`False`
`credibility`	bool	Whether the output should include partial credibility weights and credibility-weighted decrement rates.	`False`
`conf_level`	float	Confidence level under the Limited Fluctuation credibility method	`0.95`
`cred_r`	float	Error tolerance under the Limited Fluctuation credibility method	`0.05`
`col_exposure`	str	Name of the column in `data` containing exposures. Only necessary for `SplitExposedDF` objects.	`'exposure'`

Notes

If the ExposedDF object is grouped (see the group_by() method), the returned ExpStats object’s data will contain one row per group.

If nothing is passed to target_status, the target_status property of the ExposedDF object will be used. If that property is None, 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 string, list, or array with values corresponding to columns in the data property containing expected experience. More than one expected basis can be provided.

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.

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.

Returns

Type Description

ExpStats An ExpStats object with a data property that includes columns for any grouping variables, claims, exposures, and observed decrement rates (q_obs). If any values are passed to expected, additional columns will be added for expected decrements and actual-to-expected ratios. If credibility is set to True, additional columns are added for partial credibility and credibility-weighted decrement rates (assuming values are passed to expected). 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).

Type	Description
`ExpStats`	An `ExpStats` object with a `data` property that includes columns for any grouping variables, claims, exposures, and observed decrement rates (`q_obs`). If any values are passed to `expected`, additional columns will be added for expected decrements and actual-to-expected ratios. If `credibility` is set to `True`, additional columns are added for partial credibility and credibility-weighted decrement rates (assuming values are passed to `expected`). 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`).

References

Herzog, Thomas (1999). Introduction to Credibility Theory

Examples

import actxps as xp

(xp.ExposedDF(xp.load_census_dat(),
              "2019-12-31", 
              target_status="Surrender").
    group_by('pol_yr', 'inc_guar').
    exp_stats(conf_int=True))

Experience study results

Groups: pol_yr, inc_guar
Target status: Surrender
Study range: 1900-01-01 to 2019-12-31

shape: (30, 8)
┌────────┬──────────┬──────────┬────────┬──────────────┬──────────┬─────────────┬─────────────┐
│ pol_yr ┆ inc_guar ┆ n_claims ┆ claims ┆ exposure     ┆ q_obs    ┆ q_obs_lower ┆ q_obs_upper │
│ ---    ┆ ---      ┆ ---      ┆ ---    ┆ ---          ┆ ---      ┆ ---         ┆ ---         │
│ u32    ┆ bool     ┆ u32      ┆ u32    ┆ f64          ┆ f64      ┆ f64         ┆ f64         │
╞════════╪══════════╪══════════╪════════╪══════════════╪══════════╪═════════════╪═════════════╡
│ 1      ┆ false    ┆ 56       ┆ 56     ┆ 7719.80545   ┆ 0.007254 ┆ 0.005441    ┆ 0.009197    │
│ 1      ┆ true     ┆ 46       ┆ 46     ┆ 11532.402336 ┆ 0.003989 ┆ 0.002862    ┆ 0.005203    │
│ 2      ┆ false    ┆ 92       ┆ 92     ┆ 7102.810869  ┆ 0.012953 ┆ 0.010418    ┆ 0.015628    │
│ 2      ┆ true     ┆ 68       ┆ 68     ┆ 10611.955805 ┆ 0.006408 ┆ 0.0049      ┆ 0.00801     │
│ 3      ┆ false    ┆ 67       ┆ 67     ┆ 6446.913856  ┆ 0.010393 ┆ 0.008066    ┆ 0.012874    │
│ …      ┆ …        ┆ …        ┆ …      ┆ …            ┆ …        ┆ …           ┆ …           │
│ 13     ┆ true     ┆ 49       ┆ 49     ┆ 1117.137361  ┆ 0.043862 ┆ 0.032225    ┆ 0.056394    │
│ 14     ┆ false    ┆ 33       ┆ 33     ┆ 262.622262   ┆ 0.125656 ┆ 0.087578    ┆ 0.167541    │
│ 14     ┆ true     ┆ 29       ┆ 29     ┆ 609.216476   ┆ 0.047602 ┆ 0.031188    ┆ 0.065658    │
│ 15     ┆ false    ┆ 8        ┆ 8      ┆ 74.046456    ┆ 0.10804  ┆ 0.040515    ┆ 0.18907     │
│ 15     ┆ true     ┆ 9        ┆ 9      ┆ 194.128602   ┆ 0.046361 ┆ 0.020605    ┆ 0.077268    │
└────────┴──────────┴──────────┴────────┴──────────────┴──────────┴─────────────┴─────────────┘