Package {raterevision}

raterevision: insurance rate revision workflow tools

Description

raterevision provides a deliberately narrow set of tools for moving from a current insurance rating plan to a proposed one. It complements ratingtables, but the analysis helpers accept ordinary data frames and the target solver accepts arbitrary user-supplied rating code.

Details

The main workflow is:

• reshape normalized factor tables for human review with rate_tables_wide();

• round-trip those tables through Excel with write_rate_workbook() and read_rate_workbook();

• construct proposed tables with replace_factor_set(), update_factors(), rebase_factor_set(), and normalize_factor_set();

• review changes with rate_plan_diff() and validate_rate_plan();

• compare rated outputs using compare_rating_outputs(), summarize_rate_change(), and rate_change_distribution(); and

• solve a scalar rate-level adjustment with solve_rate_target().

Author(s)

Maintainer: Greg Sollenberger yagreg7@yahoo.com [copyright holder]

Authors:

• Greg Sollenberger yagreg7@yahoo.com [copyright holder]

See Also

Useful links:

• https://github.com/gs-actuary/raterevision

• Report bugs at https://github.com/gs-actuary/raterevision/issues

Compare current and proposed rating outputs

Description

Standardizes current/proposed output into one long comparison table. It can consume the wide ⁠indicated_<coverage>⁠ columns produced by ratingtables, or already-long output with an explicit premium and coverage column.

Usage

compare_rating_outputs(
  current,
  proposed,
  id_cols,
  premium_cols = NULL,
  premium_prefix = "indicated_",
  premium_col = NULL,
  coverage_col = NULL,
  keep_cols = NULL
)

Arguments

Value

Long comparison data with current/proposed premium and changes.

Diagnose differences between a reference rater and a candidate rater

Description

Uses grouped discrepancy scans and lightweight statistical models to identify rating variables associated with missing or incorrect candidate premiums. The models are diagnostic tools, not production predictive models: no tuning grid or cross-validation is performed, and the default print method reports only high-level findings.

Usage

diagnose_rating_output(
  comparison,
  predictors = NULL,
  absolute_tolerance = 0.01,
  relative_tolerance = 1e-06,
  top_n = 5L,
  model_sample = 50000L,
  max_model_levels = 40L,
  interaction_top = 4L,
  seed = 1L
)

Arguments

Details

The input is normally created by compare_rating_outputs(), with all useful rating variables carried through via its keep_cols argument. In a migration workflow, current_premium should represent the trusted/reference premium and proposed_premium the candidate ratingtables premium.

Value

An object of class raterevision_rater_diagnosis containing summary counts, variable/level diagnostics, optional coverage_summary and coverage_level_details (when coverage is present), model signals, interaction signals, and the fitted lightweight models for advanced inspection.

Extract candidate rate tables from a profiled workbook

Description

Reads the candidate regions selected in a profile_rate_workbook() result and returns a named list of rectangular data frames. The object intentionally uses the same list-oriented interface as rate_tables_wide(), while retaining source-sheet/range metadata so that a migration can be reviewed and refined.

Usage

extract_rate_tables(
  profile,
  file = attr(profile, "file"),
  only_included = TRUE,
  min_confidence = NULL
)

Arguments

Details

This function does not claim that the extracted rectangles are already valid normalized ratingtables factor tables. It is an ingestion step: uncertain candidates should be reviewed, renamed, resized, or excluded in the profile before extraction.

Value

A named list of rectangular data frames with class raterevision_tables. A manifest is stored in the manifest attribute.

Normalize the weighted mean of a factor set

Description

Scales factors so that their weighted mean equals target_mean within each grouping. Equal weights are used by default. If real portfolio exposures are desired, merge or align those weights to the factor rows first and supply them through weights.

Usage

normalize_factor_set(
  factor_table,
  term_name,
  weights = NULL,
  target_mean = 1,
  by = NULL
)

Arguments

Value

The full factor table with the selected term normalized.

Profile an Excel workbook for candidate rating tables

Description

Scans an arbitrary .xlsx workbook and identifies rectangular regions that look like rating tables. The profiler is deliberately heuristic: it uses connected nonblank regions, header structure, numeric density, and nearby labels to make educated guesses. The returned profile is intended to be reviewed and, when necessary, edited before extraction.

Usage

profile_rate_workbook(
  file,
  sheets = NULL,
  min_cells = 3L,
  min_rows = 1L,
  min_cols = 2L,
  include_threshold = 0.5,
  title_lookback = 3L
)

Arguments

Value

A data frame with class raterevision_workbook_profile. Each row is a candidate table. The include, table_name, extract_range, and header_row fields may be edited before calling extract_rate_tables().

Summarize the distribution of rate impacts

Description

Summarize the distribution of rate impacts

Usage

rate_change_distribution(
  comparison,
  breaks = c(-Inf, -0.2, -0.1, -0.05, 0, 0.05, 0.1, 0.2, Inf),
  by = NULL
)

Arguments

Value

Rate-change distribution by bucket and optional groups.

Compare current and proposed factor tables

Description

Produces a row-level audit of added, removed, changed, and unchanged factor keys. factor_row_id is ignored by default because it is not a rating key.

Usage

rate_plan_diff(
  current,
  proposed,
  key_cols = NULL,
  tolerance = sqrt(.Machine$double.eps),
  include_unchanged = TRUE
)

Arguments

Value

A data frame with current/proposed values, changes, and status.

Convert wide rate tables back to normalized long format

Description

Reconstructs a normalized factor table from the object produced by rate_tables_wide(). This is the non-Excel reverse transformation used by read_rate_workbook().

Usage

rate_tables_long(
  tables,
  manifest = attr(tables, "manifest"),
  add_factor_row_id = TRUE
)

Arguments

Value

A normalized long-format factor table.

Convert a normalized factor table to wide rate tables

Description

Converts a ratingtables-style normalized factor table into a named list of actuary-friendly data frames. Coverages become columns. One-way and higher interactions remain long by default; selected two-way interactions can be displayed as matrices with one interaction variable down rows and the other across columns. Matrix layout is intentionally prohibited for interactions deeper than two variables.

Usage

rate_tables_wide(
  factor_table,
  filters = NULL,
  matrix_terms = character(),
  sort_rows = TRUE
)

Arguments

Value

A named list of data frames with class raterevision_tables. A machine-readable manifest is stored in the manifest attribute.

Read an Excel rate workbook

Description

Reads a workbook created by write_rate_workbook(). By default the visible tables are reconstructed into a normalized long factor table suitable for ratingtables or further programmatic revision.

Usage

read_rate_workbook(file, return = c("long", "tables"), validate = TRUE)

Arguments

Value

A normalized factor table or raterevision_tables object.

Rebase a factor set to a selected rating level

Description

Divides all factors within each applicable rate-set/coverage group by the factor at a selected reference level. This makes the selected level equal to 1.000 while preserving all relativities. Rebasing is a presentation/basis operation; it is distinct from normalize_factor_set(), which controls a weighted average level.

Usage

rebase_factor_set(factor_table, term_name, base_level, by = NULL)

Arguments

Value

The full factor table with the selected term rebased.

Replace complete factor-table slices

Description

Replaces complete slices of a current factor table with rows from a replacement table. This differs from update_factors(), which changes only explicitly supplied cells. By default a slice is identified by rate-set metadata, coverage, term name, and variable-name columns; level columns are intentionally excluded so omitted levels are removed.

Usage

replace_factor_set(current, replacement, term_names = NULL, slice_cols = NULL)

Arguments

Value

A normalized factor table.

Solve a target aggregate rate change

Description

Finds a single numeric parameter that makes an arbitrary proposed rating workflow achieve a desired aggregate rate change from a supplied current premium. The solver does not know or care whether the proposed workflow uses the same specification, a structurally different specification, driver averaging, custom R code, or territory-specific base rates. The user defines the one-dimensional adjustment inside rate_function.

Usage

solve_rate_target(
  current_premium,
  target,
  rate_function,
  interval = c(0.5, 1.5),
  premium_extractor = NULL,
  tol = 1e-08,
  maxiter = 100L,
  extend_interval = c("no", "yes", "upX", "downX"),
  parameter_name = "multiplier"
)

Arguments

Details

A common territory-base use is to let x multiply every territory-specific base rate, preserving the proposed territorial shape while solving one overall rate-level parameter. If several base rates are allowed to move independently against one aggregate target, the problem is underdetermined and should not be passed to this scalar solver. Independent targets (for example one target per coverage) can be solved by calling this function once per independently adjustable parameter.

Value

A raterevision_target_solution object.

Summarize aggregate rate change

Description

Summarize aggregate rate change

Usage

summarize_rate_change(comparison, by = "coverage", exposure_col = NULL)

Arguments

Value

Aggregate current/proposed premium and rate change by group.

Apply sparse factor updates

Description

Updates only the factor keys supplied in updates. New keys are rejected by default so that a typo cannot silently create a rating level.

Usage

update_factors(current, updates, key_cols = NULL, allow_new_levels = FALSE)

Arguments

Value

Updated normalized factor table.

Validate a normalized rate factor table

Description

Performs revision-oriented checks without duplicating the full rating-spec validation in ratingtables. It checks required columns, factor values, duplicate keys, variable/level slot consistency, and optionally positivity for known multiplicative terms.

Usage

validate_rate_plan(factor_table, multiplicative_terms = NULL, error = TRUE)

Arguments

Value

A raterevision_validation data frame. If error = TRUE, validation errors are also raised as an error.

Write rate tables to an Excel workbook

Description

Writes normalized factors or a rate_tables_wide() list to an .xlsx workbook. The workbook contains one visible sheet per rate table, an optional instruction sheet, and a very-hidden ⁠_raterevision⁠ manifest used for a deterministic round trip back into R.

Usage

write_rate_workbook(
  x,
  file,
  filters = NULL,
  matrix_terms = character(),
  overwrite = TRUE,
  include_readme = TRUE
)

Arguments

Value

The file path, invisibly.