Skip to main content

methods.chain_ladder()

The chain ladder: project each origin’s latest cumulative loss to ultimate.

Usage

Source

methods.chain_ladder(
    cells,
    *,
    dev_grain_months=12,
    average="volume",
    history_periods=None,
    drop_high=False,
    drop_low=False,
    preserve=1,
    drop_above=None,
    drop_below=None,
    exclude=(),
    exclude_valuations=(),
    trim_ties="volume",
    unsupported_factor="raise",
    exhausted_exclusions="keep",
    zero_cells="missing",
    tail=None,
    tail_factor=None,
    tail_decay=None,
    tail_attach_lag=None,
    tail_fit_lags=None,
    tail_steps=None,
    tail_rows=None
)

cells is one triangle’s cells: columns origin_period, dev_lag (months from the start of the origin period) and value (cumulative loss), one row per observed cell, in any table Arrow can read (a polars DataFrame or a pyarrow Table, for example). An unobserved cell is left out, not given a null value. One triangle per call: two companies’ rows passed together are refused. Every origin period from the first to the last needs cells, one development step apart, and every value must be zero or more.

origin_period names each origin period in any of these ways, and may be dictionary-encoded (a polars Categorical or Enum):

  • an integer year with its century: 2020 is the period starting 2020-01-01 (a two-digit year such as 97 is refused);
  • a text label: a year "2020", a quarter "2020Q3" (starting 2020-07-01) or a month "2020-03" (starting 2020-03-01);
  • a date, a timestamp (read as its date, in its own time zone when it has one) or an ISO date string such as "2020-12-31". A date is read against dev_grain_months, which is also the length of an origin period: the first day of a month is the period’s first day, and the last day of a month is the period’s last day. So with dev_grain_months=12 both 2020-01-01 and 2020-12-31 are the accident year 2020, and 2021-06-30 is the year from July 2020 to June 2021; with dev_grain_months=3 2020-12-31 is the fourth quarter of 2020. Any other day is refused.

A year, quarter or month label must name a period dev_grain_months long. Each period must be written one way throughout the column (2020-01-01 and 2020-12-31 together are refused), because the results echo the label back: origins and link_ratios carry it in a column origin, the value written (as int64, string, date32 or the input’s timestamp type, as ReserveResult lists), beside origin_period, which is always the first day of the period. dev_lag still counts from the period’s first day, whichever day names it.

The development options, shared with bornhuetter_ferguson(), benktander() and cape_cod(), and with mack() except for unsupported_factor and the median. The rules that leave link ratios out run in this order, each on the ratios the ones before it left: zero_cells, history_periods, exclude, exclude_valuations, drop_above/drop_below, then drop_high/drop_low. Each ratio left out is listed in link_ratios with the first rule that removed it.

  • dev_grain_months: months per development step, 12 for an annual triangle, 3 for a quarterly one. Origin periods must be the same length.
  • average: how link ratios become a factor. "volume" (the default) divides the sum of the later cumulatives by the sum of the earlier ones; "simple" is the plain mean of the ratios; "regression" is least squares through the origin, sum(previous * following) / sum(previous ** 2); "median" is their median. (In Mack’s terms each ratio is weighted by previous ** alpha, with alpha 1 for volume, 0 for simple and 2 for regression.)
  • history_periods: use only the latest this many link ratios at each age (None, the default, uses them all). Under zero_cells="missing" a ratio left out for a zero cell still counts as one of them, as in chainladder-python’s n_periods, so the window then holds fewer.
  • exclude: link ratios to leave out, as (origin_period, dev_lag) pairs, where dev_lag is the age the ratio develops FROM in whole months; (2010, 12) leaves out the 2010 ratio from 12 to 24 months. The origin may be written in any of the ways origin_period may, not necessarily the way the cells write it. A pair that names no link ratio of the triangle is refused.
  • exclude_valuations: whole diagonals to leave out. Each valuation leaves out every link ratio that develops INTO it, so excluding 2020 removes the development that happened during 2020 (a year distorted by COVID, say), and the latest valuation may be excluded too. Write each as the evaluation date, the last day of a development period ("2020-12-31" or a date), or as the one period it ends: a year (2020 or "2020") on an annual triangle, a quarter ("2020Q4") on a quarterly one, a month ("2020-12") on a monthly one. A valuation no link ratio develops into (the first diagonal, or a date after the latest one) is refused. chainladder-python’s drop_valuation names the EARLIER end of the link ratio instead, so its drop_valuation=2019 is exclude_valuations=[2020] here.
  • drop_above / drop_below: leave out every link ratio strictly above drop_above or strictly below drop_below; a ratio equal to a bound is kept (chainladder-python leaves it out).
  • drop_high / drop_low: leave out this many of the highest and the lowest link ratios at each age. True means 1 and False 0.
  • trim_ties: which of two equal link ratios drop_high/drop_low leave out. "volume" (the default here, chainladder-python’s rule) ranks equal ratios by the earlier cumulative: drop_high leaves out the one with the larger amount and drop_low the smaller; equal amounts too go by origin, drop_high the newer and drop_low the older. "origin" ranks equal ratios by origin alone, the rule of ibnr 0.7.2 and the default of kernels.ConventionalCandidate.
  • preserve: the fewest link ratios the bounds may leave at an age, and the fewest the trims may leave (1 by default). Each rule is all or nothing at an age: if it would leave fewer, exhausted_exclusions decides.
  • unsupported_factor: what to do at an age where no link ratio is left to average: "raise" (the default) refuses; "unity" uses a factor of 1.0 and marks the age in development.unity_fallback.
  • exhausted_exclusions: what to do when the bounds, or the trims, would leave fewer than preserve ratios at an age. "keep" (the default here) does not apply that rule at that age and marks it in development.bounds_skipped or development.extreme_trimming_skipped; "raise" refuses. The default differs from kernels.ConventionalCandidate’s "raise" because on a complete triangle the last age has a single link ratio, so drop_high=True would always be refused; chainladder-python users expect it to work, and the result records the skip.
  • zero_cells: what a cumulative of exactly zero is. "missing" (the default here) follows chainladder-python, which stores a zero cell as missing: a link ratio is used only when neither of its two cells is zero, so the ratio into a zero and the ratio out of it are both left out, shown in link_ratios with reason zero_cell. "observed" keeps the zero as data: the ratio into it (0) is used, and only the ratio out of it, which is undefined, is left out, with reason undefined_ratio. The default differs from kernels.ConventionalCandidate’s "observed", so that these functions give chainladder-python’s factors on triangles with zeros. Either way a zero on an origin’s latest diagonal is its latest amount, so its chain-ladder ultimate is 0, where chainladder-python leaves that ultimate missing.

The tail options, shared with bornhuetter_ferguson(), benktander(), cape_cod() and mack(). A tail is the development still to come after the last observed age. It is applied to the factors the development options produced, and every origin’s development to ultimate then includes it, the oldest origin’s too, so Bornhuetter-Ferguson, Benktander and Cape Cod read it through pct_reported. Every option but tail defaults to None, and one given without tail is refused rather than ignored.

  • tail: None (the default, no tail), "constant", or a curve fitted to the link factors by least squares: "exponential" (f - 1 = exp(a + b t) at link t, link 1 developing from the first age), "inverse_power" (f - 1 = exp(a) t ** b) or "weibull" (f = 1 / (1 - exp(-exp(a) t ** b))), as chainladder-python’s TailCurve. A curve must decay with age, and an inverse power curve’s slope must be below -1, since between -1 and 0 the product of its factors never converges; otherwise it is refused.
  • tail_factor: a constant tail’s development from tail_attach_lag to ultimate, such as 1.05; needed for "constant". Below 1 is allowed and lowers the ultimates.
  • tail_decay: from 0 to 1 (0.5 by default), how a constant tail is spread over the steps it covers: each step’s development above 1 is tail_decay times the step’s before it, and the last step holds what is left, so the steps multiply to tail_factor. With the tail attached at the last observed age it changes only the rows shown, never an ultimate.
  • tail_attach_lag: the age, in months, of the first link the tail replaces. The default is the last observed age, where no link is replaced; an earlier age replaces the factors from that age on with the curve’s (or the constant’s steps), and development.source says which.
  • tail_fit_lags: curves only, (first, last): the ages, in months, that the first and the last link fitted develop from, both included; None at either end is the edge of the triangle. Only factors above 1.00001 go through the line, and at least two must, or the tail is refused (in_tail_fit shows which did).
  • tail_steps: curves only, how many development steps past the last observed age the curve is extrapolated, 1 to 10,000 (100 by default, as chainladder-python’s extrap_periods). It is a count of steps of the triangle’s own grain, not months. An inverse power tail still grows noticeably at 100 steps.
  • tail_rows: how many rows beyond the last observed age development shows, one step each (one year’s by default: 1 on an annual triangle, 4 on a quarterly one); the final row’s cdf holds the rest of the tail. It never changes an ultimate. A curve cannot show more rows than tail_steps.

docs/coming-from-chainladder.md maps chainladder-python’s TailConstant and TailCurve options onto these, with the cases chainladder-python rounds, ignores or answers as no tail that are refused here.

Returns a ReserveResult. Without a tail each origin is projected to the last observed development age. Input it will not answer is refused with Refusal, whose reason codes the module docstring describes.