custom_rating_functions: Custom rating functions

In ratingtables: Table-Driven Insurance Rating

Custom rating functions

Description

Custom rating functions allow a rating-plan step to use arbitrary R code when the calculation cannot conveniently be expressed as a standard factor lookup, interpolation, or input-value step.

Details

A custom function must accept the following arguments:

row

A one-row data frame containing the record being rated.

coverage

The coverage currently being rated.

current_premium

The running premium immediately before this step.

plan

The rating plan.

spec_row

The rating-specification row for this step.

lookup

A helper function for retrieving values from the plan's factor table.

The lookup helper has the form

lookup(term_name, value_source = "factor_lookup", lookup_var = NULL, bounds = "error")

and returns a lookup result whose numeric value is available as ⁠$value⁠.

A custom function should normally return a single numeric value.

To use the function, set value_source = "custom_function" in the rating specification, supply the function name in custom_function, and register the function in the custom_functions argument to new_rating_plan().

The calculation_type still controls how the returned value is applied. For example, "multiplicative" multiplies the running premium by the returned value, while "replace" replaces the running premium.

Examples

factor_table <- data.frame(
  coverage = c("BI", "BI"),
  term_name = c("base", "hidden_modifier"),
  term_value = c(100, 1.20)
)

rating_spec <- data.frame(
  step_number = 1:2,
  term_name = c("base", "custom_total"),
  value_source = c("factor_lookup", "custom_function"),
  calculation_type = c("multiplicative", "custom"),
  custom_function = c(NA, "add_fee_after_modifier")
)

add_fee_after_modifier <- function(
  row, coverage, current_premium, plan, spec_row, lookup
) {
  modifier <- lookup("hidden_modifier")$value
  current_premium * modifier + row$fee[[1]]
}

plan <- new_rating_plan(
  factor_table = factor_table,
  rating_spec = rating_spec,
  coverages = "BI",
  custom_functions = list(
    add_fee_after_modifier = add_fee_after_modifier
  )
)

policy <- data.frame(
  policy_id = "P1",
  fee = 5
)

rate_policies(policy, plan)

ratingtables documentation built on Sept. 6, 2026, 1:06 a.m.