insurancerating (version 0.8.2)

prepare_refinement: Prepare a model refinement workflow

Description

Create an editable refinement specification from a fitted pricing GLM. Smoothing, coefficient restrictions, shrinkage, rebasing and sublevel relativities can then be added in a defined order. These steps do not alter the fitted GLM until refit() is called.

Usage

prepare_refinement(model, data = NULL)

Value

A rating_refinement object containing the original GLM, retained model data and ordered refinement specification. No GLM is fitted again until refit() is called.

Arguments

model

Object of class glm.

data

Optional data.frame containing exactly the observations retained in the fitted GLM and all required model variables. If model fitting omitted rows because of missing values, supply the retained model data rather than the original unfiltered data. If NULL, the data are retrieved from the model object.

Author

Martin Haringa

Details

prepare_refinement() creates a persistent refinement specification. This object contains the original GLM, the corresponding model data and the ordered smoothing, restriction, shrinkage, rebasing and relativity steps. Retain this object during actuarial review so that assumptions can be inspected, revised and applied again in the same order.

Actuarial interpretation

Preparing a refinement does not change coefficients, fitted values or the tariff structure. It separates the original statistical model from subsequent actuarial adjustments. Each adjustment remains an explicit step rather than being embedded directly in transformed data or overwritten model coefficients. This supports comparison between the unrestricted model and alternative refinement specifications.

refit() applies the stored specification and returns a fitted GLM for model diagnostics, prediction and tariff reporting. The returned GLM is a result, not an editable refinement specification. Functions such as add_smoothing(), edit_smoothing(), add_restriction(), add_shrinkage(), add_rebasing() and add_relativities() therefore accept a rating_refinement object and do not accept an ordinary or refitted GLM directly.

A practical iterative workflow therefore keeps both objects:

refinement <- prepare_refinement(model) |>
  add_smoothing(...)
fitted_model <- refit(refinement)
refinement <- refinement |>
  edit_smoothing(...)
fitted_model <- refit(refinement)

prepare_refinement() is normally required only once for such an iteration. Calling it on a model returned by refit() deliberately starts a new refinement workflow with the already refined model as its baseline; it does not recover the earlier smoothing or restriction steps for further editing.

See Also

summary.rating_refinement(), add_smoothing(), edit_smoothing(), add_restriction(), add_shrinkage(), add_rebasing(), add_relativities(), refit()

Examples

portfolio <- data.frame(
  claims = c(1, 2, 1, 3, 2, 4),
  exposure = rep(1, 6),
  risk_class = factor(c("A", "B", "A", "B", "A", "B"))
)

model <- glm(
  claims ~ risk_class + offset(log(exposure)),
  family = poisson(),
  data = portfolio
)

refinement <- prepare_refinement(model, data = portfolio) |>
  add_restriction(data.frame(
    risk_class = "B",
    risk_class_restricted = 1.15
  ))

summary(refinement)

fitted_model <- refit(refinement)

# Retain and revise the specification rather than editing fitted_model.
refinement <- refinement |>
  add_restriction(data.frame(
    risk_class = "B",
    risk_class_restricted = 1.10
  ))

updated_model <- refit(refinement)