Package 'insurancerating'

Match event dates to active portfolio periods

Description

Match event dates, such as claim dates or inspection dates, to policy records that were active when the event occurred. The matched result contains the portfolio characteristics and coverage information applicable on each event date.

Usage

active_rows_by_date(
  portfolio,
  dates,
  period_start,
  period_end,
  date,
  by = NULL,
  unmatched = c("drop", "keep"),
  multiple_matches = c("all", "first", "last"),
  nomatch = NULL,
  mult = NULL
)

Arguments

portfolio	A data.frame or data.table with portfolio rows and active date intervals.
dates	A data.frame or data.table with event or snapshot dates.
period_start	Character string. Name of the portfolio column with period start dates.
period_end	Character string. Name of the portfolio column with period end dates.
date	Character string. Name of the date column in dates.
by	Character vector with additional columns used to match portfolio and dates, for example policy number or claim identifier.
unmatched	Character string. Use "drop" to omit event dates for which no active portfolio row is found, or "keep" to retain them with missing portfolio information. The default is "drop".
multiple_matches	Character string controlling events that match multiple active portfolio rows. Use "all" to retain every match, or "first" or "last" to retain one matching row. The default is "all".
nomatch, mult	Deprecated technical argument names. Use unmatched and multiple_matches instead.

Details

Claim and event files often contain an event date and policy identifier but not the rating factors used at that point in time. The function performs an interval match between those events and the portfolio history. Supplying a policy identifier through by prevents an event from matching active periods belonging to another policy.

This is a temporal matching operation rather than a portfolio reduction. See merge_date_ranges() for consolidating connected coverage periods and split_periods_to_months() for expanding periods into monthly records.

Multiple matches can be valid when one event relates to several concurrently active coverages. They can also reveal overlapping or duplicated policy periods. Use multiple_matches = "all" when every active record is relevant; use "first" or "last" only when the source system defines which record should take precedence.

With unmatched = "drop", events outside every applicable coverage period are omitted. With unmatched = "keep", they remain visible with missing portfolio fields. Retaining unmatched events is generally preferable during data-quality review because it makes gaps in the policy history explicit.

The interval join is performed internally with data.table::foverlaps() on local copies. Neither input is modified by reference. The output follows the original order of dates and is always returned as a regular data.frame.

Value

A regular data.frame containing the event records and the portfolio information active on their dates. Event order is preserved. Depending on multiple_matches, one event can produce more than one output row.

Author(s)

Martin Haringa

See Also

split_periods_to_months(), merge_date_ranges(), rating_grid()

Examples

portfolio <- data.frame(
  policy_id = c("P001", "P001", "P002"),
  coverage_start = as.Date(c("2024-01-01", "2025-01-01", "2025-01-01")),
  coverage_end = as.Date(c("2024-12-31", "2025-12-31", "2025-12-31")),
  sector = c("Retail", "Industry", "Services"),
  insured_amount = c(500000, 750000, 300000),
  earned_premium = c(900, 1250, 650)
)

claims <- data.frame(
  claim_id = c("C001", "C002", "C003"),
  policy_id = c("P001", "P001", "P002"),
  claim_date = as.Date(c("2024-06-15", "2025-08-10", "2026-01-10")),
  claim_amount = c(12000, 45000, 8000)
)

# Attach the policy characteristics that applied on each claim date.
active_rows_by_date(
  portfolio,
  claims,
  period_start = "coverage_start",
  period_end = "coverage_end",
  date = "claim_date",
  by = "policy_id"
)

# Keep claims outside the available policy history for data-quality review.
active_rows_by_date(
  portfolio,
  claims,
  period_start = "coverage_start",
  period_end = "coverage_end",
  date = "claim_date",
  by = "policy_id",
  unmatched = "keep"
)

---

Add portfolio experience to a rating table

Description

add_portfolio_experience() enriches a rating_table() object with observed portfolio experience. When data is supplied, observed experience is calculated automatically for all risk factors in the rating table, unless risk_factors is specified. Existing factor_analysis() results can also be supplied through observed.

This makes it possible to compare fitted GLM relativities with observed portfolio patterns in autoplot.rating_table(). The full observed output is stored on the rating table, so autoplot.rating_table() can later switch between metrics such as "frequency", "average_severity" and "risk_premium" without recalculating the summaries.

The observed metric is scaled before plotting. With scale = "reference" the metric is divided by the observed value of the model reference level. If a clear reference level cannot be found, the metric is scaled to its mean. With scale = "mean", the metric is always scaled to its mean.

Usage

add_portfolio_experience(x, ...)

## S3 method for class 'rating_table'
add_portfolio_experience(
  x,
  observed = NULL,
  data = NULL,
  risk_factors = NULL,
  claim_count = NULL,
  exposure = NULL,
  claim_amount = NULL,
  metric = NULL,
  label = "Observed experience",
  color = NULL,
  scale = c("reference", "mean"),
  experience = NULL,
  ...
)

Arguments

x	A rating_table object returned by rating_table().
...	Unused.
observed	Optional factor_analysis() object or list of factor_analysis() objects. If supplied, these observed summaries are attached directly.
data	Optional data.frame. If observed = NULL, observed experience is calculated from this data.
risk_factors	Optional character vector. Risk factors for which observed experience should be calculated. If NULL, all risk factors in the rating table are used.
claim_count	Optional character string. Claim count column used by factor_analysis().
exposure	Optional character string. Exposure column used by factor_analysis().
claim_amount	Optional character string. Claim amount column used by factor_analysis().
metric	Optional character string. Default observed metric to plot. Common choices are "frequency", "severity"/"average_severity" and "risk_premium". The metric can also be overridden in autoplot.rating_table().
label	Character; legend label for the observed experience line.
color	Optional line color. If NULL, the internal risk premium color is used.
scale	Character; scaling applied before plotting. One of "reference" or "mean".
experience	Deprecated alias for observed.

Value

A rating_table object with observed portfolio experience attached.

Author(s)

Martin Haringa

Examples

df <- MTPL2
df$area <- as.factor(df$area)

model <- glm(
  nclaims ~ area + offset(log(exposure)),
  family = poisson(),
  data = df
)

rating_table(model, model_data = df, exposure = "exposure") |>
  add_portfolio_experience(
    data = df,
    claim_count = "nclaims",
    exposure = "exposure"
  ) |>
  autoplot(risk_factors = "area", metric = "frequency")

observed <- factor_analysis(
  df,
  risk_factors = "area",
  claim_count = "nclaims",
  exposure = "exposure"
)

rating_table(model, model_data = df, exposure = "exposure") |>
  add_portfolio_experience(observed = observed) |>
  autoplot(risk_factors = "area")

---

Add model predictions to a pricing data set

Description

add_prediction() adds predictions from one or more fitted glm models to a data frame.

In pricing workflows, this is often used to bring count and severity model output together on the same portfolio. For example, an expected claim count can be normalised by exposure and multiplied by an expected average claim amount to calculate a risk premium per exposure unit.

The function is deliberately small: it does not refit models or decide how predictions should be combined. It only adds model predictions, and optionally confidence intervals, using clear output column names.

Usage

add_prediction(
  data,
  ...,
  predictions = NULL,
  prefix = "pred",
  confidence = FALSE,
  interval_names = c("lower", "upper"),
  alpha = 0.1,
  var = NULL,
  conf_int = NULL
)

Arguments

data	A data.frame containing the new data for which predictions should be generated.
...	One or more fitted model objects of class "glm".
predictions	Optional character vector giving names for the new prediction columns. Must have the same length as the number of models supplied. If NULL (default), names are generated automatically using prefix, the model response, and the model object name.
prefix	Character. Prefix used for automatically generated prediction column names. Default is "pred".
confidence	Logical. If TRUE, add confidence intervals for predictions. Default is FALSE.
interval_names	Character vector of length two. Names appended to the prediction column name for lower and upper confidence interval bounds. Default is c("lower", "upper").
alpha	Numeric between 0 and 1. Controls the miscoverage level for interval estimates. Default is 0.10, corresponding to a 90% confidence interval.
var	Deprecated. Use predictions instead.
conf_int	Deprecated. Use confidence instead.

Details

Predictions are calculated on the response scale using stats::predict(..., type = "response"). For GLMs with a log link, such as Poisson count models or Gamma severity models, the added columns are already on the original response scale. For a Poisson claim-count model containing an exposure offset, this is the expected claim count for the supplied exposure, not frequency per exposure unit. Divide by exposure when a rate is required.

If confidence = TRUE, lower and upper confidence interval columns are added next to each prediction column. The default interval suffixes are "lower" and "upper".

Predictions containing missing values are retained. If one or more NA predictions are produced, the function issues a warning with the affected prediction columns and number of missing predictions. This is typically caused by missing predictor values in data or by predictor values outside the domain supported by the fitted model.

Value

A data.frame containing the original data and additional columns for model predictions. If confidence = TRUE, confidence interval columns are added as well.

Author(s)

Martin Haringa

Examples

mod1 <- glm(nclaims ~ age_policyholder,
            data = MTPL,
            offset = log(exposure),
            family = poisson())

# Add the expected claim count for each record's exposure
mtpl_pred <- add_prediction(
  MTPL,
  mod1,
  predictions = "expected_claim_count"
)

# Add predicted values with confidence bounds
mtpl_pred_ci <- add_prediction(
  MTPL,
  mod1,
  predictions = "expected_claim_count",
  confidence = TRUE
)

# Combine frequency and severity predictions into a risk premium
freq <- glm(nclaims ~ bm + zip,
            data = MTPL,
            offset = log(exposure),
            family = poisson())

severity_data <- MTPL[MTPL$nclaims > 0 & MTPL$amount > 0, ]
severity_data$average_claim_amount <-
  severity_data$amount / severity_data$nclaims

sev <- glm(average_claim_amount ~ bm + zip,
           data = severity_data,
           weights = nclaims,
           family = Gamma(link = "log"))

pricing <- add_prediction(
  MTPL,
  freq,
  sev,
  predictions = c("expected_claim_count", "expected_average_severity")
)

pricing$claim_frequency <-
  pricing$expected_claim_count / pricing$exposure
pricing$expected_loss <-
  pricing$expected_claim_count * pricing$expected_average_severity
pricing$risk_premium <-
  pricing$claim_frequency * pricing$expected_average_severity

---

Rebase categorical tariff relativities to a reference level

Description

Rescale the current relativities of one categorical risk factor so that a selected level has relativity 1. add_rebasing() is an ordered refinement step: it uses the relativities available at that point in the workflow and retains all ratios between levels.

Usage

add_rebasing(model, model_variable, reference_level = NULL, weights = NULL)

Arguments

model	A rating_refinement object created with prepare_refinement(). Rebasing uses the current relativities at this point in the ordered workflow.
model_variable	Character string naming the categorical risk factor to rebase. This may identify an original GLM factor or a tariff factor created by an earlier add_relativities(), add_restriction() or add_shrinkage() step.
reference_level	Optional single character value naming the level that should receive relativity 1. When NULL, the level with the largest aggregated weight is selected automatically.
weights	NULL or a character string naming a numeric, non-negative column in the refinement data. The weights are used only when reference_level = NULL. NULL derives the basis from explicit model weights or a simple exposure offset.

Details

Rebasing changes the numerical reference of a tariff factor, but does not change its relative differentiation. If the current relativity of reference level $j$ is $r_j$, every level is transformed as

$r_i^{new} = \frac{r_i}{r_j}.$

The selected reference level therefore becomes 1, while the ratio between any two levels remains unchanged. For example, relativities 0.8, 1.0 and 1.2 rebased to the first level become 1.0, 1.25 and 1.5. This is different from add_shrinkage(), which deliberately reduces the spread between levels.

Selecting the reference level

Supply reference_level when the tariff has an established reference class or when governance requires a particular level to remain at 1. If reference_level = NULL, the level with the largest aggregated weight is selected. Ties are resolved by the order of the current factor levels.

With weights = NULL, explicit GLM weights are used when available; otherwise a single offset of the form log(column) is used. This commonly selects claim count for a weighted severity GLM and exposure for a frequency or risk-premium GLM. An explicit numeric column can be supplied when another portfolio basis is required. weights is ignored when reference_level is supplied because no automatic selection is then needed.

Position in the refinement workflow

Rebasing is generally applied after the step that creates the final tariff levels. For example, add_relativities() may replace a broad level by several sublevels; add_rebasing() can then select one of those resulting sublevels as the new reference. It can also follow add_shrinkage() when the shrunken relativities should be reported relative to an established level.

set_reference_level() serves a different purpose. It changes the contrast reference of a factor before fitting a GLM. add_rebasing() rescales current tariff relativities inside an existing refinement specification. The refinement step and selected reference are retained for review by summary() and audit_refinement().

Value

A rating_refinement object containing an ordered rebasing step. The step stores the original and rebased relativities, the selected reference level, its original relativity, the selection method and, when applicable, the aggregated level weights. The GLM is fitted only when refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), set_reference_level(), add_relativities(), add_shrinkage(), add_restriction(), refit(), audit_refinement()

Examples

portfolio <- data.frame(
  claims = c(1, 2, 1, 3, 2, 4, 1, 5),
  exposure = c(1, 1, 1, 1, 2, 1, 1, 1),
  sector = factor(rep(c("Industry", "Office", "Retail", "Transport"), 2))
)

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

# Keep Office as the explicit tariff reference after shrinkage.
refinement <- prepare_refinement(model, data = portfolio) |>
  add_shrinkage(
    model_variable = "sector",
    credibility = 0.9,
    weights = "exposure"
  ) |>
  add_rebasing(
    model_variable = "sector",
    reference_level = "Office"
  )

summary(refinement)
refined_model <- refit(refinement)
rating_table(refined_model)

# Omitting reference_level selects the level with the largest exposure.
exposure_reference <- prepare_refinement(model, data = portfolio) |>
  add_rebasing(
    model_variable = "sector",
    weights = "exposure"
  )

---

Add sublevel relativities to a refinement workflow

Description

Divide one or more levels of an existing GLM risk factor into more detailed tariff levels using supplied relativities. This can be appropriate when the GLM is estimated on a coarser factor for statistical stability, while a documented actuarial segmentation is required within sufficiently homogeneous model levels.

Usage

add_relativities(
  model,
  model_variable,
  split_variable,
  relativities,
  exposure,
  normalize = TRUE,
  output_variable = paste0(model_variable, "_refined")
)

Arguments

model	Object of class rating_refinement, created with prepare_refinement(). A fitted GLM, including a model returned by refit(), is not accepted directly; retain and modify the corresponding refinement specification instead.
model_variable	Character string. Existing variable in the GLM, or a restricted version created by an earlier add_restriction() step. Levels of the underlying model variable can be split into more detailed tariff segments. When an earlier restriction exists, its coefficients are used automatically.
split_variable	Character string. More granular portfolio variable that defines the detailed groups inside model_variable.
relativities	Named list of data frames, usually created with relativities() and split_level().
exposure	Character string. Exposure column used for weighting and, when requested, normalisation.
normalize	Logical. If TRUE, normalise the supplied relativities by exposure within each split model level.
output_variable	Character string naming the resulting hybrid tariff factor. The default appends ⁠_refined⁠ to model_variable. A more application-specific name, such as sbi_tariff_segment, can make the intended tariff use clearer in model output and reporting. The name must not overwrite an existing column in the refinement data.

Details

add_relativities() stores a relativity step on a rating_refinement object. It does not alter the fitted GLM immediately. The split is evaluated in the recorded step order and applied when refit() is called.

model_variable is the variable already used in the GLM. split_variable is the more detailed variable in the portfolio data that will be used to split one or more levels of model_variable. The relativities argument should be a named list describing those splits, usually built with relativities() and split_level(). output_variable names the resulting hybrid tariff factor: levels included in relativities are represented by their detailed split_variable level, while all other levels retain their model_variable level.

Levels of model_variable that are not included in relativities retain their existing model coefficient. In rating_table(), exposure for these retained levels is aggregated from model_variable, while exposure for the newly split levels is aggregated from split_variable within the specified parent model level. Omitting a model level from relativities therefore means that the level remains unsplit; it is not treated as an incomplete specification.

add_relativities() validates the supplied sublevel names against the observed values of split_variable before storing the refinement step. A misspelled or incorrectly spaced category or sublevel therefore produces an immediate error, with a suggestion when a closely matching observed value is available. It also verifies that each sublevel occurs within its specified parent category of model_variable.

When normalize = TRUE, the supplied relativities are normalised using exposure so that their exposure-weighted mean equals one within the split model level. They then redistribute the existing model coefficient across the sublevels without changing its exposure-weighted average. With normalize = FALSE, the supplied relativities are applied directly.

Step order and restrictions

If model_variable was restricted in an earlier add_restriction() step, the restricted coefficients are automatically used as the basis for the derived relativities. The user can continue to supply the original model variable; no additional argument is needed. Supplying the restricted variable explicitly gives the same coefficient basis and does not apply the restriction a second time. Refinement steps are order-dependent, so a restriction added after add_relativities() does not affect an earlier relativity step. Once the restricted coefficients have been used to derive the final split, rating_table() reports output_variable as the tariff factor and does not also show the intermediate restricted variable.

This also applies to restriction_type = "multiplier": a multiplier on a parent level is included once in the coefficient from which its sublevels are derived. The split replaces the preceding restricted effect in the model offset. For example, a parent relativity of 0.80, multiplied by 1.15 and split with an unnormalised sublevel relativity of 0.90, gives 0.80 * 1.15 * 0.90.

Conversely, add_restriction() can be called after add_relativities() to adjust selected levels of the derived output_variable. The output variable is then recognised as an existing refinement factor; users do not need to set allow_new_risk_factors = TRUE. Levels omitted from the restriction table are fixed at the relativities calculated by this step.

Rating grids and audits

After refit(), rating_grid() groups by the output factor in place of its parent. The numeric split relativity is mapped to the output levels, which may have different values within one parent level. Later shrinkage and rebasing retain this segment-level grid, including when refit(intercept_only = TRUE) is used. audit_refinement() reviews these final segments while retaining the original variables for baseline predictions.

Appropriate use

add_relativities() is intended for refinement within an already reasonably homogeneous GLM segment. It redistributes an existing coefficient across sublevels using exposure-weighted relativities, while preserving the overall level of the original coefficient when normalisation is used. Appropriate applications include mild residual heterogeneity, monotonic tariff differentiation and expert-based segmentation within a stable risk group where the original GLM coefficient remains broadly representative.

Limitations

The method is not a substitute for creating a separate risk segment when the original GLM coefficient is itself distorted. For example, suppose a broad industry segment contains many relatively stable businesses, but a few chemical companies drive most of the losses while representing little exposure. The fitted industry coefficient may then be dominated by the chemical companies' experience. Applying exposure-weighted relativities inside that segment may barely reduce the coefficient for the large exposure group, because the original coefficient is already pulled upward by the outlier subgroup.

In that situation it is often better to create a separate GLM factor level, derive a separate tariff segment, or apply explicit segmentation or acceptation rules, instead of relying only on add_relativities().

Value

A rating_refinement object containing the stored relativity specification. The pricing GLM is not fitted again until refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), relativities(), split_level(), add_restriction(), add_shrinkage(), add_rebasing(), add_smoothing(), refit(), rating_table()

Examples

portfolio <- data.frame(
  claims = c(1, 2, 1, 3, 2, 4),
  exposure = rep(1, 6),
  construction = factor(c("residential", "commercial", "residential",
                          "commercial", "residential", "commercial")),
  construction_detail = factor(c("flat", "shop", "house",
                                 "office", "flat", "shop"))
)

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

relativities <- relativities(
  split_level(
    "residential",
    new_levels = c(flat = 0.95, house = 1.05)
  ),
  split_level(
    "commercial",
    new_levels = c(shop = 1.10, office = 0.90)
  )
)

refined <- prepare_refinement(model, data = portfolio) |>
  add_relativities(
    model_variable = "construction",
    split_variable = "construction_detail",
    output_variable = "construction_tariff_segment",
    relativities = relativities,
    exposure = "exposure"
  )

# A subsequent restriction can revise one derived level. The remaining
# tariff-segment levels are fixed at the relativities calculated above.
refined <- refined |>
  add_restriction(data.frame(
    construction_tariff_segment = "flat",
    construction_tariff_segment_restricted = 1.00
  ))

refined_model <- refit(refined)
rating_table(refined_model, exposure = FALSE)

---

Add coefficient restrictions to a refinement workflow

Description

Fix selected risk-factor levels at user-supplied relativities or apply multiplicative adjustments to their current relativities before the refined pricing GLM is fitted. This can be appropriate when sampling variation produces an implausible local effect, when an actuarial assumption is supported by additional information, or when a documented tariff constraint must be applied consistently.

Usage

add_restriction(
  model,
  restrictions,
  allow_new_levels = TRUE,
  allow_new_risk_factors = FALSE,
  replaces = NULL,
  restriction_type = c("fixed", "multiplier"),
  model_variable = NULL,
  output_variable = NULL
)

Arguments

model	Object of class rating_refinement, created with prepare_refinement(). A fitted GLM, including a model returned by refit(), is not accepted directly; retain and modify the corresponding refinement specification instead.
restrictions	Preferably a named numeric vector: names identify levels and values contain fixed relativities or multipliers. In this form, model_variable is required. Alternatively, a data frame with exactly two columns remains fully supported. Its first column identifies the risk factor and must contain character or factor levels; numeric level columns are rejected. Its second column names the generated tariff column and contains numeric values. Unspecified levels are fixed at their current values or receive multiplier 1, respectively.
allow_new_levels	Logical. If TRUE (default), restrictions may contain levels that were not observed in the model data. Their supplied relativities are treated as explicit tariff assumptions rather than model estimates. If FALSE, an unknown level results in an error.
allow_new_risk_factors	Logical. If FALSE (default), the first column of restrictions must identify a variable included in the fitted GLM or a tariff factor created by an earlier refinement step. Set this to TRUE to add an external variable that is present in the refinement data but absent from both the model and preceding refinement steps. All observed levels must then have supplied relativities, which are treated as fixed tariff assumptions. For an existing model or refinement factor, TRUE is also valid, has no additional effect, and does not itself emit a warning or message. This permission never allows a multiplier to create a new factor.
replaces	NULL (default) or a character string naming an existing standalone model term that the new fixed risk factor replaces. During refit(), this term is removed before the restricted relativity column is added. Supplying replaces also provides the explicit opt-in required for a new risk factor; allow_new_risk_factors = TRUE is then unnecessary. Existing terms used in transformations or interactions cannot be replaced through this argument.
restriction_type	Character string. "fixed" (default) sets selected levels to the supplied relativities. "multiplier" multiplies the relativity present at that point in the refinement workflow by each supplied value.
model_variable	NULL for the two-column data-frame form, or a character string identifying the risk factor when restrictions is a named numeric vector. This can also identify the output_variable from an earlier add_relativities() step.
output_variable	Optional name for the generated tariff column when using named-vector restrictions. Defaults to paste0(model_variable, "_restricted") for fixed restrictions and paste0(model_variable, "_multiplier") for multiplier restrictions. With data-frame restrictions, the second column name fulfils this role.

Details

add_restriction() stores a restriction step on a rating_refinement object. It does not alter the fitted GLM immediately. The restriction is evaluated in the recorded step order and applied when refit() is called. Retain the refinement object when reviewing or revising the specification.

With restriction_type = "fixed", the supplied values become the final relativities for the selected levels. With restriction_type = "multiplier", each supplied value multiplies the relativity that exists at that point in the ordered refinement workflow. The multiplier is retained as a relative adjustment: it is not converted prematurely into a fixed relativity. A multiplier of 1 leaves a level unchanged, 1.10 increases it by 10%, and 0.95 decreases it by 5%.

The preferred input is a named numeric restrictions vector together with model_variable. Vector names identify the levels and values contain the fixed relativities or multipliers. This keeps every level directly beside its value. output_variable names the generated fixed tariff column and has a deterministic default.

Alternatively, supply the existing two-column data-frame form. Its first column name identifies the risk factor and its second column name identifies the generated tariff column. Both forms are fully supported; the named-vector form is preferred for concise specifications. The first column must contain character or factor levels, not numeric values. Convert numeric category codes explicitly with as.character() or factor(). Labels such as "1" and "2" are valid, including as names in c("1" = 0.90, "2" = 1.10). The supplied relativities or multipliers remain numeric; they are not category labels.

Actuarial interpretation

A fixed restriction table may contain all levels of the model variable, or only the levels that need a manual adjustment. If only a subset is supplied, the missing levels are automatically filled with their current effective relativities at that point in the refinement workflow. These may be the original fitted GLM relativities or values produced by preceding refinement steps. This makes it possible to change one level explicitly while fixing all other levels at their current values.

Levels that were not observed when the GLM was fitted can also be supplied. Such a level has no coefficient estimate from the model data. Its relativity is therefore an explicit tariff assumption, for example based on expert judgement, external experience or a planned extension of the tariff. Existing levels that are not supplied remain fixed at their fitted relativities.

With allow_new_levels = TRUE, which is the default, these new tariff levels are retained in the refinement metadata and subsequently shown by rating_table(). An informational message identifies every newly added level, its supplied relativity and the fact that it was not observed in the model data. Set allow_new_levels = FALSE when the restriction table should be checked strictly against the levels observed by the fitted model, for example to detect spelling errors in level names.

When a newly supplied level is written as a numeric interval, the function checks it against the existing interval levels. A warning is issued if the new interval overlaps the current classification. The level is still retained because overlapping labels may occasionally be intentional, but they do not form an unambiguous tariff partition. To replace an interval classification, first add the complete new classification as a separate column in the refinement data, use that column as the first column of restrictions, and identify the old model term with replaces.

A variable that is present in the refinement data but was not included in the fitted GLM can be added with allow_new_risk_factors = TRUE. In that case all observed levels must have a supplied relativity. The new factor is applied as a fixed tariff factor during refit(); its effects are not estimated from the model data. This can be appropriate when an external classification or expert assumption must be incorporated, such as a hail zone derived from geographic information.

allow_new_risk_factors does not create the portfolio variable itself. The refinement data must already contain a column assigning every observation to a level. This is required to apply the supplied relativities to individual records.

Setting allow_new_risk_factors = TRUE permits a new factor; it does not require one. For a factor already in the fitted model or introduced by an earlier refinement step, TRUE has no additional effect and does not itself produce a warning or message. This applies to both fixed restrictions and multipliers. Multipliers still require an existing relativity and cannot create a new factor, even when this permission is enabled. The flag does not request replacement of another model variable; use replaces for that.

Replacing an existing model variable

A new fixed tariff factor can either supplement the fitted GLM or replace an existing model variable. Supply replaces when the new factor represents an alternative tariff classification for an effect already present in the model. During refit(), the named existing term is removed and the supplied fixed relativities are inserted in its place. With replaces = NULL, the new factor is added alongside the existing model terms, which preserves the previous behaviour.

Supplying replaces is itself an explicit request to add the new risk factor, so allow_new_risk_factors = TRUE does not also need to be supplied. The replacement relationship is retained in the ordered refinement metadata and is shown by print(), summary() and audit_refinement(). This makes clear that the new factor substitutes for an earlier model effect rather than adding further multiplicative differentiation.

replaces is intentionally limited to a standalone main-effect term in the current refinement formula. A variable used in an interaction or transformed expression cannot be removed unambiguously through this argument. Such model structures should be revised explicitly before the refinement is prepared. This argument is therefore not a general-purpose facility for deleting model terms.

Updating an existing restriction

A later call to add_restriction() for the same risk factor and the same restricted model variable updates the restriction already stored in the refinement. Relativities supplied in the later call replace the previously stored values for those levels. Restrictions for levels that are not supplied again are retained.

The existing and new values are first combined and the resulting restriction table is then validated as one specification. This is useful when an actuarial assumption is revised during model refinement: only the affected levels need to be supplied again, while the remaining tariff assumptions stay unchanged. The restriction step keeps its original position in the workflow, so subsequent steps such as add_relativities() use the revised restricted coefficients.

The second column must retain the same name when an existing restriction is updated, because that name identifies the restricted model variable used by refit(). A message reports levels whose previously supplied relativity is changed.

Restricting a factor created by add_relativities()

An output_variable introduced by an earlier add_relativities() step is already part of the ordered refinement specification. It is therefore not treated as a new external risk factor and does not require allow_new_risk_factors = TRUE. add_restriction() identifies the preceding relativity step from its stored metadata and replaces the corresponding derived tariff effect during refit().

When only one level of such a refined variable is supplied, that level receives the new relativity and every other level is fixed at the relativity produced by add_relativities(). Mathematically, the resulting restriction therefore covers all current levels. Only the explicitly supplied level changes. This is useful when actuarial review supports a local adjustment but the remaining expert split should not be re-estimated.

Refinement order remains material. A restriction added after add_relativities() operates on the derived split relativities. A restriction added before add_relativities() instead changes the coefficient basis from which the split is derived.

Ordered fixed and multiplier restrictions

Restriction steps are evaluated in their recorded order. A multiplier after a fixed restriction scales that fixed relativity. A later fixed restriction replaces the complete effect at the selected levels and therefore supersedes earlier multipliers for the same risk factor. For example, fixing a level at 0.95 and then multiplying by 1.10 gives 1.045; applying those steps in the opposite order gives 0.95.

Multipliers require an active underlying relativity. They cannot create a new risk factor or level, and cannot be combined with replaces. Their values must be finite and strictly positive because they are applied on the log scale. The stored multiplier remains visible in refinement summaries and audit metadata.

Value

A rating_refinement object containing the stored restriction specification. The pricing GLM is not fitted again until refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), add_smoothing(), add_shrinkage(), add_rebasing(), add_relativities(), refit(), rating_table()

Examples

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

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

# Preferred form: each level is directly beside its relativity.
refined <- prepare_refinement(model, data = portfolio) |>
  add_restriction(
    restrictions = c(C = 1.10, D = 1.20),
    model_variable = "postal_area"
  )

# Postal area D was not observed in the portfolio. Its relativity is an
# explicit tariff assumption and becomes available after refitting.
refined_model <- refit(refined)
rating_table(refined_model, exposure = FALSE)

# The two-column data-frame form is also fully supported.
restrictions <- data.frame(
  postal_area = c("C", "D"),
  relativity = c(1.10, 1.20)
)
prepare_refinement(model, data = portfolio) |>
  add_restriction(restrictions)

# Multipliers remain relative to the underlying modelled relativities.
# TRUE is valid here: postal_area already exists, so the flag has no effect.
prepare_refinement(model, data = portfolio) |>
  add_restriction(
    restrictions = c(B = 1.10, C = 0.95),
    model_variable = "postal_area",
    restriction_type = "multiplier",
    allow_new_risk_factors = TRUE
  ) |>
  refit()

# A factor absent from the fitted GLM can replace an existing model term.
# The portfolio must already assign every observation to a hail zone.
portfolio$hail_zone <- factor(c("low", "high", "low", "high", "low", "high"))
hail_restrictions <- data.frame(
  hail_zone = c("low", "high"),
  hail_relativity = c(1.00, 1.20)
)

prepare_refinement(model, data = portfolio) |>
  add_restriction(
    hail_restrictions,
    replaces = "postal_area"
  )
# During refit(), hail_zone replaces postal_area rather than supplementing it.

# Without `replaces`, a new fixed factor supplements the existing terms.
# A later actuarial review changes only the relativity for the low hail zone.
# The high-zone relativity remains 1.20 and the existing step is updated.
revised_hail_restrictions <- data.frame(
  hail_zone = "low",
  hail_relativity = 1.10
)

hail_refinement <- prepare_refinement(model, data = portfolio) |>
  add_restriction(
    hail_restrictions,
    allow_new_risk_factors = TRUE
  ) |>
  add_restriction(revised_hail_restrictions)

refit(hail_refinement)

---

Shrink categorical tariff relativities towards a common level

Description

Reduce differences between the relativities of one categorical risk factor before the refined GLM is fitted. add_shrinkage() combines each current relativity with a central level on the logarithmic scale. Extreme relativities move further in absolute terms, while their ordering is retained.

Usage

add_shrinkage(model, model_variable, credibility = 0.9, weights = NULL)

Arguments

model	A rating_refinement object created with prepare_refinement(). Shrinkage is applied to the current relativities at this point in the ordered refinement workflow.
model_variable	Character string naming the categorical risk factor to shrink. This may also identify a tariff factor created by an earlier add_relativities() step. After add_restriction(), use the first column of its restriction table; the second column is resolved internally.
credibility	Numeric scalar between 0 and 1. This is the weight given to the current risk-factor relativity. The remaining weight is assigned to the common centre. The default 0.9 retains 90 percent of the current logarithmic effect.
weights	NULL, "equal", or a character string naming a numeric, non-negative column in the refinement data. NULL derives the weighting basis from explicit model weights or a simple exposure offset. "equal" gives every level equal weight.

Details

Shrinkage can be used when the direction of a fitted risk-factor pattern is credible, but the difference between its highest and lowest relativities is considered too large for the available experience or the intended tariff. It is a structured actuarial adjustment rather than a new statistical fit.

For level $i$, the unnormalised adjusted relativity is

$\tilde{r}_i = \exp\{Z \log(r_i) + (1-Z)\log(c)\},$

where $r_i$ is the current relativity, $Z$ is credibility, and $c$ is the weighted geometric centre. A credibility of 1 leaves the relativities unchanged. A credibility of 0 removes the differences between levels.

The adjusted relativities are subsequently rescaled so that their weighted arithmetic mean equals the weighted arithmetic mean before shrinkage. With portfolio weights such as exposure or claim count, this prevents shrinkage itself from changing the weighted level of the risk factor. The final GLM refit may still change the intercept or other fitted quantities; use audit_refinement() to assess that combined portfolio effect.

Weight selection

weights = NULL first uses explicit GLM weights when these were supplied during model fitting. Otherwise, a single column in an offset of the form log(column) is used. This commonly selects claim count for a weighted severity GLM and exposure for a frequency or risk-premium GLM. If neither source is unambiguous, the function asks for an explicit choice.

Set weights to a column name to control the basis directly. For example, exposure is generally appropriate for frequency or risk-premium relativities, while claim count is generally appropriate for severity relativities. Set weights = "equal" to give every risk-factor level the same weight. In that case the equal-level mean is preserved, which does not necessarily preserve the level of the observed portfolio.

Interpretation

credibility is a user-supplied refinement parameter. It should not be interpreted as an automatically estimated Buhlmann or Buhlmann-Straub credibility factor. Its value should be supported by portfolio stability, validation over time and the intended degree of tariff differentiation. The selected value and weighting basis are retained in the refinement specification and shown by summary().

Following a restriction

When shrinkage follows add_restriction(), model_variable remains the first column of the restriction table: the categorical risk factor whose levels are being adjusted. The second column is a numeric implementation column containing the fixed relativities used during refit(); it is not a separate categorical risk factor. add_shrinkage() resolves that internal column automatically from the stored restriction metadata.

Value

A rating_refinement object containing an ordered shrinkage step. The returned object stores the original and adjusted relativities, level weights, inferred weight source and normalization information. The GLM is fitted only when refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), add_smoothing(), add_restriction(), add_rebasing(), add_relativities(), refit(), audit_refinement()

Examples

portfolio <- data.frame(
  claims = c(1, 2, 1, 3, 2, 4, 1, 5),
  exposure = c(1, 1, 1, 1, 2, 1, 1, 1),
  sector = factor(rep(c("Industry", "Office", "Retail", "Transport"), 2))
)

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

refinement <- prepare_refinement(model, data = portfolio) |>
  add_shrinkage(
    model_variable = "sector",
    credibility = 0.9,
    weights = "exposure"
  )

summary(refinement)
refined_model <- refit(refinement)
rating_table(refined_model)

# Use equal level weights explicitly when portfolio weighting is not wanted.
equal_level_refinement <- prepare_refinement(model, data = portfolio) |>
  add_shrinkage(
    model_variable = "sector",
    credibility = 0.8,
    weights = "equal"
  )

---

Smooth grouped tariff relativities in a refinement workflow

Description

Replace independently estimated relativities of an ordered, grouped model variable with a smooth tariff curve. This can reduce sampling variation between adjacent levels of risk factors such as age, vehicle age, insured value or bonus-malus years while retaining the broad effect estimated by the GLM.

Usage

add_smoothing(
  model,
  model_variable = NULL,
  source_variable = NULL,
  breaks,
  smoothing = "spline",
  k = NULL,
  degree = NULL,
  weights = NULL,
  tariff_class = NULL,
  rating_variable = NULL,
  x_cut = NULL,
  x_org = NULL
)

Arguments

model	Object of class rating_refinement, created with prepare_refinement(). A fitted GLM, including a model returned by refit(), is not accepted directly; retain and modify the corresponding refinement specification instead.
model_variable	Character string. Existing grouped or binned variable in the GLM. This is the model term that will be replaced by a smoothed tariff factor. The column must not contain missing values; remove or impute missing values before adding the smoothing step.
source_variable	Character string. Original numeric portfolio variable underlying model_variable. Its name is also used for the resulting smoothed tariff variable. The column must contain only finite, non-missing numeric values.
breaks	Numeric vector with the tariff segment boundaries to use after smoothing. These boundaries determine the final tariff segmentation, not the number of portfolio observations used to estimate the curve. Values must be finite, strictly increasing and cover every observed value of source_variable. A boundary may extend beyond the interval range represented by model_variable, for example to create a rounded final tariff class. This does not itself produce a message. A short message is shown only when a representative point of a new interval lies outside the fitted GLM range and its relativity therefore requires extrapolation. This argument is required.
smoothing	Character string selecting the smoothing method. Available values are "spline" (default), "poly", "gam", "increasing", "decreasing", "convex", "concave", "increasing_convex", "increasing_concave", "decreasing_convex" and "decreasing_concave". The former short SCOP codes remain accepted as compatibility aliases. See Details for the statistical interpretation and shape restrictions.
k	Optional single positive whole number. Basis dimension for smoothing methods "spline", "gam", "increasing", "decreasing", "convex", "concave" and the combined direction-curvature methods. It sets the maximum flexibility available to the smooth and is not necessarily equal to its estimated effective degrees of freedom. NULL uses the smaller of 10 and the number of unique grouped model points. At least three unique grouped values are required. The basis dimension cannot exceed the number of unique grouped covariate values available for fitting.
degree	Optional single whole number. Polynomial degree, used only by smoothing = "poly". The degree must be feasible for the number of unique grouped model points.
weights	Optional character string. Numeric volume column, usually exposure, used to weight the grouped GLM relativities during smoothing.
tariff_class, rating_variable	Deprecated. Use model_variable and source_variable instead.
x_cut, x_org	Deprecated. Use model_variable and source_variable instead.

Details

add_smoothing() stores a smoothing specification on a rating_refinement object. It does not alter the fitted GLM immediately. The smoothing is evaluated in the recorded step order and applied when refit() is called. The original GLM contains model_variable, usually a factor created by grouping a continuous risk factor. source_variable identifies the original numeric variable represented by those groups.

The smoother is estimated from the fitted GLM relativities at the midpoint of each model interval. Consequently, the amount of information available to the smoother is primarily determined by the number of grouped model levels, rather than by the number of individual portfolio records. Exposure or another volume measure can be supplied through weights so that model levels with more portfolio volume have greater influence on the fitted curve.

The fitted curve is evaluated using breaks and converted back to a grouped tariff variable. The original model term is replaced by that smoothed tariff variable during refitting.

Actuarial interpretation

Smoothing introduces a structural assumption: adjacent values of the source variable are expected to have related tariff effects. The selected method, basis dimension and breaks should therefore be assessed against exposure, observed experience, coefficient uncertainty and stability over time. A smooth curve should not be interpreted as evidence that the underlying risk relationship is itself known without uncertainty.

Smoothing methods

The available methods represent different assumptions about the shape of the tariff effect:

"spline"

The general-purpose default. Fits an unconstrained penalized cubic regression spline. It is suitable when the tariff effect should be smooth but no monotonicity or curvature restriction is justified.

"poly"

Fits a global polynomial through the grouped GLM relativities. degree determines its order. A low degree gives a compact parametric trend; higher degrees can follow more local variation but may oscillate, particularly near the boundaries.

"increasing" and "decreasing"

Fit monotone smooths. These methods constrain the tariff effect to move in one direction, without imposing how quickly its slope changes. They are often the most directly interpretable constrained specifications when actuarial reasoning supports a consistently increasing or decreasing risk effect.

"convex" and "concave"

Constrain curvature but not direction. For a convex curve, the slope increases as the source variable increases; for a concave curve, the slope decreases. A convex curve may therefore be U-shaped and a concave curve may be inverted U-shaped. These are advanced choices when curvature itself has a defensible interpretation.

"increasing_convex" and "increasing_concave"

Fit increasing curves with an additional curvature constraint. An increasing convex effect rises at an increasing rate, for example when upper-tail risk causes marginal cost to accelerate. An increasing concave effect rises at a decreasing rate and gradually flattens, for example when risk cost rises with insured value but less than proportionally.

"decreasing_convex" and "decreasing_concave"

Fit decreasing curves with an additional curvature constraint. A decreasing convex effect becomes less steep and tends to flatten. A decreasing concave effect becomes progressively steeper.

"gam"

Fits an unconstrained thin-plate regression spline with mgcv::gam(). It is mainly intended as a flexible reference when comparing the general spline and shape-constrained specifications. It does not impose the actuarial shape assumptions represented by the constrained methods.

The shape-constrained methods are fitted with scam::scam(). Monotonicity concerns the direction of the effect, whereas convexity and concavity concern how its slope changes. In most tariff applications, a directional assumption is easier to substantiate than a curvature assumption. A constraint should reflect an actuarial or pricing assumption that is defensible for the risk factor; it should not be selected solely because it produces a smoother visual result. The combined monotonicity and curvature methods are advanced specifications and are most appropriate when both assumptions can be supported independently.

The former short codes "mpi", "mpd", "cx", "cv", "micx", "micv", "mdcx" and "mdcv" remain accepted as compatibility aliases. New code should use the readable method names above. Both forms produce the same smoothing specification.

Basis dimension and polynomial degree

For "spline", "gam" and the shape-constrained methods, k specifies the basis dimension. It controls the maximum flexibility available to the smooth, but it is not the final effective degrees of freedom of the fitted curve. The estimated smoothing penalty can reduce the effective degrees of freedom below this maximum.

A smaller k restricts the curve to broad movements. A larger k permits more local variation, but requires enough distinct grouped covariate values and may be unstable when only a few tariff levels are available. If k is NULL, the function uses the smaller of 10 and the number of unique grouped model points. Spline, GAM and shape-constrained smoothing require at least three unique grouped values. The function checks this dimension before fitting and reports the observed number of unique values when the requested complexity is not feasible.

For "poly", degree has the corresponding complexity role. A polynomial of degree $d$ requires at least $d + 1$ unique grouped values. When degree is omitted, the existing behaviour uses the highest degree supported by the grouped model points. In practice, an explicit low degree is generally preferable when a stable global trend is intended.

degree is only accepted for smoothing = "poly". Conversely, k is only accepted for "spline", "gam" and the shape-constrained methods. This separation prevents a complexity argument from being supplied but silently ignored.

The deprecated smooth_coef() wrapper remains available for backwards compatibility.

Value

An object of class rating_refinement containing the stored smoothing specification. The pricing GLM is not fitted again until refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), edit_smoothing(), add_restriction(), add_shrinkage(), add_rebasing(), add_relativities(), refit(), risk_factor_gam()

Examples

## Not run: 
library(dplyr)

age_policyholder_frequency <- risk_factor_gam(
  data = MTPL,
  claim_count = "nclaims",
  risk_factor = "age_policyholder",
  exposure = "exposure"
)

age_segments_freq <- derive_tariff_segments(
  age_policyholder_frequency,
  segmentation_penalty = 10,
  seed = 1
)

dat <- MTPL |>
  add_tariff_segments(age_segments_freq, name = "age_policyholder_freq_cat") |>
  mutate(across(where(is.character), as.factor)) |>
  mutate(across(where(is.factor), ~ set_reference_level(., exposure)))

freq <- glm(
  nclaims ~ bm + age_policyholder_freq_cat,
  offset = log(exposure),
  family = poisson(),
  data = dat
)

sev <- glm(
  amount ~ zip,
  weights = nclaims,
  family = Gamma(link = "log"),
  data = dat |> filter(amount > 0)
)

premium_df <- dat |>
  add_prediction(freq, sev) |>
  mutate(premium = pred_nclaims_freq * pred_amount_sev)

burn_unrestricted <- glm(
  premium ~ zip + bm + age_policyholder_freq_cat,
  weights = exposure,
  family = Gamma(link = "log"),
  data = premium_df
)

ref <- prepare_refinement(burn_unrestricted) |>
  add_smoothing(
    model_variable = "age_policyholder_freq_cat",
    source_variable = "age_policyholder",
    breaks = c(seq(18, 93, 5), 95),
    smoothing = "spline",
    k = 6,
    weights = "exposure"
  )

# When the tariff effect must not decrease, use the readable constrained
# method name. The former value "mpi" remains accepted for compatibility.
increasing_ref <- prepare_refinement(burn_unrestricted) |>
  add_smoothing(
    model_variable = "age_policyholder_freq_cat",
    source_variable = "age_policyholder",
    breaks = c(seq(18, 93, 5), 95),
    smoothing = "increasing",
    k = 6,
    weights = "exposure"
  )

# Limit the visible range without changing the fitted smoothing curve.
autoplot(ref, x_max = 80, y_max = 1.5)


## End(Not run)

---

Add derived tariff segments to portfolio data

Description

Adds the tariff segments derived by derive_tariff_segments() as a new factor column to a portfolio data set. The stored boundaries are applied to the original continuous risk-factor column, so the result does not depend on the row order used when the GAM was fitted.

The helper does not re-estimate the GAM or derive new boundaries. It can be used after filtering or reordering the original portfolio and on new data whose risk-factor values remain within the range used to derive the segmentation.

Usage

add_tariff_segments(data, segments, name = NULL, overwrite = FALSE)

Arguments

data	A data frame to which the tariff segments should be added.
segments	Object of class "tariff_segments", produced by derive_tariff_segments(). Old "tariff_classes" objects are accepted for backward compatibility.
name	Character string. Name of the new output column. If NULL, the name is based on the risk factor name, for example "age_policyholder_segment".
overwrite	Logical. If FALSE, the function stops when name already exists in data.

Details

The risk-factor name and optional rounding increment are taken from segments. The risk-factor column in data must be numeric and contain only finite, non-missing values. Values outside the original segmentation range produce an error because their tariff treatment has not been supported by the fitted GAM. The resulting factor can be used in a GLM or retained as a candidate grouping for further actuarial review.

Value

A data frame with the derived tariff segment column added.

Author(s)

Martin Haringa

See Also

risk_factor_gam(), derive_tariff_segments()

Examples

## Not run: 
age_segments <- risk_factor_gam(
  MTPL,
  risk_factor = "age_policyholder",
  claim_count = "nclaims",
  exposure = "exposure"
) |>
  derive_tariff_segments()

MTPL |>
  add_tariff_segments(age_segments, name = "age_policyholder_segment")

## End(Not run)

---

Convert an object to a gt table

Description

Generic presentation helper. Methods return a gt table for objects where a formatted reporting table is more useful than another plot.

Create a formatted gt table from an object returned by assess_excess_threshold(). The original object remains a regular data.frame subclass; as_gt() is only used when a presentation table is needed for a report, tariff note or pricing review.

Format the coefficient-level result from bootstrap_coefficients() as a gt table. The table retains the requested link or exponentiated scale and shows how many bootstrap estimates were available for each coefficient.

Create a formatted gt table from an object returned by rating_table(). Risk factors are presented as row groups, while fitted model effects are shown as relativities or coefficients depending on the scale selected in rating_table().

Usage

as_gt(x, ...)

## S3 method for class 'threshold_assessment'
as_gt(
  x,
  claims = TRUE,
  loss = FALSE,
  premium = TRUE,
  locale = "nl-NL",
  loss_decimals = 0,
  premium_decimals = 0,
  ratio_decimals = 1,
  color_last_column = TRUE,
  title = NULL,
  subtitle = NULL,
  ...
)

## S3 method for class 'bootstrap_coefficients'
as_gt(
  x,
  scale = c("link", "exponentiated", "relativity"),
  confidence = 0.95,
  interval = c("percentile", "normal"),
  locale = "nl-NL",
  estimate_decimals = 3,
  success_decimals = 1,
  title = NULL,
  subtitle = NULL,
  ...
)

## S3 method for class 'rating_table'
as_gt(
  x,
  significance = NULL,
  show_effect_spanner = NULL,
  model_labels = NULL,
  locale = "nl-NL",
  estimate_decimals = 3,
  exposure_decimals = 0,
  missing_text = "–",
  title = NULL,
  subtitle = NULL,
  ...
)

Arguments

x	A supported object to convert, such as a threshold_assessment, rating_table, bootstrap_coefficients or refinement_audit object.
...	Arguments passed to methods.
claims	Logical. If TRUE, include claim-count columns.
loss	Logical. If TRUE, include loss amount columns. The default is FALSE to keep the threshold comparison compact.
premium	Logical. If TRUE, include risk-premium and premium-reduction columns.
locale	Character. Locale used to format model effects and exposure, for example "nl-NL" or "en-US".
loss_decimals, premium_decimals, ratio_decimals	Non-negative whole numbers controlling displayed decimals for loss amounts, premium amounts and percentage ratios.
color_last_column	Logical. If TRUE, color the final displayed column from white to yellow so the highest values stand out in the presentation table.
title	Optional character. Table title. If NULL, no title is added.
subtitle	Optional character. Table subtitle. If NULL, no subtitle is added.
scale	Character string. "link" reports coefficients on their fitted GLM scale. "exponentiated" applies exp() to every original and bootstrap coefficient. "relativity" is an alias for "exponentiated"; this interpretation is most direct for a log-link GLM. For a logit-link model, exponentiated coefficients are odds ratios rather than response probabilities.
confidence	Numeric scalar between 0 and 1 giving the confidence level.
interval	Character string. "percentile" uses empirical bootstrap quantiles. "normal" uses the original estimate plus or minus a normal quantile times the bootstrap standard error.
estimate_decimals	Non-negative whole number. Number of decimals shown for fitted coefficients or relativities.
success_decimals	Non-negative whole number. Number of decimals for the success-rate percentage.
significance	Optional logical. If NULL, use the significance setting stored on x. If TRUE, append the stored significance stars to the model effects and add the significance-level note. If FALSE, show fitted effects without stars.
show_effect_spanner	Optional logical. If NULL, show the "Relativities" or "Coefficients" spanner when multiple models are present and omit it for a single model. Use TRUE or FALSE to override this behaviour.
model_labels	Optional character vector with display labels for the fitted models. By default, each model object name is used unchanged. An unnamed vector is matched to the model columns in their existing order. A named vector can map model object names to labels, for example c(freq = "Frequency", sev = "Severity").
exposure_decimals	Non-negative whole number. Number of decimals shown for the exposure column, when available.
missing_text	Single character string used to display missing values. The default is an en dash ("\\u2013") so structural missing values, such as exposure for the intercept, are visually distinct from observed zero values.

Details

The first column of a rating_table identifies the model risk factor. as_gt() uses this column as groupname_col and sets row_group_as_column = TRUE. Levels belonging to the same risk factor are therefore kept together in a compact format suitable for a tariff note, model review or technical appendix.

Risk-factor and level order are taken directly from rating_table(). Use its risk_factor_order, level_order, numeric_level_order, reference_first and order_model arguments to determine the order before formatting the table.

With significance = TRUE, significance stars are appended to the fitted effects and the significance levels are shown below the table. This requires an object originally created with rating_table(significance = TRUE), because p-value information is deliberately not retained when significance is disabled during table construction. Significance stars are a statistical diagnostic and should be interpreted together with exposure, effect size, model stability and actuarial relevance.

In the underlying rating_table, estimates and significance indicators are stored in separate ⁠est_*⁠ and ⁠signif_*⁠ columns. as_gt() merges each pair only for display. The estimates therefore remain numeric in the source object, including when several models are presented in one table.

Value

A gt_tbl object for supported methods.

Author(s)

Martin Haringa

Examples

portfolio <- data.frame(
  policy_id = 1:10,
  sector = rep(c("Industry", "Retail"), each = 5),
  claim_count = c(
    0, 1, 1, 1, 1,
    0, 1, 1, 1, 1
  ),
  claim_amount = c(
    0, 25000, 120000, 50000, 175000,
    0, 40000, 90000, 150000, 300000
  ),
  policy_years = rep(1, 10)
)

thresholds <- assess_excess_threshold(
  data = portfolio,
  claim_amount = "claim_amount",
  thresholds = c(25000, 50000, 100000, 150000),
  exposure = "policy_years",
  group = "sector",
  claim_count = "claim_count"
)

if (requireNamespace("gt", quietly = TRUE)) {
  as_gt(thresholds)
}

portfolio <- MTPL
portfolio$zip <- as.factor(portfolio$zip)

frequency_model <- glm(
  nclaims ~ bm + zip + offset(log(exposure)),
  family = poisson(),
  data = portfolio
)

fitted_tariff <- rating_table(
  frequency_model,
  model_data = portfolio,
  exposure = "exposure",
  significance = TRUE
)

if (requireNamespace("gt", quietly = TRUE)) {
  as_gt(fitted_tariff)
  as_gt(fitted_tariff, model_labels = "Frequency model")
  as_gt(fitted_tariff, significance = FALSE, locale = "en-US")
}

---

Assess possible excess-loss thresholds

Description

Compare candidate thresholds for capped severity and large-loss pricing work.

assess_excess_threshold() is a diagnostic helper. It does not choose a threshold automatically. It shows how many claims, how many records contain claim amounts above candidate thresholds, how much historical claim cost sits above those thresholds, and how much risk premium would remain after capping claims at each threshold.

The function is intended for portfolio-level data as well as claim-level data. Portfolio-level data can include policies without claims, for example rows where claim_count = 0 and the claim amount is zero. Use this before redistribute_excess_loss() to understand the effect of the threshold on the portfolio. The output is useful for tariff notes, pricing reviews and governance discussions around adjusted severity models.

Usage

assess_excess_threshold(
  data,
  claim_amount,
  thresholds,
  exposure = NULL,
  group = NULL,
  claim_count = NULL
)

Arguments

data	A data.frame with portfolio-level or claim-level observations. Portfolio-level data can include policies without claims.
claim_amount	Character string. Claim amount column.
thresholds	Numeric vector of candidate thresholds.
exposure	Optional character string. Exposure column. If supplied, risk premium before and after capping is calculated. The output column keeps this original name. If NULL, every record is counted as one exposure unit and the output contains an exposure column.
group	Optional character string. Grouping column used to assess thresholds by segment. The output column keeps this original name. If NULL, no grouping column is added.
claim_count	Optional character string. Claim-count column. If supplied, n_claims is calculated as the sum of this column. If NULL, records with claim_amount > 0 are counted as one claim and records with claim_amount == 0 as zero claims.

Details

The output can be used for two common follow-up analyses. First, aggregate the threshold assessment to portfolio level to calculate the average additional risk premium required to finance the excess layer. Second, after selecting a threshold, compare groups to see which parts of the portfolio benefit most from the excess protection.

Value

A data.frame with class "threshold_assessment" and columns:

group column

The original grouping column, such as sector, if group is supplied. This is the first column when grouping is used.

threshold

The excess threshold being assessed. Thresholds are shown in the same order as supplied in the thresholds argument.

exposure column

The original exposure column, such as policy_years, if exposure is supplied. If exposure = NULL, this column is named exposure and counts records.

n_claims

Total number of claims, calculated from claim_count or inferred from claim_amount > 0.

n_excess_records

Number of records with claim_amount > threshold. This counts records, not individual claims.

total_loss

Total claim amount before applying the threshold.

capped_loss

Total claim amount retained below or at the threshold.

excess_loss

Total claim amount above the threshold.

pure_premium_before

Risk premium before capping: total_loss / exposure.

pure_premium_after

Risk premium after capping: capped_loss / exposure.

premium_reduction

pure_premium_before - pure_premium_after, equivalent to excess_loss / exposure. This is positive when applying the threshold reduces the retained risk premium.

premium_reduction_ratio

premium_reduction / pure_premium_before. This is between 0 and 1 when pure_premium_before > 0; if pure_premium_before == 0, it is defined as 0.

Author(s)

Martin Haringa

Examples

portfolio <- data.frame(
  policy_id = 1:10,
  sector = rep(c("Industry", "Retail"), each = 5),
  claim_count = c(
    0, 1, 1, 1, 1,
    0, 1, 1, 1, 1
  ),
  claim_amount = c(
    0, 25000, 120000, 50000, 175000,
    0, 40000, 90000, 150000, 300000
  ),
  policy_years = rep(1, 10)
)

thresholds <- assess_excess_threshold(
  data = portfolio,
  claim_amount = "claim_amount",
  thresholds = c(25000, 50000, 100000, 150000),
  exposure = "policy_years",
  group = "sector",
  claim_count = "claim_count"
)

thresholds
if (requireNamespace("gt", quietly = TRUE)) {
  as_gt(thresholds)
}

# Calculate the average additional risk premium required to finance
# the excess portion of the claims.
thresholds |>
  dplyr::summarise(
    policy_years = sum(policy_years),
    excess_loss = sum(excess_loss),
    capped_loss = sum(capped_loss),
    extra_risk_premium = excess_loss / policy_years,
    risk_premium_increase = excess_loss / capped_loss,
    .by = "threshold"
  )

# After selecting a threshold, compare which groups benefit most
# from the excess protection.
selected_threshold <- thresholds |>
  dplyr::filter(threshold == 100000) |>
  dplyr::select(
    sector,
    threshold,
    policy_years,
    n_claims,
    n_excess_records,
    premium_reduction,
    premium_reduction_ratio
  ) |>
  dplyr::arrange(dplyr::desc(premium_reduction_ratio))

selected_threshold

# If claim_count is omitted, records with positive claim amounts are counted.
assess_excess_threshold(
  data = portfolio,
  claim_amount = "claim_amount",
  thresholds = 100000,
  exposure = "policy_years",
  group = "sector"
)

---

Audit the effect of a fitted model refinement

Description

Compare an unrestricted GLM with the model returned by refit() on the same observed portfolio. The audit records the refinement specification and quantifies how the fitted response or fitted rate changes for the portfolio and for each final tariff-factor level.

Usage

audit_refinement(
  object,
  exposure = NULL,
  risk_factors = NULL,
  scale = c("auto", "response", "per_exposure"),
  metric = NULL
)

Arguments

object	A fitted model returned by refit(). Ordinary GLMs do not contain the stored baseline and refinement metadata required for the comparison.
exposure	Optional character string naming the exposure column. With scale = "auto", the function attempts to infer a single exposure column from the original model offset. Supply this argument explicitly when that interpretation is ambiguous.
risk_factors	Optional character vector identifying final tariff factors for the level comparison. If NULL, the final factors reported by rating_table() and available in rating_grid() are used.
scale	Character string. "per_exposure" compares fitted values per unit of exposure. "response" compares predictions on the response scale. "auto" selects "per_exposure" when one exposure variable can be identified from the model offset and otherwise selects "response".
metric	Optional character string used to describe the audited measure, for example "risk_premium", "frequency" or "average_severity". If NULL, the audit uses "fitted_rate" or "fitted_response".

Details

Direct coefficient comparisons are generally not a sufficient refinement audit. A coefficient can change because the intercept or another model term changes, while the combined fitted value for a policy remains similar. audit_refinement() therefore compares predictions from the original and refined models on common observed model-point combinations.

The model points are obtained with rating_grid(). Portfolio and level results are weighted by the number of records or, when supplied, by exposure. With scale = "per_exposure", predictions that include an exposure offset are divided by total exposure after aggregation. This gives an exposure-weighted fitted rate rather than an unweighted average over unique model points.

The resulting measure should be named according to the model being audited. For a frequency model it is normally a fitted frequency; for a severity model it is a fitted average severity; and for a direct risk-premium model it can be labelled "risk_premium". A complete risk-premium comparison requires either a direct risk-premium model or an explicit combination of frequency and severity predictions.

Value

An object of class refinement_audit. The object contains package and model metadata, the ordered refinement steps, portfolio-level results, results by risk factor and level, and the model points used in the calculation. Use summary.refinement_audit() for a concise audit report, as.data.frame() for the level results and as_gt() for a formatted table.

Author(s)

Martin Haringa

See Also

prepare_refinement(), refit(), rating_grid(), summary.rating_refinement()

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"))
)

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

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

summary(refinement)

refined_model <- refit(refinement)
audit <- audit_refinement(
  refined_model,
  exposure = "exposure",
  metric = "frequency"
)

summary(audit)
as.data.frame(audit)

if (requireNamespace("gt", quietly = TRUE)) {
  as_gt(audit)
}

---

Plot the resampled performance distribution

Description

Display the empirical distribution of resampled RMSE values from bootstrap_performance(). The histogram shows the observed resampling distribution, while the density curve provides a smooth visual summary.

Usage

## S3 method for class 'bootstrap_performance'
autoplot(object, fill = "#E6E6E6", color = NA, ...)

Arguments

object	An object of class "bootstrap_performance", produced by bootstrap_performance().
fill	Fill colour of the histogram bars. Default is "#E6E6E6".
color	Border colour of the histogram bars. Default is NA, which removes bar borders.
...	Currently unused.

Details

The dashed orange line marks the RMSE of the original fitted model. The dotted grey lines mark the 2.5 and 97.5 percent empirical quantiles of the resampled values when these can be calculated. Their distance provides a practical indication of sampling variability; it is not a formal prediction interval for future portfolio performance.

Value

A ggplot2::ggplot object.

Author(s)

Martin Haringa

See Also

bootstrap_performance(), rmse()

Examples

## Not run: 
mod1 <- glm(nclaims ~ age_policyholder, data = MTPL,
            offset = log(exposure), family = poisson())
x <- bootstrap_performance(mod1, MTPL, n_resamples = 100,
                           show_progress = FALSE)
autoplot(x)

## End(Not run)

---

Inspect simulation-based residual uniformity

Description

Plot the scaled residuals returned by check_residuals() against their theoretical uniform quantiles. Systematic departures from the diagonal can indicate remaining structure, distributional mismatch or influential observations in a fitted pricing model.

Usage

## S3 method for class 'check_residuals'
autoplot(object, show_message = TRUE, max_points = 1000, ...)

Arguments

object	An object produced by check_residuals().
show_message	Logical. If TRUE, print a concise interpretation of the Kolmogorov-Smirnov p-value.
max_points	Maximum number of QQ-plot points to display. If the residual check contains more points, an evenly spaced subset is shown. Use Inf to display all points.
...	Currently unused.

Details

The subtitle reports the uniformity-test p-value stored in object. This p-value is a diagnostic signal rather than a stand-alone model acceptance criterion. The shape and location of deviations should be assessed together with exposure, fitted values and relevant risk-factor levels.

Reducing max_points affects only the displayed QQ points; it does not change the residual calculation or the reported test.

Value

A ggplot2::ggplot object.

Author(s)

Martin Haringa

See Also

check_residuals(), check_overdispersion()

---

Plot observed portfolio experience by risk factor

Description

Visualise the exposure and observed actuarial metrics calculated by factor_analysis(). The plots support assessment of portfolio composition, observed frequency, severity, risk premium and loss ratio across risk-factor levels.

The observed patterns are descriptive. They do not adjust for correlations with other risk factors and should therefore not be interpreted as multivariate tariff relativities.

Usage

## S3 method for class 'factor_analysis'
autoplot(
  object,
  metrics = NULL,
  ncol = 1,
  legend_position = c("right", "bottom", "top", "left", "none"),
  show_exposure = TRUE,
  show_exposure_labels = TRUE,
  sort_by_exposure = FALSE,
  level_order = NULL,
  decimal_mark = ",",
  line_color = NULL,
  bar_fill = NULL,
  abbreviate_labels = TRUE,
  label_width = 20,
  label_abbreviations = NULL,
  flip_bars = FALSE,
  show_total = FALSE,
  total_color = NULL,
  total_name = NULL,
  rotate_angle = NULL,
  custom_theme = NULL,
  remove_underscores = FALSE,
  compact_x_axis = TRUE,
  show_plots = NULL,
  background = NULL,
  labels = NULL,
  sort = NULL,
  sort_manual = NULL,
  dec.mark = NULL,
  color = NULL,
  color_bg = NULL,
  coord_flip = NULL,
  remove_x_elements = NULL,
  ...
)

Arguments

object	A factor_analysis or univariate object produced by factor_analysis() or univariate().
metrics	Numeric or character vector specifying which metrics to plot (default is all available metrics). The numeric positions are: 1. Frequency (nclaims / exposure) 2. Average severity (claim_amount / claim_count) 3. Risk premium (claim_amount / exposure) 4. Loss ratio (claim_amount / premium) 5. Average premium (premium / exposure) 6. Exposure 7. Severity 8. Number of claims 9. Premium Character values can be "frequency", "average_severity", "risk_premium", "loss_ratio", "average_premium", "exposure", "claim_amount", "claim_count", and "premium".
ncol	Positive whole number. Number of columns in the plot composition.
legend_position	Character string specifying the legend position. Supported values are "right", "bottom", "top", "left" and "none". A legend is present only when the factor_analysis object was created with group_by, because the resulting group-specific series are distinguished by colour. Without group_by, colours are fixed plot styles and no legend is drawn; in that case this argument has no visible effect.
show_exposure	Show exposure as background bars behind line plots (default = TRUE).
show_exposure_labels	Show labels with the exposure bars (default = TRUE).
sort_by_exposure	Sort risk factor levels into descending order by exposure (default = FALSE).
level_order	Custom order for risk factor levels; character vector (default = NULL).
decimal_mark	Decimal mark; defaults to ",".
line_color	Optional override for line/point color. If NULL (default), colors are taken from the internal palette. If specified, the chosen color is applied to all line-based plots.
bar_fill	Optional override for background bar color. If NULL (default), the background color is taken from the internal palette. If specified, the chosen color is applied to all background bars.
abbreviate_labels	Logical. If TRUE, long risk-factor level labels are shortened to label_width characters. A shortened label ends in one period; for example, "Bouwnijverheid" becomes "Bouwn." when label_width = 6. Only the displayed axis labels are changed.
label_width	Positive whole number of at least 2. Maximum number of characters in automatically shortened level labels.
label_abbreviations	Optional named character vector with explicit display labels, for example c("Bouwnijverheid" = "Bouwn.", "Onroerend goed" = "Onr. goed"). Explicit labels take precedence over automatic shortening.
flip_bars	Logical. If TRUE, flip cartesian coordinates for bar plots (metrics 6 to 9). This option does not affect the line-based plots for metrics 1 to 5.
show_total	Show line for total if by is used (default = FALSE).
total_color	Color for total line (default = "black").
total_name	Legend name for total line (default = NULL).
rotate_angle	Numeric value for angle of labels on the x-axis (degrees).
custom_theme	List with customized theme options.
remove_underscores	Logical; remove underscores from labels (default = FALSE).
compact_x_axis	Logical. When TRUE and ncol == 1, x-axis components are removed from all plots except the last one. The following elements are suppressed: axis.title.x axis.text.x axis.ticks.x This prevents duplicated x-axes in vertically stacked patchwork plots. Defaults to TRUE.
show_plots	Deprecated. Use metrics instead.
background	Deprecated alias for show_exposure.
labels	Deprecated alias for show_exposure_labels.
sort	Deprecated alias for sort_by_exposure.
sort_manual	Deprecated alias for level_order.
dec.mark	Deprecated alias for decimal_mark.
color	Deprecated alias for line_color.
color_bg	Deprecated alias for bar_fill.
coord_flip	Deprecated alias for flip_bars.
remove_x_elements	Deprecated alias for compact_x_axis.
...	Currently unused.

Details

For rate-based metrics, exposure can be shown as background bars so that observed level differences can be interpreted together with portfolio volume. Levels with little exposure or few claims can produce volatile observed metrics and should be assessed accordingly.

When the factor analysis contains one or more by variables, separate observed series are shown. show_total = TRUE adds the aggregate portfolio series for comparison. Sorting and manual level ordering affect only the presentation; the underlying summaries are unchanged.

A rate or ratio is not shown for a risk-factor level when its denominator is zero or missing. For example, average severity is undefined when claim count is zero, and loss ratio is undefined when premium is zero. autoplot() gives one combined warning identifying the affected metrics and levels. Other valid metrics and exposure information remain in the figure.

Value

A patchwork composition containing the requested ggplot panels.

Author(s)

Marc Haine, Martin Haringa

See Also

factor_analysis(), add_portfolio_experience()

Examples

# Plot observed frequency and risk premium
x <- factor_analysis(MTPL2,
                     x = "area",
                     severity = "amount",
                     nclaims = "nclaims",
                     exposure = "exposure")
autoplot(x, metrics = c("frequency", "risk_premium"))

---

Inspect a model refinement step

Description

Visualise one stored step of a rating_refinement specification before fitting the revised GLM with refit(). The plot compares the original fitted tariff effect with the smoothing, restriction, shrinkage, rebasing or sublevel relativity specification produced by the selected step.

Usage

## S3 method for class 'rating_refinement'
autoplot(
  object,
  variable = NULL,
  step = NULL,
  x_max = NULL,
  y_max = NULL,
  show_initial_smoothing = FALSE,
  show_segments = TRUE,
  remove_underscores = FALSE,
  rotate_angle = NULL,
  custom_theme = NULL,
  ...
)

Arguments

object	Object of class rating_refinement.
variable	Optional character string identifying the model or derived variable whose refinement step should be shown. For one smoothing lineage, the most recent smoothing or edit step is selected. An error is returned when no step matches or when matches belong to different refinements.
step	Optional positive integer identifying a step in the stored refinement sequence. This takes precedence over variable.
x_max	Optional single finite numeric value. Maximum value displayed on the x-axis of a smoothing plot. This changes only the visible plotting range; it does not remove observations, alter the fitted smoothing curve or affect refit(). It is useful when a small number of extreme values would otherwise compress the range containing most portfolio risks. For example, use x_max = 1e7 to display insured values up to 10 million. This argument is only available for smoothing steps.
y_max	Optional single finite numeric value. Maximum relativity displayed on the y-axis of a smoothing plot. Like x_max, this changes only the visible plotting range and does not alter the smoothing fit, refinement data or refit(). This argument is only available for smoothing steps.
show_initial_smoothing	Logical. For a smoothing or smoothing-edit plot, whether to overlay the initial curve produced by the corresponding add_smoothing() step. The other smoothing line shows the cumulative curve at the selected step. Default is FALSE. This argument does not alter the refinement specification or refit().
show_segments	Logical. For a smoothing or smoothing-edit relativity plot, whether to show the horizontal relativities and boundary points of the new tariff segments. Set this to FALSE to inspect the continuous smoothing curve without the segmented tariff representation. The original fitted model effects remain visible. Default is TRUE.
remove_underscores	Logical; if TRUE, underscores are replaced by spaces in the x-axis label. Default is FALSE.
rotate_angle	Optional numeric value for the angle of x-axis labels.
custom_theme	Optional list passed to ggplot2::theme().
...	Additional plotting arguments passed to ggplot2 geoms.

Details

Refinement steps are evaluated in their stored order up to and including the selected step. The plot is a diagnostic preview: it does not refit the GLM and does not modify the refinement specification.

If step is supplied, that position in the refinement sequence is shown. If only variable is supplied, the most recent step in one smoothing lineage is used. For other refinement types, exactly one stored step must match that variable. When neither is supplied, the object must contain exactly one refinement step. Otherwise the function asks the user to select a step explicitly.

Each edit_smoothing() call is stored as a separate workflow step. Selecting such a step shows the cumulative smoothing after all preceding edits up to that point. Set show_initial_smoothing = TRUE to add the curve produced by the corresponding add_smoothing() step before any edits were applied.

Actuarial interpretation

The plot supports review of the proposed tariff structure before estimation. It can be used to assess the local shape and magnitude of a smoothing curve, the effect of fixed relativities, and the differentiation introduced within a broader GLM level. This visual assessment does not by itself establish statistical adequacy; claim volume, exposure, stability over time and model diagnostics should also be considered.

For a sublevel split created by add_relativities(), the original parent level is shown as a horizontal segment across its child levels. This makes the parent GLM effect and the proposed within-level differentiation directly comparable.

Value

A ggplot2 object.

Author(s)

Martin Haringa

See Also

prepare_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", "C", "A", "B", "C"))
)

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

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

autoplot(refinement)

---

Compare fitted risk-factor effects graphically

Description

Plot the coefficients or relativities stored in a rating_table() object by risk factor. Multiple fitted models can be compared, exposure can be shown as background bars, and observed portfolio experience attached with add_portfolio_experience() can be added as a separate line.

Usage

## S3 method for class 'rating_table'
autoplot(
  object,
  risk_factors = NULL,
  metric = NULL,
  ncol = 1,
  legend_position = c("auto", "right", "bottom", "top", "left", "none"),
  show_exposure_labels = TRUE,
  decimal_mark = ",",
  y_label = "Relativity",
  bar_fill = NULL,
  model_color = NULL,
  use_linetype = FALSE,
  abbreviate_labels = TRUE,
  label_width = 20,
  label_abbreviations = NULL,
  rotate_angle = NULL,
  custom_theme = NULL,
  remove_underscores = FALSE,
  labels = NULL,
  dec.mark = NULL,
  ylab = NULL,
  fill = NULL,
  color = NULL,
  linetype = NULL,
  ...
)

Arguments

object	A "rating_table" object returned by rating_table().
risk_factors	Optional character vector specifying the risk factors to plot. If NULL, all available risk factors are shown.
metric	Optional character string. Observed-experience metric to plot when observed experience has been attached with add_portfolio_experience(). Common choices are "frequency", "severity"/"average_severity" and "risk_premium".
ncol	Positive integer specifying the number of columns in the patchwork layout.
legend_position	Character string specifying the legend position. The default, "auto", hides the legend when only one fitted model is shown and no observed-experience line is present. It places the legend on the right when multiple fitted models or an observed-experience comparison are shown. Use "right", "bottom", "top", "left" or "none" to override this behaviour.
show_exposure_labels	Logical. If TRUE, print exposure values on the background bars.
decimal_mark	Character string, either "," or ".", controlling number labels.
y_label	Character string for the primary y-axis.
bar_fill	Optional colour for exposure bars. If NULL, the package palette is used.
model_color	Optional single colour overriding the model-line palette.
use_linetype	Logical. If TRUE, distinguish fitted models by line type as well as colour.
abbreviate_labels	Logical. If TRUE, long risk-factor level labels are shortened to label_width characters. A shortened label ends in one period; for example, "Bouwnijverheid" becomes "Bouwn." when label_width = 6. Only the displayed axis labels are changed.
label_width	Positive whole number of at least 2. Maximum number of characters in automatically shortened level labels.
label_abbreviations	Optional named character vector with explicit display labels, for example c("Bouwnijverheid" = "Bouwn.", "Onroerend goed" = "Onr. goed"). Explicit labels take precedence over automatic shortening.
rotate_angle	Optional numeric angle for risk-factor level labels.
custom_theme	Optional named list passed to ggplot2::theme().
remove_underscores	Logical. If TRUE, replace underscores with spaces in risk-factor axis labels.
labels	Deprecated alias for show_exposure_labels.
dec.mark	Deprecated alias for decimal_mark.
ylab	Deprecated alias for y_label.
fill	Deprecated alias for bar_fill.
color	Deprecated alias for model_color.
linetype	Deprecated alias for use_linetype.
...	Additional arguments reserved for method compatibility.

Details

Plot contents

One panel is produced for each selected risk factor. Model effects use the primary y-axis. When exposure is available, bars are rescaled to the plotting range and the original exposure scale is shown on the secondary y-axis. Panel and level order follow the input rating_table() object. This keeps the reference level and any explicit actuarial review order consistent between the data frame, as_gt() and the plot.

Observed experience is plotted only after it has been attached with add_portfolio_experience(). The selected metric is converted to the relative scale recorded in that object, using either the model reference level or the portfolio mean.

Actuarial interpretation

The plot supports comparison of fitted tariff effects, portfolio volume and unadjusted observed experience. Differences between the observed and modelled lines may indicate portfolio-mix effects, sparse levels, model smoothing or genuine lack of fit. The chart does not separate these explanations and should be reviewed together with claim counts, residual diagnostics and stability across periods.

When models are compared, the analyst should ensure that response definitions, link functions and relativity scales are sufficiently comparable. Exposure bars provide volume context but are not confidence intervals.

Value

A patchwork object containing one ggplot2 panel per selected risk factor.

Author(s)

Martin Haringa

See Also

rating_table(), add_portfolio_experience(), factor_analysis(), as_gt.rating_table()

Examples

portfolio <- MTPL
portfolio$zip <- as.factor(portfolio$zip)

frequency <- glm(
  nclaims ~ bm + zip + offset(log(exposure)),
  family = poisson(),
  data = portfolio
)

effects <- rating_table(
  frequency,
  model_data = portfolio,
  exposure = "exposure"
)

autoplot(effects, risk_factors = "zip", show_exposure_labels = FALSE)

---

Inspect smooth risk-factor effects and tariff-segment boundaries

Description

Plot the smooth effect estimated by risk_factor_gam() or inspect that same effect together with candidate boundaries returned by derive_tariff_segments(). Both methods use the same curve, confidence interval, observation and axis layers.

Usage

## S3 method for class 'tariff_segments'
autoplot(
  object,
  confidence = FALSE,
  color_gam = "steelblue",
  show_observations = FALSE,
  color_splits = "grey50",
  size_points = 1,
  color_points = "black",
  rotate_labels = FALSE,
  remove_outliers = NULL,
  conf_int = NULL,
  x_stepsize = NULL,
  show_segments = TRUE,
  ...
)

## S3 method for class 'riskfactor_gam'
autoplot(
  object,
  confidence = FALSE,
  color_gam = "steelblue",
  show_observations = FALSE,
  x_stepsize = NULL,
  size_points = 1,
  color_points = "black",
  rotate_labels = FALSE,
  remove_outliers = NULL,
  conf_int = NULL,
  ...
)

Arguments

object	An object returned by risk_factor_gam() or derive_tariff_segments().
confidence	Logical. If TRUE, add pointwise 95 percent confidence intervals where finite values are available.
color_gam	Colour for the fitted GAM line.
show_observations	Logical. If TRUE, add the aggregated observed experience used for fitting.
color_splits	Colour for segment boundaries. Used only for a tariff_segments object.
size_points	Numeric point size for observed experience.
color_points	Colour for observed experience.
rotate_labels	Logical. If TRUE, rotate x-axis labels by 45 degrees.
remove_outliers	Optional single numeric upper display limit for observed points. The fitted curve remains unchanged.
conf_int	Deprecated. Use confidence instead.
x_stepsize	Optional positive numeric step size for x-axis tick marks. If NULL, breaks are determined automatically.
show_segments	Logical. For a tariff_segments object, show the candidate segment boundaries when TRUE. Default is TRUE.
...	Additional arguments reserved for method compatibility.

Details

The fitted line is shown on its natural response scale: claim frequency, average severity or risk premium. Optional observed points represent portfolio experience aggregated at the continuous risk-factor values used for fitting.

For a tariff_segments object, vertical lines show the derived interval boundaries. These lines support actuarial review of where the continuous effect changes sufficiently to motivate a categorical tariff treatment. Set show_segments = FALSE to inspect only the underlying smooth curve.

Confidence intervals describe uncertainty in the fitted curve conditional on the selected GAM specification. They do not include uncertainty from model selection, omitted risk factors or future portfolio changes. Segment boundaries do not by themselves demonstrate that adjacent segments are statistically or commercially distinct. Exposure, claim volume, temporal stability and operational tariff constraints should be considered separately.

remove_outliers affects displayed observed points only. It does not remove observations from the fitted GAM or alter the prediction curve or segment boundaries.

Value

A ggplot2 object.

Author(s)

Martin Haringa

See Also

risk_factor_gam(), derive_tariff_segments(), add_tariff_segments()

Examples

## Not run: 
fit <- risk_factor_gam(
  MTPL,
  risk_factor = "age_policyholder",
  claim_count = "nclaims",
  exposure = "exposure"
)

# Inspect the continuous effect before deriving tariff segments.
autoplot(fit, confidence = TRUE, show_observations = TRUE)

segments <- derive_tariff_segments(
  fit,
  segmentation_penalty = 10,
  seed = 1
)

# Inspect the same effect with the candidate segment boundaries.
autoplot(segments, confidence = TRUE, show_observations = TRUE)
autoplot(segments, show_segments = FALSE)

## End(Not run)

---

Plot a fitted truncated severity distribution

Description

Creates a plot of the empirical cumulative distribution function (ECDF) of the observed truncated claim amounts together with the fitted truncated CDF.

The comparison assesses whether the fitted conditional severity distribution represents the shape of the observed claims within the same truncation interval.

Usage

## S3 method for class 'truncated_severity'
autoplot(
  object,
  ecdf_geom = c("point", "step"),
  x_label = NULL,
  y_label = NULL,
  y_limits = c(0, 1),
  x_limits = NULL,
  show_title = TRUE,
  digits = 2,
  truncation_digits = 2,
  geom_ecdf = NULL,
  xlab = NULL,
  ylab = NULL,
  ylim = NULL,
  xlim = NULL,
  print_title = NULL,
  print_dig = NULL,
  print_trunc = NULL,
  ...
)

Arguments

object	An object produced by fit_truncated_severity().
ecdf_geom	Character string indicating how to display the empirical CDF. Must be one of "point" or "step".
x_label	Title of the x axis. Defaults to "severity".
y_label	Title of the y axis. Defaults to "cumulative proportion".
y_limits	Numeric vector of length 2 specifying y-axis limits.
x_limits	Optional numeric vector of length 2 specifying x-axis limits.
show_title	Logical. If TRUE, print title and subtitle.
digits	Integer. Number of digits for parameter estimates in the subtitle.
truncation_digits	Integer. Number of digits used for truncation bounds.
geom_ecdf, xlab, ylab, ylim, xlim, print_title, print_dig, print_trunc	Deprecated argument names kept for backward compatibility.
...	Currently unused.

Details

The plot compares the empirical distribution of the observed, truncated claim severities with the fitted distribution conditional on the same truncation interval. This is a visual check of whether the selected severity distribution is plausible for the part of the portfolio that is actually observed.

Systematic separation between the empirical and fitted curves can indicate that the selected gamma or lognormal distribution does not adequately represent the observed severity shape. The plot does not assess the unobserved parts of the distribution outside the truncation bounds.

Value

A ggplot2 object.

Author(s)

Martin Haringa

See Also

fit_truncated_severity(), rlnormt(), rgammat()

---

Assess GLM coefficient stability by portfolio-row bootstrap

Description

Refit a GLM on repeated bootstrap samples of the estimation portfolio and retain the coefficient estimates from every successful refit. The resulting distribution describes how sensitive individual model coefficients are to sampling variation in the observed portfolio.

Usage

bootstrap_coefficients(
  object,
  n_resamples = 500,
  seed = NULL,
  show_progress = interactive()
)

Arguments

object	A fitted glm object. Refined GLMs are accepted when their estimation data can be recovered from the model object.
n_resamples	Positive whole number. Number of bootstrap samples. Default is 500.
seed	Optional single numeric seed for reproducible resampling.
show_progress	Logical. If TRUE, display a text progress bar.

Details

Each resample contains the same number of portfolio rows as the original estimation data and is drawn with replacement. The function recovers these data from object; a separate data argument is deliberately not required. Rows omitted during the original model fit are excluded so the resampling population remains aligned with the fitted GLM.

Original factor levels, the model formula, offsets and model weights are retained during refitting. A factor level may nevertheless be absent from a particular bootstrap sample. Its coefficient can then be non-estimable and is stored as NA for that replicate.

A failed or non-converged GLM refit does not stop the procedure. The failed replicate is recorded and the function continues. After resampling, an informative message reports how many requested refits produced usable model objects. summary.bootstrap_coefficients() reports the number of finite estimates separately for each coefficient.

Actuarial interpretation

The bootstrap distribution can identify tariff effects that are sensitive to the particular portfolio sample. Wide intervals, material bootstrap bias or a low number of estimable replicates often indicate sparse levels, correlated model terms or limited claim information. These diagnostics should be considered alongside exposure, claim counts, coefficient interpretation and stability across calendar periods.

The row bootstrap represents sampling variation in the observed estimation portfolio. It does not include future trend, parameter uncertainty caused by model selection, structural changes in portfolio composition or dependence between repeated records for the same policy. Where such dependence is material, a cluster-level bootstrap would require a different resampling design.

Value

An object of class "bootstrap_coefficients". It contains the original coefficients, a coefficient matrix with one row per requested resample, indicators for successful model fits, recorded failure messages, and the resampling settings. Use summary.bootstrap_coefficients() for a coefficient-level data frame and as_gt() for a formatted table.

Author(s)

Martin Haringa

See Also

summary.bootstrap_coefficients(), bootstrap_performance(), model_performance(), as_gt()

Examples

model <- glm(
  nclaims ~ age_policyholder + zip + offset(log(exposure)),
  family = poisson(),
  data = MTPL
)

## Not run: 
boot <- bootstrap_coefficients(
  model,
  n_resamples = 25,
  seed = 123,
  show_progress = FALSE
)

summary(boot, scale = "link")
summary(boot, scale = "exponentiated")
summary(boot, scale = "relativity")

if (requireNamespace("gt", quietly = TRUE)) {
  as_gt(boot, scale = "relativity")
}

## End(Not run)

---

Assess performance stability under repeated resampling

Description

Refit a pricing model on repeated samples and record the resulting response-scale prediction error. The distribution of RMSE values describes how sensitive model performance is to changes in the observed portfolio sample.

Usage

bootstrap_performance(
  model,
  data,
  n_resamples = 50,
  sample_fraction = 1,
  metric = "rmse",
  sampling = c("bootstrap", "split"),
  show_progress = TRUE,
  rmse_model = NULL,
  n = NULL,
  frac = NULL
)

Arguments

model	A fitted model object that can be updated on resampled data.
data	Data frame containing the model response and predictors.
n_resamples	Positive whole number. Number of resampling replicates. Default is 50.
sample_fraction	Fraction of the data used in the training sample. Must be in ⁠(0, 1]⁠. Default is 1.
metric	Character string. Performance metric to compute. Currently only "rmse" is supported.
sampling	Character string. Sampling scheme. "bootstrap" samples training rows with replacement and evaluates on out-of-bag rows when sample_fraction < 1. "split" samples training rows without replacement and evaluates on the remaining rows when sample_fraction < 1.
show_progress	Logical. Show a progress bar during resampling. Default is TRUE.
rmse_model	Optional finite numeric RMSE for the original fitted model. If NULL, it is calculated from model and data.
n, frac	Deprecated argument names. Use n_resamples and sample_fraction instead.

Details

Resampling design

With sampling = "bootstrap", training rows are sampled with replacement. With sampling = "split", they are sampled without replacement. When sample_fraction < 1, performance is evaluated on records not used for fitting. When sample_fraction = 1, performance is evaluated on the sampled training data and should be interpreted as an in-sample stability measure.

Character columns and factor columns are converted to factors with levels taken from the full input data before resampling. For factor variables used in the model, the training sample is augmented when needed so every observed level is represented at least once. This prevents prediction failures when a level is present in the evaluation data but absent from a particular training sample.

Actuarial interpretation

The resampled RMSE distribution is useful for comparing the stability of alternative frequency, severity or risk-premium specifications under repeated portfolio sampling. A narrow distribution indicates that the measured error is relatively insensitive to the sampled records; a wide distribution indicates greater sampling sensitivity.

This is an experience-based diagnostic and does not by itself represent the full uncertainty in future claims, trend, portfolio mix or model specification. Sparse factor levels are retained in training samples where necessary to avoid new-level prediction failures. That protection is useful operationally, but should be considered when interpreting the resampling design.

Value

An object of class "bootstrap_performance", which is a list with components:

rmse_bs

Numeric vector with n_resamples bootstrap RMSE values.

rmse_mod

Root mean squared error for the original fitted model.

metric

Metric name.

sampling

Sampling scheme.

Author(s)

Martin Haringa

See Also

rmse(), model_performance(), autoplot.bootstrap_performance()

Examples

## Not run: 
mod1 <- glm(nclaims ~ age_policyholder, data = MTPL,
            offset = log(exposure), family = poisson())

# Use all records
x <- bootstrap_performance(mod1, MTPL, n_resamples = 80,
                           show_progress = FALSE)
print(x)
autoplot(x)

# Use 80% of records and evaluate on the remaining records
x_frac <- bootstrap_performance(mod1, MTPL, n_resamples = 50,
                                sample_fraction = .8, sampling = "split",
                                show_progress = FALSE)
autoplot(x_frac)

## End(Not run)

---

Calibrate the overall level of a refined pricing model

Description

Adjust the overall prediction level of a fitted model returned by refit() without re-estimating its relative tariff structure. Calibration is a final model-level operation: all refinement decisions must be completed before calling calibrate_model().

Usage

calibrate_model(model, factor)

Arguments

model	A fitted refined GLM returned by refit(). It must inherit from refitrestricted or refitsmooth and use a log link.
factor	Positive finite numeric scalar. 1 retains the prediction level, values above 1 increase it, and values below 1 decrease it.

Details

For a refined GLM with a log link, calibration adds log(factor) to the intercept. Consequently, every response-scale prediction is multiplied by factor, while all non-intercept coefficients and tariff relativities remain unchanged.

The returned object is a copied, internally consistent fitted model. Its coefficients, linear predictors, fitted values, working residuals, deviance and AIC are updated to the calibrated level. The original refined model is not modified. Calibration metadata store the factor, log shift, original and calibrated intercept, creation time and call.

Refinement and calibration

Model refinement changes or constrains the relative tariff structure and is evaluated through prepare_refinement(), one or more ⁠add_*()⁠ operations, and refit(). Model calibration changes only the final overall level. A calibrated model cannot be calibrated again or used as the starting point for further refinement. Retain the rating_refinement specification and recalibrate a newly refitted model if earlier decisions need to be revised.

Value

A fitted glm that also inherits from calibrated_model. Attributes calibration_factor, calibration_original_intercept, calibration_intercept, calibration_log_shift, calibration_call and calibrated_at record the calibration.

See Also

refit(), rating_table(), add_prediction(), audit_refinement()

Examples

restrictions <- data.frame(
  zip = c("0", "1", "2", "3"),
  zip_restricted = c(0.90, 1.00, 1.05, 1.10)
)

mod_initial <- glm(
  nclaims ~ zip + offset(log(exposure)),
  family = poisson(),
  data = MTPL
)

mod_refined <- mod_initial |>
  prepare_refinement() |>
  add_restriction(restrictions) |>
  refit(intercept_only = TRUE)

mod_calibrated <- calibrate_model(mod_refined, factor = 1.05)

rating_table(mod_calibrated)

data_final <- mod_refined$data |>
  add_prediction(
    mod_calibrated,
    predictions = "net_risk_premium"
  )

---

Check overdispersion of a Poisson claim frequency model

Description

Tests whether a fitted Poisson GLM shows overdispersion using Pearson's chi-squared statistic.

Usage

check_overdispersion(object)

Arguments

object

A fitted model of class "glm" with family Poisson.

Details

In Poisson claim frequency models, the variance is assumed to be equal to the mean. A dispersion ratio above 1 indicates that the observed variation is larger than expected under that assumption. In pricing work this can be a useful diagnostic signal for omitted heterogeneity, clustering, outliers, or model misspecification. It does not automatically mean that the model is unusable.

• A dispersion ratio close to 1 is broadly consistent with the Poisson variance assumption.

• A dispersion ratio above 1 suggests overdispersion.

• A p-value below 0.05 indicates statistically significant overdispersion.

Value

An object of class "overdispersion_check" and "overdispersion", which is a list with elements:

pearson_chisq

Pearson's chi-squared statistic.

dispersion_ratio

Dispersion ratio, calculated as Pearson's chi-squared statistic divided by residual degrees of freedom.

residual_df

Residual degrees of freedom.

p_value

P-value from the chi-squared test.

For backwards compatibility the object also contains the aliases chisq, ratio, rdf, and p.

Author(s)

Martin Haringa

References

Bolker B. et al. (2017). GLMM FAQ See also: performance::check_overdispersion().

Examples

x <- glm(nclaims ~ area, offset = log(exposure),
         family = poisson(), data = MTPL2)
check_overdispersion(x)

---

Check simulation-based model residuals

Description

Checks whether a fitted model shows systematic residual deviations from the distribution implied by the model. The function uses simulation-based residuals from DHARMa::simulateResiduals(), which are especially useful for GLMs where classical residual plots can be hard to interpret.

Usage

check_residuals(object, n_simulations = 30)

Arguments

object	A fitted "glm" object supported by DHARMa::simulateResiduals().
n_simulations	Number of simulations used to generate residuals. Must be a positive whole number. The default of 30 is intended for a quick check. For a more stable final assessment, 250 to 1,000 simulations will often be more suitable. More simulations increase the calculation time.

Details

In insurance pricing, residual checks are used to assess whether a model is behaving consistently across the portfolio. For example, a Poisson frequency model may fit the average claim count well but still show structure in the residuals because of omitted rating factors, unmodelled heterogeneity, clustering, outliers, or an unsuitable distributional assumption.

DHARMa simulates new responses from the fitted model and compares the observed response with those simulations. The resulting scaled residuals are approximately uniformly distributed on ⁠[0, 1]⁠ when the model is correctly specified. This gives a common diagnostic scale for GLMs and related models, where raw residuals are otherwise difficult to compare across different fitted values, exposures, or expected claim amounts.

check_residuals() returns the scaled residuals, QQ-plot data, and a Kolmogorov-Smirnov p-value for a simple uniformity check. The p-value should be read as a diagnostic signal, not as a pricing decision rule. A low p-value indicates that the residual distribution differs from what the fitted model implies and that the model specification may need review.

A low p-value does not always mean that the model has an important pricing problem. In a large portfolio, even a small difference can produce a low p-value. The result should therefore be reviewed together with the QQ plot, the size of the difference and its relevance for the tariff.

Value

An object of class "residual_check" and "check_residuals", which is a list with:

qq_data

Data frame with theoretical quantiles (x) and observed scaled residuals (y).

scaled_residuals

Numeric vector of DHARMa scaled residuals.

p_value

P-value from a Kolmogorov-Smirnov test against uniform(0, 1).

For backwards compatibility the object also contains the aliases df and p.val.

Author(s)

Martin Haringa

References

Dunn, K. P., & Smyth, G. K. (1996). Randomized quantile residuals. JCGS, 5, 1–10.

Gelman, A., & Hill, J. (2006). Data analysis using regression and multilevel/hierarchical models. Cambridge University Press.

Hartig, F. (2020). DHARMa: Residual Diagnostics for Hierarchical (Multi-Level / Mixed) Regression Models. R package version 0.3.0. https://CRAN.R-project.org/package=DHARMa

Examples

## Not run: 
m1 <- glm(nclaims ~ area, offset = log(exposure),
          family = poisson(), data = MTPL2)
cr <- check_residuals(m1, n_simulations = 250)
autoplot(cr)

## End(Not run)

---

Derive candidate tariff segments from a smooth risk-factor effect

Description

Approximate the smooth effect estimated by risk_factor_gam() with intervals for a continuous risk factor. The resulting boundaries provide a candidate categorical representation that can be inspected before inclusion in a pricing GLM or tariff structure.

Usage

derive_tariff_segments(
  object,
  segmentation_penalty = 0,
  seed = 1,
  max_iterations = 10000,
  population_size = 200,
  complexity = NULL,
  alpha = NULL,
  niterations = NULL,
  ntrees = NULL
)

Arguments

object	A "risk_factor_gam" object returned by risk_factor_gam(). Legacy "riskfactor_gam" and "fitgam" classes are accepted for compatibility.
segmentation_penalty	Non-negative numeric penalty on additional tree splits. Larger values generally favour fewer tariff segments. The default 0 retains the historical behaviour and applies no explicit split penalty; it can therefore produce a relatively detailed candidate segmentation. There is no universal actuarial value: compare candidate penalties and assess the resulting volume and stability by segment.
seed	Single finite whole number used to reproduce the evolutionary search.
max_iterations	Positive integer. Maximum number of evolutionary search iterations. This is an advanced algorithm-control parameter.
population_size	Positive integer. Number of candidate trees maintained during the evolutionary search. This is an advanced algorithm-control parameter.
complexity	Deprecated. Use segmentation_penalty instead.
alpha	Deprecated. Use segmentation_penalty instead.
niterations	Deprecated. Use max_iterations instead.
ntrees	Deprecated. Use population_size instead.

Details

Method

An evolutionary regression tree from evtree::evtree() is fitted to the predicted GAM effect over the distinct observed risk-factor values. The tree therefore approximates the estimated univariate curve; it is not fitted directly to individual claim outcomes or portfolio loss. Internal tree split points are translated into interval boundaries. If no internal split is supported by the fitted search, one interval spanning the observed range is returned.

The method follows the data-driven binning approach described by Henckaerts et al. (2018). segmentation_penalty, population_size, max_iterations and seed control the stochastic search rather than an actuarial minimum-volume rule. Reusing the same inputs and seed makes the result reproducible.

Each distinct observed risk-factor value has equal influence when the tree approximates the fitted curve. Exposure, claim count or another actuarial weight is deliberately not applied again in this step. The relevant portfolio information has already influenced the curve through the statistical specification used by risk_factor_gam(), such as the exposure offset in a frequency model, claim-count weights in a severity model or exposure weights in a risk-premium model. Applying a second weight during segmentation would introduce an additional portfolio-distribution choice after the GAM has been estimated.

Exposure and claim count remain available through summary(). They are diagnostics for assessing the support and practical stability of candidate segments, but they do not influence the estimated boundaries.

Actuarial interpretation

The returned segments approximate the shape of the fitted univariate GAM; they are not automatically a final tariff classification. Before use in a multivariate model, the boundaries should be assessed against exposure and claim volume, stability across periods, operational rounding and the interaction with other risk factors. Particular care is required for boundaries in sparsely populated tails.

summary() reports the number of portfolio records, number of distinct risk-factor values and available exposure and claim volume within each proposed segment. These diagnostics support actuarial review but do not constitute an automatic acceptance rule. Minimum-volume requirements and operational rounding should be selected with reference to portfolio size, model purpose and governance standards.

A staged GLM refinement workflow

In practical pricing work, the candidate boundaries are often used to form an initial set of relatively broad model groups. The actuary reviews summary() and, where necessary, combines thinly populated segments or increases segmentation_penalty until the groups have sufficient exposure and claim information for stable estimation. The resulting factor can then be included in an unrestricted GLM.

This broad first-stage grouping avoids estimating a separate free GLM coefficient for every fine tariff interval when observations are unevenly distributed over the continuous risk factor. After fitting the GLM, add_smoothing() can use the broad model effect together with the original continuous variable to construct a regularised pattern over finer breaks. These finer breaks may reflect operational or commercial tariff boundaries, while their relativities remain linked through the smoothing specification rather than being estimated independently for every small segment.

The staged approach therefore separates statistical support from final tariff granularity: broad groups provide the information used by the GLM, while smoothing can translate that information into a finer and more regular tariff structure. Smoothing does not create additional observations, so the resulting classes should still be assessed for stability, extrapolation and commercial suitability.

The first and last boundaries equal the observed range used by the GAM. Applying the segmentation to new data outside that range results in an informative error rather than silent extrapolation.

Use autoplot.tariff_segments() to compare the smooth curve and boundaries. Use add_tariff_segments() to apply the resulting boundaries to portfolio data using the original continuous risk factor.

Value

A list of class "tariff_segments" with components:

gam_prediction

Data frame with the fitted GAM curve.

risk_factor

Name of the continuous risk factor.

model_type

Model type: "frequency", "severity", or "pure_premium".

classification_data

Data frame used to derive the segments.

risk_factor_values

Observed risk factor values in portfolio row order.

segment_boundaries

Numeric vector with segment boundaries.

assigned_segments

Factor with the tariff segment assigned to each observed risk factor value.

segment_summary

Data frame with portfolio counts, distinct risk-factor values and the observed response components for each candidate segment. Use summary() as the public interface for this table.

segmentation_penalty

Penalty applied to additional tree splits.

For backward compatibility, the old components prediction, x, model, data, x_obs, splits, class_boundaries, assigned_groups, and tariff_classes are also returned.

Author(s)

Martin Haringa

References

Antonio, K. and Valdez, E. A. (2012). Statistical concepts of a priori and a posteriori risk classification in insurance. Advances in Statistical Analysis, 96(2), 187–224. doi:10.1007/s10182-011-0152-7

Grubinger, T., Zeileis, A., and Pfeiffer, K.-P. (2014). evtree: Evolutionary learning of globally optimal classification and regression trees in R. Journal of Statistical Software, 61(1), 1–29. doi:10.18637/jss.v061.i01

Henckaerts, R., Antonio, K., Clijsters, M., & Verbelen, R. (2018). A data driven binning strategy for the construction of insurance tariff classes. Scandinavian Actuarial Journal, 2018(8), 681–705. doi:10.1080/03461238.2018.1429300

Wood, S.N. (2011). Fast stable restricted maximum likelihood and marginal likelihood estimation of semiparametric generalized linear models. JRSS B, 73(1), 3–36. doi:10.1111/j.1467-9868.2010.00749.x

See Also

risk_factor_gam(), autoplot.tariff_segments(), add_tariff_segments(), prepare_refinement(), add_smoothing()

Examples

## Not run: 
age_segments <- risk_factor_gam(
  MTPL,
  risk_factor = "age_policyholder",
  claim_count = "nclaims",
  exposure = "exposure"
) |>
  derive_tariff_segments(
    segmentation_penalty = 10,
    seed = 1
  )

autoplot(age_segments, show_observations = TRUE)
summary(age_segments)

MTPL |>
  add_tariff_segments(age_segments, name = "age_policyholder_segment")

## End(Not run)

---

Edit a smoothing curve in a refinement workflow

Description

Modify a specified interval of a smoothing curve previously added with add_smoothing(). Use a relative adjustment when the existing shape is broadly appropriate, or explicit values and control points when the curve should follow known targets.

Usage

edit_smoothing(
  model,
  model_variable = NULL,
  step = NULL,
  from = NULL,
  to = NULL,
  from_value = NULL,
  to_value = NULL,
  control_positions = NULL,
  control_values = NULL,
  adjustment = NULL,
  slope_adjustment = 1,
  transition = NULL,
  allow_extrapolation = FALSE,
  extrapolation_step = NULL
)

Arguments

model	Object of class rating_refinement, created with prepare_refinement() and containing an existing smoothing step. Ordinary and refitted GLMs are not accepted directly. Legacy smooth and restricted objects are still accepted for backwards compatibility.
model_variable	Character string. The model_variable of the smoothing step to edit. Required when more than one smoothing step exists and step is not supplied.
step	Optional numeric index of the original smoothing step or one of its later edit steps. In both cases, the new edit is linked to the same original smoothing and appended after the existing workflow steps.
from, to	Optional numeric values giving the start and end of the source-variable interval to modify. For adjustment, either value may be omitted to use the beginning or end of the available smoothing range. For slope_adjustment, from is the required anchor and to must remain NULL. Explicit target-value and control-point edits require both values.
from_value, to_value	Optional numeric values used to override the smoothed curve value at from and to.
control_positions, control_values	Optional numeric vectors of equal length. These define additional points that the edited smoothing curve should pass through.
adjustment	Optional positive numeric scalar applied multiplicatively to the current smoothing within the selected interval. 1.05 requests an increase of up to 5 percent and 0.95 a decrease of up to 5 percent. With two boundaries, the default transition anchors the multiplier at 1 at from and to; a one-sided edit is anchored only at the supplied boundary.
slope_adjustment	Positive numeric scalar controlling the change in slope after from. The default 1 leaves the curve unchanged. Values above 1 strengthen the remaining change; values between 0 and 1 flatten it. This argument is available only in edit_smoothing().
transition	Optional character string controlling how adjustment connects to the unchanged smoothing. NULL inherits the original smoothing specification. "linear" gives continuous linear transitions and "step" permits immediate jumps. Smoothing methods accepted by add_smoothing() can be supplied as explicit structural overrides.
allow_extrapolation	Logical. Whether edits may extend beyond the observed source-variable range.
extrapolation_step	Optional positive numeric scalar used to set the spacing of extra break points when extrapolation is allowed.

Details

edit_smoothing() appends a separate, ordered edit step to a rating_refinement object. It does not alter the fitted GLM immediately. Repeated calls are cumulative: every new edit starts from the smoothing produced by preceding edits to the same add_smoothing() step. The selected cumulative curve is applied when refit() is called.

Use model_variable or step to identify the smoothing to edit. step may identify either its original add_smoothing() step or a later edit belonging to that smoothing. The interval from from to to defines the part of the source-variable range that should be changed. With adjustment, either boundary may be omitted. Supplying only from edits the curve from that value to the end of the smoothing range; supplying only to edits it from the beginning of the range to that value. adjustment multiplies the current smoothing within the selected range. For example, adjustment = 1.05 requests an increase of up to 5 percent relative to the existing smoothing.

With two boundaries, the multiplier is anchored at 1 at from and to and reaches the requested adjustment near the middle. With only from, it is anchored at 1 at from and moves towards the requested adjustment at the end of the range. With only to, it starts at the requested adjustment and reconnects to 1 at to. These one-sided forms are useful for refining a lower or upper tail without introducing a jump at the supplied boundary.

By default, transition = NULL inherits the smoothing specification from the add_smoothing() step. The entry and exit are adapted to their opposite directions and join the unchanged curve continuously. "linear" uses continuous straight transitions. "step" applies the multiplier immediately at both boundaries and therefore permits deliberate jumps. Explicit shape-constrained transition names accepted by add_smoothing() can also be supplied. When a constrained transition is inherited or selected, the edited curve is checked for the corresponding monotonicity and curvature.

from_value and to_value instead prescribe curve values at the interval boundaries. control_positions and control_values add points that the edited curve should follow inside the interval. Relative adjustments and explicit target values cannot be combined in one edit_smoothing() call because they represent different actuarial instructions. They may be used in separate consecutive edits, which are then evaluated in their stored order.

slope_adjustment changes the remaining increase or decrease after from, while keeping the curve before that point unchanged. If $R(x)$ is the current smoothing and $a$ is from, the edited curve is $R(a) + s[R(x) - R(a)]$ for $x > a$, where $s$ is slope_adjustment. A value of 1.10 therefore makes the change after the anchor 10 percent stronger; 0.90 makes it 10 percent weaker. The curve is continuous at the anchor.

Each call applies one edit type: a relative adjustment, a slope_adjustment, or explicit target/control-point values. Apply multiple changes in consecutive calls so that every actuarial intervention remains a separate, inspectable refinement step.

Actuarial interpretation

The edited interval is an explicit tariff assumption layered on the statistically fitted smoothing curve. It should be supported by an actuarial rationale and reviewed against exposure, observed experience and the continuity of adjacent segments. The edit does not add information to sparse parts of the portfolio and should not be interpreted as a new model estimate.

Keep the rating_refinement object, call refit() to assess the current specification, edit that same refinement object, and call refit() again. The previously fitted GLM remains unchanged. This retains the order and content of manual adjustments as part of the reproducible refinement specification.

Value

A rating_refinement object with a separate smoothing-edit step appended to the ordered specification. The pricing GLM is not fitted again until refit() is called.

Author(s)

Martin Haringa

See Also

prepare_refinement(), add_smoothing(), add_restriction(), add_shrinkage(), add_rebasing(), add_relativities(), refit()

Examples

set.seed(42)
driver_age <- rep(seq(20, 59), each = 4)
exposure <- rep(1, length(driver_age))
age_band <- cut(
  driver_age,
  breaks = c(18, 30, 40, 50, 60),
  include.lowest = TRUE
)
expected_claims <- exp(
  -1.7 + 0.018 * (driver_age - 20) + 0.0006 * (driver_age - 40)^2
)
portfolio <- data.frame(
  claims = rpois(length(driver_age), exposure * expected_claims),
  exposure = exposure,
  driver_age = driver_age,
  age_band = age_band
)

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

refinement <- prepare_refinement(model, data = portfolio) |>
  add_smoothing(
    model_variable = "age_band",
    source_variable = "driver_age",
    breaks = c(18, 30, 40, 50, 60),
    weights = "exposure"
  )

# Fit and inspect the initial smoothing specification.
initial_model <- refit(refinement)

# Edit the retained specification and fit it again.
explicit_refinement <- refinement |>
  edit_smoothing(
    model_variable = "age_band",
    from = 30,
    to = 50,
    from_value = 1.00,
    to_value = 1.10,
    control_positions = c(40),
    control_values = c(1.05)
  )

explicit_model <- refit(explicit_refinement)

# Keep the current shape as the basis and raise the middle of this interval
# by up to 5 percent. The inherited transition remains continuous.
adjusted_refinement <- refinement |>
  edit_smoothing(
    model_variable = "age_band",
    from = 30,
    to = 50,
    adjustment = 1.05
  )

adjusted_model <- refit(adjusted_refinement)

# Keep the curve unchanged through age 40, then strengthen its remaining
# change by 10 percent while retaining continuity at age 40.
steeper_refinement <- refinement |>
  edit_smoothing(
    model_variable = "age_band",
    from = 40,
    slope_adjustment = 1.10
  )

# A one-sided adjustment applies from age 40 to the end of the range.
upper_tail_refinement <- refinement |>
  edit_smoothing(
    model_variable = "age_band",
    from = 40,
    adjustment = 1.05,
    transition = "linear"
  )

---

Recover the portfolio data used by a fitted model

Description

Recover the estimation data and pricing metadata stored with a fitted GLM or a model produced by the refinement workflow. The result provides a reproducible basis for rating grids, coefficient tables and portfolio-level model diagnostics.

model_data() is kept as a deprecated compatibility wrapper.

Usage

extract_model_data(x)

Arguments

x	An object of class "glm", "refitsmooth", or "refitrestricted".

Details

Data represented by the result

For an ordinary GLM, the function recovers the data stored with the model or its model frame and records the response, model terms, risk factors, weights and offsets. The recovered data represent the observations available to the fitted model. Rows omitted during fitting, for example because of missing model variables, may therefore not be present.

For a refined model, technical columns used to construct smoothing and restriction terms are removed from the returned data. The mappings required to interpret the refined coefficients are retained as attributes. A factor created by add_relativities() replaces its parent in the default rating-grid grouping. Its numeric relativity columns are mapped to the new segment levels using the stored refinement specification; the original portfolio columns remain available for explicit grouping and audits.

Actuarial use

The extracted object is intended for downstream calculations that must remain consistent with the fitted pricing model, such as rating_grid() and rating_table(). It should not be interpreted as a replacement for the original raw portfolio extract: preprocessing, filtering and missing-value handling applied before or during model fitting remain part of the data provenance.

Value

A data.frame of class "model_data" with additional attributes:

• response: response variable in the model;

• rf: risk factors used for default rating-grid grouping, including the output factors of split refinements;

• offweights: weight and offset variables if present;

• terms: model terms object for plain GLMs;

• mgd_rst, mgd_smt: merged restrictions and smooths for refit objects;

• new_nm, old_nm: new and old column names for refit objects.

Author(s)

Martin Haringa

See Also

rating_grid(), rating_table(), prepare_refinement()

Examples

## Not run: 
library(insurancerating)

pmodel <- glm(
  breaks ~ wool + tension,
  data = warpbreaks,
  family = poisson(link = "log")
)

extract_model_data(pmodel)

## End(Not run)

---

Summarise observed portfolio experience by risk factor

Description

Aggregate observed claim, exposure and premium experience for one or more discrete risk factors. The result supports exploratory pricing analysis by showing how portfolio volume and unadjusted actuarial metrics vary across factor levels.

Usage

factor_analysis(
  data = NULL,
  risk_factors = NULL,
  claim_amount = NULL,
  claim_count = NULL,
  exposure = NULL,
  premium = NULL,
  group_by = NULL,
  df = NULL,
  x = NULL,
  severity = NULL,
  nclaims = NULL,
  by = NULL
)

Arguments

data	A data frame containing portfolio observations.
risk_factors	Non-empty character vector naming the discrete risk factors to analyse.
claim_amount	Optional character string naming the total claim-amount column.
claim_count	Optional character string naming the claim-count column.
exposure	Optional character string naming the exposure column.
premium	Optional character string naming the premium-amount column.
group_by	Optional character vector naming additional grouping variables, such as underwriting year or product segment.
df, x, severity, nclaims, by	Deprecated argument names. Use data, risk_factors, claim_amount, claim_count, and group_by instead.

Details

Calculated measures

Depending on the supplied columns, the function calculates:

• frequency = claim_count / exposure;

• average_severity = claim_amount / claim_count;

• risk_premium = claim_amount / exposure;

• loss_ratio = claim_amount / premium;

• average_premium = premium / exposure.

Input amount columns are summed before ratios are calculated. A measure is omitted when its required inputs were not supplied. A zero or missing denominator produces NA_real_ rather than an infinite value.

Actuarial interpretation

These are observed, univariate or stratified portfolio measures. They are not adjusted for correlation between rating factors and should not be interpreted as conditional GLM effects. Differences between levels may reflect portfolio mix, small exposure, claim volatility or changes over time. Claim counts, exposure and stability should therefore be reviewed alongside the ratios.

group_by can be used to compare the same risk-factor pattern across periods or portfolio segments. autoplot.factor_analysis() provides the corresponding graphical review. Modelled effects can subsequently be inspected with rating_table().

Column interface

Column names are supplied as character strings. Deprecated univariate() remains available for compatibility with its former interface.

Value

A data frame with classes "factor_analysis", "univariate" and "data.frame". It contains the grouping columns, aggregated input columns and all actuarial measures supported by the supplied inputs. The original column names are retained for claim amount, claim count, exposure and premium.

Author(s)

Martin Haringa

See Also

autoplot.factor_analysis(), rating_table(), add_portfolio_experience()

Examples

area_experience <- factor_analysis(
  MTPL2,
  risk_factors = "area",
  claim_amount = "amount",
  claim_count = "nclaims",
  exposure = "exposure",
  premium = "premium"
)

area_experience
autoplot(area_experience, metrics = c("frequency", "risk_premium"))

---

Fisher's natural breaks classification

Description

fisher_classify() is deprecated as of version 0.8.0 because Fisher-Jenks classification is not directly linked to the insurance rating workflow.

Classifies a continuous numeric vector into intervals using Fisher-Jenks natural breaks. Useful for choropleth mapping or other applications where grouped ranges are required.

Usage

fisher_classify(x, n = 7, dig.lab = NULL, diglab = NULL)

Arguments

x	A numeric vector to be classified.
n	Integer. Number of classes to generate (default = 7).
dig.lab	Integer. Number of significant digits to use for interval labels (default = 2).
diglab	Deprecated. Use dig.lab instead.

Details

The "fisher" style uses the algorithm proposed by Fisher (1958), commonly referred to as the Fisher-Jenks algorithm. This function is a thin wrapper around classInt::classIntervals().

The argument diglab is deprecated and will be removed in a future version.

Value

A factor indicating the interval to which each element of x belongs.

Author(s)

Martin Haringa

References

Bivand, R. (2018). classInt: Choose Univariate Class Intervals. R package version 0.2-3. https://CRAN.R-project.org/package=classInt

Fisher, W. D. (1958). On grouping for maximum homogeneity. Journal of the American Statistical Association, 53, pp. 789–798. doi:10.1080/01621459.1958.10501479

Examples

set.seed(1)
x <- rnorm(100)
fisher_classify(x, n = 5)

---

Fit severity distributions to truncated claim data

Description

Estimate an underlying claim severity distribution when the observed claims are truncated.

Usage

fit_truncated_severity(
  losses = NULL,
  distribution = c("gamma", "lognormal"),
  lower_truncation = NULL,
  upper_truncation = NULL,
  start_values = NULL,
  print_initial = TRUE,
  n_variants = 1,
  n_shape_grid = 8,
  n_scale_grid = 8,
  show_progress = FALSE,
  show_summary = TRUE,
  y = NULL,
  dist = NULL,
  left = NULL,
  right = NULL,
  start = NULL,
  trace = NULL,
  report = NULL
)

Arguments

losses	Numeric vector with observed claim severities.
distribution	Severity distribution to fit: "gamma" or "lognormal".
lower_truncation	Numeric lower truncation point. Claims at or below this value are assumed not to be present in losses. Defaults to 0.
upper_truncation	Numeric upper truncation point. Claims at or above this value are assumed not to be present in losses. Defaults to Inf.
start_values	Optional named list of starting values. If NULL, a multi-start strategy is used. For a gamma distribution use shape and scale; for a lognormal distribution use meanlog and sdlog.
print_initial	Deprecated logical retained for backward compatibility.
n_variants	Controls how many local variations around base starts are used.
n_shape_grid	Number of grid points for gamma shape.
n_scale_grid	Number of grid points for gamma scale.
show_progress	Logical. If TRUE, prints periodic progress during the fitting loop.
show_summary	Logical. If TRUE, prints a short summary at the end.
y, dist, left, right, start, trace, report	Deprecated argument names kept for backward compatibility.

Details

In insurance pricing, severity models are often fitted on claim amounts that are not observed over the full range of possible losses. Small claims may be absent because of a deductible, reporting threshold, or data extraction rule. Very large claims may be capped, excluded, or modelled separately as large losses. A standard gamma or lognormal fit on the remaining observed claims treats that truncated sample as if it were complete, which can bias the estimated severity distribution.

fit_truncated_severity() fits the distribution conditional on the claim being observed within the truncation interval. This means the fitted likelihood uses the density divided by the probability mass between lower_truncation and upper_truncation. The function is intended for truncation, where claims outside the interval are absent from the data. This differs from censoring, where claims outside a limit are still observed but their exact amount is not known.

Observed losses must lie strictly inside the truncation interval. Values outside the interval indicate that the bounds do not describe the data and therefore produce an error.

Value

An object of class c("truncated_severity", "truncated_dist", "fitdist"). The object contains the fitted distribution parameters from fitdistrplus::fitdist() and additional attributes:

truncated_vec

The observed losses used for fitting.

lower_truncation, upper_truncation

The truncation bounds.

fit_attempts

Metadata for each attempted start combination.

n_attempts, n_success, n_failed

Fit attempt counts.

best_attempt_index

Index of the selected start combination.

Examples

## Not run: 
observed <- MTPL2$amount[MTPL2$amount > 500 & MTPL2$amount < 10000]
fit <- fit_truncated_severity(
  losses = observed,
  distribution = "gamma",
  lower_truncation = 500,
  upper_truncation = 10000
)
autoplot(fit)

## End(Not run)

---

Reduce portfolio periods by merging adjacent date ranges

Description

Combine overlapping or nearly adjacent coverage periods for the same policy, risk or portfolio segment. The result provides a consolidated time basis for exposure calculations, active-policy counts and period-based reporting.

Together with rating_grid(), this function belongs to the portfolio reduction workflow. Both functions reduce row-level portfolio data while retaining selected totals. merge_date_ranges() reduces temporally connected records; rating_grid() reduces records with identical risk-factor values.

Usage

merge_date_ranges(
  data = NULL,
  ...,
  period_start = NULL,
  period_end = NULL,
  group_by = NULL,
  aggregate_cols = NULL,
  aggregate_fun = "sum",
  merge_gap_days = 1,
  df = NULL,
  begin = NULL,
  end = NULL,
  agg_cols = NULL,
  agg = NULL,
  min.gapwidth = NULL
)

Arguments

data	A data.frame or data.table containing the portfolio periods.
period_start	Character string. Name of the column with period start dates.
period_end	Character string. Name of the column with period end dates.
group_by	Character vector with columns that identify the portfolio entity or rating segment within which date ranges should be merged.
aggregate_cols	Character vector with numeric columns to aggregate over merged ranges, for example premium or exposure.
aggregate_fun	Function or function name used to combine aggregate_cols within a merged interval. The default, "sum", is generally appropriate for additive measures such as premium or exposure.
merge_gap_days	Non-negative whole number. Ranges with fewer uncovered days than this value are treated as continuous. The default, 1, merges overlapping periods and periods that start on the day after the preceding period ends. Use 0 to merge overlapping periods only. A value above 1 also bridges short uncovered gaps and should represent an explicit administrative assumption.
df, begin, end, ..., agg_cols, agg, min.gapwidth	Deprecated argument names kept for backward compatibility. Use data, period_start, period_end, group_by, aggregate_cols, aggregate_fun, and merge_gap_days.

Details

Portfolio reduction

merge_date_ranges() performs temporal portfolio reduction. It combines connected periods within the same group_by values and retains the selected additive amounts. Use rating_grid() for the complementary categorical reduction of records with identical risk-factor combinations.

Connected periods

Insurance portfolio extracts often contain multiple rows for the same policy or risk because of renewals, endorsements, product changes, or short administrative gaps. Before calculating portfolio in/outflow, active exposure windows, or policy counts, it can be useful to reduce those rows to stable coverage intervals.

merge_date_ranges() merges date ranges within each group_by combination. Ranges with a gap smaller than merge_gap_days are treated as one continuous interval. If aggregate_cols is supplied, those columns are aggregated over the merged interval. The grouping columns should identify records for which combining coverage periods is actuarially and operationally meaningful; periods belonging to different risks or contracts should not be pooled. Missing values are not permitted in group_by, because such records cannot be assigned reliably to the same policy, risk or segment.

Start and end dates are treated as inclusive. Consequently, two periods for which the second starts one day after the first ends have zero uncovered days. They are merged with the default merge_gap_days = 1. A value of 5 merges periods with at most four uncovered days between them.

Aggregation and implementation

Aggregated amounts are combined over the source rows, not prorated over calendar days. Summing premium or exposure is appropriate when each source row contains a distinct additive amount. If overlapping rows already contain amounts for the same covered days, users should resolve that overlap before aggregation to avoid double counting.

Each output row represents one consolidated period within a group_by combination. This is a temporal reduction of the portfolio; records with the same risk-factor values are not combined when their periods remain separate.

Internally, interval construction and aggregation use data.table::data.table() on a local copy. The supplied object is not modified by reference. For a portfolio that should remain outside R memory, use merge_date_ranges_db() to perform the same interval reduction in DuckDB.

Value

A regular data.frame with classes "merged_date_ranges" and "reduce", and attributes:

• begin — name of the period-start column

• end — name of the period-end column

• cols — grouping columns

Author(s)

Martin Haringa

See Also

merge_date_ranges_db(), rating_grid(), rating_grid_db(), active_rows_by_date(), split_periods_to_months()

Examples

portfolio <- data.frame(
  policy_id = rep(c("P001", "P002"), each = 3),
  coverage = rep(c("Fire", "Liability"), each = 3),
  period_start = as.Date(c(
    "2024-01-01", "2024-02-01", "2024-04-01",
    "2024-01-01", "2024-02-03", "2024-03-03"
  )),
  period_end = as.Date(c(
    "2024-01-31", "2024-02-29", "2024-04-30",
    "2024-01-31", "2024-03-02", "2024-03-31"
  )),
  earned_premium = c(100, 110, 120, 80, 90, 95)
)

# Reduce directly adjacent periods within each policy and coverage.
pt1 <- merge_date_ranges(
  portfolio,
  period_start = "period_start",
  period_end = "period_end",
  group_by = c("policy_id", "coverage")
)

summary(pt1, period = "months", policy_id, coverage)

# Bridge a short administrative gap and retain additive premium totals.
pt2 <- merge_date_ranges(
  portfolio,
  period_start = "period_start",
  period_end = "period_end",
  group_by = c("policy_id", "coverage"),
  aggregate_cols = "earned_premium",
  # Explicitly bridge administrative gaps of up to four uncovered days.
  merge_gap_days = 5
)

summary(pt2, period = "months", policy_id, coverage)

---

Merge connected portfolio periods in DuckDB

Description

Construct the temporal portfolio reduction performed by merge_date_ranges() as a lazy DuckDB query. Overlapping or adjacent periods are merged inside DuckDB, so only the consolidated periods need to be copied into R.

Usage

merge_date_ranges_db(
  data,
  period_start,
  period_end,
  group_by,
  aggregate_cols = NULL,
  aggregate_fun = c("sum", "mean", "min", "max"),
  merge_gap_days = 1
)

Arguments

data	A lazy DuckDB table created with dplyr::tbl().
period_start	Character string naming the period-start column.
period_end	Character string naming the period-end column.
group_by	Character vector identifying the policy, risk or segment within which periods may be combined.
aggregate_cols	Optional character vector naming numeric columns to aggregate over each merged period.
aggregate_fun	Character string specifying the SQL aggregation for aggregate_cols: "sum", "mean", "min", or "max".
merge_gap_days	Non-negative whole number. The interpretation is the same as in merge_date_ranges(): 1 merges overlapping and directly adjacent periods, while 0 merges overlapping periods only.

Details

Merging connected intervals is a SQL gaps-and-islands calculation. The query uses ordered window functions to compare each start date with the latest preceding end date, assigns an interval identifier, and then aggregates each resulting interval.

Date arithmetic differs between database systems. This implementation is therefore deliberately restricted to DuckDB. It does not download the source table and does not create a permanent database table.

Value

A lazy DuckDB table. Use dbplyr::sql_render() to inspect the SQL or dplyr::collect() to import the consolidated periods into R.

Author(s)

Martin Haringa

See Also

merge_date_ranges(), rating_grid_db(), rating_grid()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb())
portfolio_db <- dplyr::tbl(con, "portfolio_periods")

periods_db <- merge_date_ranges_db(
  portfolio_db,
  period_start = "period_start",
  period_end = "period_end",
  group_by = c("policy_id", "coverage"),
  aggregate_cols = c("earned_exposure", "earned_premium")
)

periods <- dplyr::collect(periods_db)
DBI::dbDisconnect(con, shutdown = TRUE)

## End(Not run)

---

Compare fitted GLMs using common performance measures

Description

Compare one or more fitted GLMs using AIC, BIC and response-scale RMSE. The resulting table provides a concise first comparison of alternative pricing-model specifications fitted to the same portfolio outcome.

Usage

model_performance(...)

Arguments

...	One or more objects of class "glm".

Details

The following measures are reported:

AIC

Akaike information criterion, balancing likelihood fit and model complexity.

BIC

Bayesian information criterion, applying a stronger sample-size-dependent complexity penalty.

RMSE

Root mean squared error between observed and response-scale predicted values.

Lower values are preferred within each measure, but the measures answer different questions. AIC and BIC depend on the model likelihood, whereas RMSE measures error on the response scale. Comparisons are therefore most meaningful when models use the same response, estimation records, weights and offsets.

The table does not select a pricing model automatically. In actuarial model assessment, statistical fit should be considered together with portfolio calibration, residual behaviour, coefficient stability, exposure by level and the practical interpretability of the resulting tariff structure.

The implementation is adapted from performance::model_performance().

Value

A data frame of class "model_performance", with columns:

Model

Name of the model object as passed to the function.

AIC

AIC value.

BIC

BIC value.

RMSE

Root mean squared error.

Author(s)

Martin Haringa

See Also

rmse(), bootstrap_performance(), check_overdispersion(), check_residuals()

Examples

m1 <- glm(nclaims ~ area, offset = log(exposure), family = poisson(),
          data = MTPL2)
m2 <- glm(nclaims ~ area + premium, offset = log(exposure), family = poisson(),
          data = MTPL2)
model_performance(m1, m2)

---

Motor Third Party Liability (MTPL) portfolio

Description

A dataset containing the characteristics of 30,000 policyholders in a Dutch Motor Third Party Liability (MTPL) insurance portfolio. Includes information on policyholder characteristics, vehicle attributes, and claims.

Usage

MTPL

Format

A data frame containing 30,000 rows and 7 variables:

age_policyholder

Age of the policyholder (in years).

nclaims

Number of claims.

exposure

Exposure, expressed in years. For example, if a vehicle is insured from July 1, the exposure equals 0.5 for that year.

amount

Total claim amount for the portfolio record (in euros).

power

Engine power of the vehicle (in kilowatts).

bm

Bonus-malus level (0–22). Higher levels indicate worse claim history.

zip

Region indicator (0–3).

Author(s)

Martin Haringa

---

Motor Third Party Liability (MTPL) portfolio (3,000 policyholders)

Description

A dataset containing the characteristics of 3,000 policyholders in a Dutch Motor Third Party Liability (MTPL) insurance portfolio. Includes information on region, claims, exposure, and premium.

Usage

MTPL2

Format

A data frame containing 3,000 rows and 6 variables:

customer_id

Unique customer identifier.

area

Region where the customer lives (0–3).

nclaims

Number of claims.

amount

Total claim amount for the portfolio record (in euros).

exposure

Exposure, expressed in years.

premium

Earned premium.

Author(s)

Martin Haringa

---

Portfolio histogram with tail bins

Description

Visualise the distribution of a numeric portfolio variable while keeping extreme tails readable.

Insurance portfolios often contain skewed variables such as claim amounts, premium, exposure, insured sums, deductibles, or fitted premiums. A few very large policies or claim events can stretch a regular histogram so much that the body of the portfolio becomes hard to inspect. outlier_histogram() keeps the main range visible and groups values below lower or above upper into dedicated tail bins.

The plot is useful for actuarial portfolio checks, data quality review, and model preparation: it helps show where most risks are concentrated while still making the presence of extreme observations explicit.

Usage

outlier_histogram(
  data,
  x,
  lower = NULL,
  upper = NULL,
  density = FALSE,
  bins = 30,
  bar_fill = "#E6E6E6",
  bar_color = "white",
  tail_fill = "#F28E2B",
  tail_color = "white",
  density_color = "#2C7FB8",
  left = NULL,
  right = NULL,
  line = NULL,
  fill = NULL,
  color = NULL,
  fill_outliers = NULL
)

Arguments

data	A data.frame containing the portfolio variable to inspect.
x	Character; numeric column in data to plot.
lower	Optional numeric lower threshold. Values below this threshold are grouped into one left-tail bin.
upper	Optional numeric upper threshold. Values above this threshold are grouped into one right-tail bin.
density	Logical. If TRUE, add a density line. Default = FALSE.
bins	Integer. Number of bins used for the displayed range. Default = 30.
bar_fill	Fill color for regular histogram bars.
bar_color	Border color for regular histogram bars.
tail_fill	Fill color for tail bins.
tail_color	Border color for tail bins.
density_color	Color for the optional density line.
left, right	Deprecated aliases for lower and upper.
line	Deprecated alias for density.
fill, color, fill_outliers	Deprecated aliases for bar_fill, bar_color, and tail_fill.

Details

This function is intended as an exploratory portfolio diagnostic. It does not remove or winsorize observations in data; it only groups tail values in the visual display. The labels on the tail bins show the original range captured by each tail bin.

The method for handling outlier bins is based on https://edwinth.github.io/blog/outlier-bin/.

Value

A ggplot2::ggplot object.

Author(s)

Martin Haringa

Examples

# Inspect the full premium distribution
outlier_histogram(MTPL2, "premium")

# Keep the portfolio body readable while showing both tails
outlier_histogram(MTPL2, "premium", lower = 30, upper = 120, bins = 30)

---