methods.chain_ladder()
The chain ladder: project each origin’s latest cumulative loss to ultimate.
Usage
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:
2020is the period starting 2020-01-01 (a two-digit year such as97is 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 againstdev_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 withdev_grain_months=12both 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; withdev_grain_months=32020-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 byprevious ** 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). Underzero_cells="missing"a ratio left out for a zero cell still counts as one of them, as in chainladder-python’sn_periods, so the window then holds fewer.exclude: link ratios to leave out, as(origin_period, dev_lag)pairs, wheredev_lagis 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 waysorigin_periodmay, 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 (2020or"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’sdrop_valuationnames the EARLIER end of the link ratio instead, so itsdrop_valuation=2019isexclude_valuations=[2020]here.drop_above/drop_below: leave out every link ratio strictly abovedrop_aboveor strictly belowdrop_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.Truemeans 1 andFalse0.trim_ties: which of two equal link ratiosdrop_high/drop_lowleave out."volume"(the default here, chainladder-python’s rule) ranks equal ratios by the earlier cumulative:drop_highleaves out the one with the larger amount anddrop_lowthe smaller; equal amounts too go by origin,drop_highthe newer anddrop_lowthe 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_exclusionsdecides.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 indevelopment.unity_fallback.exhausted_exclusions: what to do when the bounds, or the trims, would leave fewer thanpreserveratios at an age."keep"(the default here) does not apply that rule at that age and marks it indevelopment.bounds_skippedordevelopment.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, sodrop_high=Truewould 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 inlink_ratioswith reasonzero_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 reasonundefined_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 linkt, 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’sTailCurve. 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 fromtail_attach_lagto 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 istail_decaytimes the step’s before it, and the last step holds what is left, so the steps multiply totail_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), anddevelopment.sourcesays which.tail_fit_lags: curves only,(first, last): the ages, in months, that the first and the last link fitted develop from, both included;Noneat 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_fitshows 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’sextrap_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 agedevelopmentshows, 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 thantail_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.