Package 'clmplus'

Title: Tool-Box of Chain Ladder Plus Models
Description: Implementation of the age-period-cohort models for the claim development presented in the manuscript 'Replicating and extending chain-ladder via an age-period-cohort structure on the claim development in a run-off triangle' <doi:10.1080/10920277.2025.2496725>.
Authors: Gabriele Pittarello [aut, cre, cph] (ORCID: <https://orcid.org/0000-0003-3360-5826>), Munir Hiabu [aut, cph] (ORCID: <https://orcid.org/0000-0001-5846-667X>), Andres Villegas [aut, cph]
Maintainer: Gabriele Pittarello <[email protected]>
License: GPL (>= 2)
Version: 1.1.0
Built: 2026-07-24 13:09:29 UTC
Source: https://github.com/gpitt71/clmplus

Help Index

Pre-process Run-Off Triangles

Description

Pre-process Run-Off Triangles.

Usage

AggregateDataPP(
  cumulative.payments.triangle,
  entries.weights = NULL,
  eta = 1/2
)

Arguments

cumulative.payments.triangle

A square numeric matrix with at least two rows. Rows are accident periods, columns are development periods, and observed upper-triangle cells satisfy 'row + column <= J + 1'. Values are non-negative cumulative paid amounts in the source data's monetary units, non-decreasing across each row; unavailable cells may be 'NA'. Recoveries (negative incremental payments) are not supported.
entries.weights

Optional non-negative numeric 'J' by 'J' matrix of fitting weights in the same accident/development layout. 'NULL' gives observed cells weight one. The first development period and missing cells are always zero-weighted after conversion to calendar coordinates.
eta

One finite numeric value in '(0, 1]', default '0.5', describing expected within-cell payment timing (lost exposure). It is used to derive exposure and to convert fitted hazards to development factors.

Value

An 'AggregateDataPP' list with:

cumulative.payments.triangle

The input 'J' by 'J' cumulative paid triangle, unchanged.
occurrance

A 'J' by 'J' matrix of incremental paid amounts in development-period by calendar-period coordinates. The misspelling is retained as a stable public field name.
exposure

A 'J' by 'J' numeric matrix in the same calendar coordinates, calculated as cumulative payments minus '(1 - eta) * occurrence'.
incremental.payments.triangle

A 'J' by 'J' accident/development matrix of incremental paid amounts.
fit.w

The 'J' by 'J' fitting-weight matrix in development/calendar coordinates.
J

The integer triangle dimension.
diagonal

A length-'J' numeric vector containing the latest observed cumulative diagonal in calendar representation.
eta

The supplied within-cell timing scalar.

References

Pittarello, G., Hiabu, M., & Villegas, A. M. (2023). Replicating and extending chain-ladder via an age-period-cohort structure on the claim development in a run-off triangle. arXiv preprint arXiv:2301.03858.

Examples

data(sifa.mtpl)
sifa.mtpl.rtt <- AggregateDataPP(cumulative.payments.triangle=sifa.mtpl)

Amases GTPL

Description

Dataset of cumulative paid claims for a small italian company in the line of business: general third party liability.

Usage

amases.gtpl

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014

Amases MOD

Description

Dataset of cumulative paid claims for a small italian company in the line of business: motor or damage.

Usage

amases.mod

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014

Amases MTPL

Description

Dataset of cumulative paid claims for a small italian company in the line of business: motor third party liability.

Usage

amases.mtpl

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014

Fit a Chain Ladder Plus hazard model

Description

Fits one of the package's age, age-cohort, age-period, or age-period-cohort claim-development models to data prepared by [AggregateDataPP()]. Estimation is performed by [StMoMo::fit.StMoMo()].

Usage

clmplus(
  AggregateDataPP,
  hazard.model = NULL,
  link = c("log", "logit"),
  staticAgeFun = TRUE,
  periodAgeFun = "NP",
  cohortAgeFun = NULL,
  effect_log_scale = TRUE,
  verbose = FALSE,
  constFun = function(ax, bx, kt, b0x, gc, wxt, ages) {
     list(ax = ax, bx = bx, kt =
    kt, b0x = b0x, gc = gc)
 },
  ...
)

## Default S3 method:
clmplus(
  AggregateDataPP,
  hazard.model = NULL,
  link = c("log", "logit"),
  staticAgeFun = TRUE,
  periodAgeFun = "NP",
  cohortAgeFun = NULL,
  effect_log_scale = TRUE,
  verbose = FALSE,
  constFun = function(ax, bx, kt, b0x, gc, wxt, ages) {
     list(ax = ax, bx = bx, kt =
    kt, b0x = b0x, gc = gc)
 },
  ...
)

## S3 method for class 'AggregateDataPP'
clmplus(
  AggregateDataPP,
  hazard.model = NULL,
  link = c("log", "logit"),
  staticAgeFun = TRUE,
  periodAgeFun = "NP",
  cohortAgeFun = NULL,
  effect_log_scale = TRUE,
  verbose = FALSE,
  constFun = function(ax, bx, kt, b0x, gc, wxt, ages) {
     list(ax = ax, bx = bx, kt =
    kt, b0x = b0x, gc = gc)
 },
  ...
)

Arguments

AggregateDataPP

An object created by [AggregateDataPP()]. It contains a square cumulative paid-claims triangle and the corresponding development-calendar occurrence, exposure, and weight matrices.
hazard.model

A required character scalar selecting '"a"' (age only, equivalent to chain ladder), '"ac"' (age-cohort), '"ap"' (age-period), or '"apc"' (age-period-cohort).
link, staticAgeFun, periodAgeFun, cohortAgeFun, constFun

Compatibility arguments retained from the original interface. The package's four built-in model definitions determine these settings, so these arguments are currently ignored.
effect_log_scale

A logical scalar. If 'TRUE' (the default), fitted effects are returned on the linear-predictor/log scale; if 'FALSE', they are exponentiated.
verbose

A logical scalar passed to [StMoMo::fit.StMoMo()]. The default 'FALSE' hides StMoMo fitting progress. 'TRUE' displays progress, including zero-weighted ages, years, and cohorts and the start/finish of the gnm fit.
...

Reserved for future extensions; no arguments are currently forwarded.

Details

Incremental payment amounts can be non-integer even though the StMoMo fit uses a Poisson quasi-likelihood. Warnings whose messages begin exactly with 'non-integer x =' are therefore expected and are selectively muffled. All other warnings, including convergence and numerical warnings, remain visible.

Value

A 'clmplusmodel' list with:

model.fit

The underlying 'fitStMoMo' object. Its fitted 'ax', 'kt', and 'gc' fields contain the selected age, period, and cohort effects; inapplicable effects are 'NULL'. Other fields are supplied by StMoMo and should be treated as implementation details.

apc_input

A list containing 'J' (triangle dimension), 'eta' (within-cell exposure timing), 'hazard.model', 'diagonal' (latest observed cumulative payments by calendar representation), and the original 'cumulative.payments.triangle'.

hazard_scaled_deviance_residuals

A 'J' by 'J' numeric matrix in accident-year by development-year triangle orientation. Unobserved cells are 'NA'.

fitted_development_factors

A 'J' by 'J' numeric matrix of fitted multiplicative cumulative development factors; unavailable cells are 'NA'.

fitted_effects

A list with 'fitted_development_effect', 'fitted_calendar_effect', and 'fitted_accident_effect'. Components not included in the selected model are 'NULL'.

The default method always raises an informative error because 'AggregateDataPP' does not inherit from '"AggregateDataPP"'.

See Also

[AggregateDataPP()], [predict.clmplusmodel()], [predictReserve.clmplusmodel()], [plot.clmplusmodel()]

Examples

data(sifa.mtpl)
prepared <- AggregateDataPP(sifa.mtpl)
age_fit <- clmplus(prepared, hazard.model = "a", verbose = FALSE)
age_fit$fitted_effects

apc_fit <- clmplus(prepared, hazard.model = "apc", verbose = FALSE)
plot(apc_fit)

Plot the payments behavior

Description

This function allows to define the behavior of the triangle payments.

Usage

## S3 method for class 'AggregateDataPP'
plot(x, ...)

Arguments

x

An 'AggregateDataPP' object.
...

Reserved; currently ignored.

Value

A 'gtable' containing two ggplot panels (incremental and cumulative paid amounts), returned visibly after being drawn.

References

Pittarello, Gabriele, Munir Hiabu, and Andrés M. Villegas. "Replicating and extending chain ladder via an age-period-cohort structure on the claim development in a run-off triangle." arXiv preprint arXiv:2301.03858 (2023).

Examples

data(sifa.mtpl)
sifa.mtpl.pp <- AggregateDataPP(cumulative.payments.triangle=sifa.mtpl)
plot(sifa.mtpl.pp)

Plot the hazard model residuals

Description

This function allows to plot the hazard model residuals on the triangle payments.

Usage

## S3 method for class 'clmplusmodel'
plot(x, heat.lim = c(-2.5, 2.5), ...)

Arguments

x

A fitted 'clmplusmodel' object.
heat.lim

A length-two numeric vector giving the lower and upper fill scale limits for scaled deviance residuals.
...

Reserved; currently ignored.

Value

A 'ggplot' object showing scaled deviance residuals in accident-year by development-year triangle form.

References

Pittarello, Gabriele, Munir Hiabu, and Andrés M. Villegas. "Replicating and extending chain ladder via an age-period-cohort structure on the claim development in a run-off triangle." arXiv preprint arXiv:2301.03858 (2023).

Examples

data(sifa.mtpl)
sifa.mtpl.rtt <- AggregateDataPP(cumulative.payments.triangle=sifa.mtpl)
clm.fit<-clmplus(sifa.mtpl.rtt, 'a')
plot(clm.fit)

Plot the hazard model fitted and forecasted parameters

Description

This function allows to define the behavior of the triangle payments.

Usage

## S3 method for class 'clmpluspredictions'
plot(x, cy.type = "fe", ...)

Arguments

x

A 'clmpluspredictions' object returned by [predict.clmplusmodel()].
cy.type

Either '"fe"' (the default) to include extrapolated calendar effects or '"f"' to show only fitted calendar effects.
...

Reserved; currently ignored.

Value

A 'gtable' containing one ggplot panel for each effect included in the fitted model. The table is returned visibly after being drawn.

References

Pittarello, G., Hiabu, M., & Villegas, A. M. (2023). Replicating and extending chain-ladder via an age-period-cohort structure on the claim development in a run-off triangle. arXiv preprint arXiv:2301.03858.

Examples

data(sifa.mtpl)
sifa.mtpl.rtt <- AggregateDataPP(cumulative.payments.triangle=sifa.mtpl)
clm.fit<-clmplus(sifa.mtpl.rtt, 'a')
clm <- predict(clm.fit)
plot(clm)

Predict the Reserve using Chain Ladder Plus Models

Description

Predict the lower triangle with a clmplus model.

Usage

## S3 method for class 'clmplusmodel'
predict(
  object,
  gk.fc.model = "a",
  ckj.fc.model = "a",
  gk.order = c(1, 1, 0),
  ckj.order = c(0, 1, 0),
  forecasting_horizon = NULL,
  constrained_development_factors = FALSE,
  ...
)

Arguments

object

clmplusmodel, Model to predict from.
gk.fc.model

character, model to forecast the cohort component for the last accident period. It can be either arima ('a') or linear model ('l'). Disregarded for models that do not have a cohort effect.
ckj.fc.model

character, model to forecast the calendar period effect. It can be either arima ('a') or linear model ('l'). Disregarded for models that do not have a period effect.
gk.order

integer, order of the arima model with drift for the accident year effect extrapolation. Default to (1,1,0).
ckj.order

integer, order of the arima model with drift for the calendar year effect extrapolation. Default to (0,1,0).
forecasting_horizon

integer, between 1 and the triangle width. Calendar periods ahead for the predictions. Default predictions are to run-off.
constrained_development_factors

logical, if TRUE the predict function will set negative development factors to 1.
...

Extra arguments to be passed to the predict function.

Value

Returns the following output:

reserve

numeric The reserve for each accident period.

ultimate_cost

numeric The ultimate cost for each accident period.

full_triangle

matrix array The complete run-off triangle of cumulative payments, it includes the (input) upper triangle and the predicted (output) lower triangle.
lower_triangle

matrix array The predicted lower triangle of cumulative payments.
development_factors_predicted

matrix array The predicted lower triangle of the extrapolated development factors.
apc_output

list The following output from the age-period-cohort representation: model.fit (fitStMoMo) age-period-cohort model fit. alphaij (matrix array) predicted claim development. lower_triangle_apc (matrix array) predicted lower triangle of cumulative payments in age-period-cohort form. development_factors_apc (matrix array) development factors in age-period-cohort representation.

References

Pittarello, Gabriele, Munir Hiabu, and Andrés M. Villegas. "Replicating and extending chain ladder via an age-period-cohort structure on the claim development in a run-off triangle." arXiv preprint arXiv:2301.03858 (2023).

Sifa GTPL

Description

Dataset of cumulative paid claims for a medium italian company in the line of business: general third party liability.

Usage

sifa.gtpl

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014

Sifa MOD

Description

Dataset of cumulative paid claims for a medium italian company in the line of business: motor or damage.

Usage

sifa.mod

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014

Sifa MTPL

Description

Dataset of cumulative paid claims for a medium italian company in the line of business: motor third party liability.

Usage

sifa.mtpl

Format

A 12 by 12 numeric matrix of cumulative paid claims. Rows index accident years and columns index development years; cells below the observed run-off triangle are ‘NA'. Amounts are in the source’s recorded monetary units. No additional preprocessing has been applied.

References

Savelli, Nino, and Clemente, Gian Paolo. "Lezioni di matematica attuariale delle assicurazioni danni." EDUCatt-Ente per il diritto allo studio universitario dell'Università Cattolica, 2014