API Reference
Reserving methods
The front door for the traditional methods: one function per method, named after it, on one triangle’s cells given as any Arrow-readable table (a polars DataFrame or a pyarrow Table). Import with from ibnr import methods. Results are pyarrow Tables, and ReserveResult.to_polars() gives any of them as a polars DataFrame. Input a method will not answer is refused with Refusal, a ValueError with a reason code. Coming from chainladder-python, see the lookup table.
- methods.chain_ladder()
-
The chain ladder: project each origin’s latest cumulative loss to ultimate.
- methods.mack()
-
Mack’s chain ladder: the chain-ladder ultimate and its standard error.
- methods.bornhuetter_ferguson()
-
Bornhuetter-Ferguson: the unreported share of an a priori ultimate.
- methods.benktander()
-
Benktander: Bornhuetter-Ferguson repeated, each time from the last ultimate.
- methods.cape_cod()
-
Cape Cod: Bornhuetter-Ferguson with the loss ratio estimated from the triangle.
- methods.tweedie_glm()
-
A Tweedie GLM fitted to the triangle’s increments, and each origin’s ultimate.
- methods.ml_development()
-
A random forest or gradient boosting fitted to the cells, and each origin’s ultimate.
- methods.one_year_cdr()
-
The one-year claims development result: how far next year’s re-estimate
- methods.odp_bootstrap()
-
England and Verrall’s over-dispersed Poisson bootstrap of the whole run-off.
- methods.ReserveResult
-
What a reserving method returns: pyarrow Tables with fixed column types.
- methods.OneYearCDRResult
-
What
one_year_cdr()returns: pyarrow Tables with fixed column types. - methods.BootstrapResult
-
What
odp_bootstrap()returns: pyarrow Tables with fixed column types. - methods.Refusal
-
ibnr will not answer this input, and says why with a reason code.
Triangle
The long-format triangle data layer - a tidy table of origin_period / dev_lag / eval_date cells over an ibis expression (duckdb or polars backend), carrying grain, cumulative/incremental, and units metadata.
- Triangle
-
A reserving triangle over an ibis table expression.
- TriangleMeta
-
Triangle-level metadata. Carried through every transformation.
Triangle transforms & interop
Cumulative/incremental conversion, grain changes, as_of() backtest slicing, and lossless round-trips with chainladder-python and bermuda.
- Triangle.from_long()
- Triangle.from_chainladder()
- Triangle.to_chainladder()
- Triangle.from_bermuda()
- Triangle.to_bermuda()
- Triangle.to_cumulative()
- Triangle.to_incremental()
- Triangle.with_dev_grain()
- Triangle.with_origin_grain()
- Triangle.as_of()
- Triangle.latest_diagonal()
- Triangle.filter()
-
Filter rows with ibis deferred predicates, e.g.
t.filter(ibis._.lob == 'wkcomp'). - Triangle.select_fields()
- Triangle.to_wide()
-
Pivot one field to an origin x dev_lag matrix (materializes; for display).
- Triangle.to_pandas()
- Triangle.to_polars()
- Triangle.execute()
- Triangle.count()
- Triangle.with_expr()
-
New Triangle with a replaced expression and optional meta updates.
- Triangle.validate()
Gallery
Discover, retrieve, and fit reserving models through the GalleryEntry contract. Every entry - Bayesian, neural, or statistical - produces a PredictiveDistribution.
- gallery.list()
-
Names of all registered gallery entries.
- gallery.get
- gallery.fit
- gallery.GalleryEntry
Held-out evaluation
The four steps between a fitted entry and a leaderboard row: which cells a fit at as_of is scored on, one model’s arrays at those cells, the cross-model intersection, and the board.
- gallery.next_diagonal()
-
Cells that first become observable on the diagonal after
as_of. - gallery.CohortForecast
-
One model, one cohort, one cutoff, one field, at the held-out cells.
- gallery.Absence
-
Why an array is missing, from a closed vocabulary.
- gallery.align_panel()
-
Put every model on the SAME cells - per score - and report what fell out.
- gallery.leaderboard()
-
The board. One row per model, ordered by model name. No sort key.
- gallery.reserve_rows()
-
One row per cohort: predicted and actual reserve at the grid endpoint.
- gallery.SCORE_DIRECTION
- gallery.stack()
-
Fit stacking weights on one panel, build stacked forecasts at a later one.
Chain ladder & reserve risk
The distribution-free chain ladder (Mack 1993) and its run-off MSEP, plus the one-year claims development result - the Solvency II reserve-risk view. cdr_methods() is the option surface: which model generates next year’s diagonal, how the reserve is re-estimated once it exists, and what each route has actually been validated against.
- kernels.MackFit
-
A fitted distribution-free chain ladder on one cohort.
- kernels.fit_mack()
-
Fit the distribution-free chain ladder on a single-cohort Triangle.
- kernels.fit_mack_grid()
-
Fit Mack’s distribution-free chain ladder from a grid dict (the array entry point).
- kernels.cohort_grid_frame()
-
One cohort’s rows as a plain pandas frame, turned into the dense grid dict.
- kernels.simulate_ultimates()
-
Simulate FULL run-off ultimates from a fitted Mack model.
- kernels.cdr_methods()
-
Every way to get a one-year CDR, and the terms of each.
- kernels.get_cdr_method()
-
The
CDRMethoddescriptor for one route, or a KeyError naming the - kernels.one_year_cdr()
-
Merz-Wuthrich (2008) closed-form msep of the one-year CDR.
- kernels.simulate_one_year_cdr()
-
Actuary in the box: the one-year CDR distribution by re-reserving.
- kernels.rereserve()
-
(n_draws, n_w)one-year CDR draws from simulated next-diagonal values. - kernels.cdr_risk_measures()
-
VaR and TVaR of the one-year LOSS, from simulated CDR draws.
- kernels.CDRResult
-
One-year CDR uncertainty for one cohort, per accident year and in total.
- kernels.MackDiagonal
-
Next year’s diagonal from Mack’s conditional moments.
- kernels.ODPBootstrapDiagonal
-
Next year’s diagonal from an England-Verrall ODP residual bootstrap.
- gallery.GalleryDiagonal
-
Next year’s diagonal from a fitted gallery entry’s posterior predictive.
Tweedie GLM development
The kernel under methods.tweedie_glm: a Tweedie GLM fitted to a cumulative grid’s increments by iteratively reweighted least squares, numpy only, with no penalty.
- kernels.fit_tweedie_grid()
-
Fit a Tweedie GLM to the increments of a cumulative grid.
- kernels.TweedieSpec
-
What to fit: the distribution, the link, the design and the projection.
- kernels.TweedieFit
-
A fitted Tweedie GLM on one triangle’s increments.
Machine-learning development
The kernel under methods.ml_development: a random forest or gradient boosting (scikit-learn, from the ml extra) fitted to a cumulative grid’s cells over chainladder-python’s DevelopmentML design, each origin projected by its own fitted pattern.
- kernels.fit_ml_development_grid()
-
Fit a random forest or gradient boosting to a cumulative grid’s cells.
- kernels.MLDevelopmentSpec
-
What to fit: the estimator, its settings, the response and the design.
- kernels.MLDevelopmentFit
-
A fitted tree model on one triangle, and each origin’s projection.
Conventional point candidates
Chain ladder, Bornhuetter-Ferguson and Gluck’s generalized Cape Cod as fixed settings that can be refitted at successive information dates. A replay measures each candidate’s realized actual-versus-expected and the observed change in its fitted ultimate over one development period; selection picks a candidate on those historical outcomes alone, and the evaluation scores the frozen forecast against later terminal observations.
- kernels.fit_conventional()
-
Fit one cohort using only information stored on or before
as_of. - kernels.fit_conventional_grid()
-
Fit one cohort from a grid of plain arrays, with no Triangle and no database queries.
- kernels.conventional_grid()
-
Explicit CL/BF/GCC Cartesian grid; no implicit paper-specific defaults.
- kernels.ConventionalCandidate
-
Settings held fixed when a candidate is refitted at successive dates.
- kernels.ConventionalFit
-
A point forecast and the observations actually used to estimate it.
- kernels.replay_conventional()
-
Refit fixed candidates, then measure each successive observed diagonal.
- kernels.ConventionalReplay
-
Historical fits, origin-level outcomes, and explicit failures/exclusions.
- kernels.score_replay()
-
Equation 2: absolute-actual-weighted RMSE separately on each diagonal.
- kernels.select_conventional()
-
Choose the lowest mean diagonal RMSE over a complete historical window.
- kernels.ConventionalSelection
-
A decision based solely on replay outcomes available by
as_of. - kernels.evaluate_conventional()
-
Evaluate the frozen selected forecast at its declared terminal age.
- kernels.ConventionalEvaluation
-
Frozen forecasts against later terminal-age observations, in input units.
Tails
Development after the last observed age: a constant tail, or an exponential, inverse power or Weibull curve fitted to the link factors. A TailSpec goes on a ConventionalCandidate or into fit_mack_grid, where tail_variance gives the tail step’s sigma and standard error for Mack’s standard errors. apply_tail takes one row of factors per simulation too.
- kernels.TailSpec
-
A tail, held fixed like a
ConventionalCandidate. - kernels.apply_tail()
-
Apply a tail to link factors.
- kernels.tail_variance()
-
The tail step’s sigma and the tail factor’s standard error, for Mack.
Evaluation kernels
The unifying predictive-distribution output type, the cross-backend posterior-parity tooling, and the point-error metrics - which take the level errors are summed within as an argument, because summing before the absolute value is where one line’s overestimate cancels another’s underestimate.
- kernels.PredictiveDistribution
-
Sampled predictive distribution over a set of targets.
- kernels.ParityReport
-
Result of comparing one or more ported posteriors to a reference.
- kernels.compare_posteriors()
-
Compare each non-reference posterior in
idatastoidatas[reference]. - kernels.point_metrics()
-
Point-error metrics over aligned units of one level. See the module docstring.
- kernels.level_errors()
-
Sum
predictedandactualwithinleveland return one row per unit. - kernels.shrink_toward()
-
baseline + alpha * (point - baseline): a point pulled toward a baseline. - kernels.point_summary()
-
Point errors of a
PredictiveDistribution’s draw means against outcomes.
Residual calibration
Historical uncertainty for a point forecaster: apply it at earlier cutoffs, pool the standardised errors by unit size, and resample them around the final point.
- kernels.rolling_residuals()
-
Standardised forecast errors of a fixed forecaster at earlier cutoffs.
- kernels.calibrate()
-
Pool the named horizons’ errors by unit size and centre each pool.
- kernels.Calibration
-
Centred residual pools per size stratum; see the module docstring.
- kernels.calibrated_draws()
-
(n_draws, n_units):point + scale * resampled centred residual. - kernels.leave_one_out_coverage()
-
Coverage of intervals built for each calibration forecast from the OTHER
Wire format
The single place an ibnr result becomes bytes - one Arrow IPC stream per artifact, uncompressed by default, plus a one-way JSON summary for callers that cannot take the draws.
- kernels.to_arrow()
-
Serialize one ibnr result to an Arrow IPC stream.
- kernels.from_arrow()
-
Reconstruct whatever
to_arrow()wrote, dispatching onibnr.kind. - kernels.peek_kind()
-
The artifact type, read from the stream’s schema message.
- kernels.to_summary()
-
A JSON-safe digest for callers that cannot take the draws.
- kernels.CODEC_VERSION
- kernels.CONTENT_TYPE_ARROW
- kernels.CONTENT_TYPE_JSON
- kernels.DEFAULT_QUANTILES
Retrospective harness
Parallel company x line backtesting with staged sampler escalation - the compute seam behind the study scripts.
- kernels.harness.run_retro()
-
Run every task through the staged escalation, in parallel.
- kernels.harness.run_task()
-
Fit + score one task: the worker function. Never raises - a failure
- kernels.harness.RetroTask
-
One unit of work: fit one model to one company x line cohort as of a
- kernels.harness.SamplerSettings
-
One escalation stage’s MCMC budget.
- kernels.harness.ConvergenceGates
-
Pass/fail thresholds on an entry’s
convergence()diagnostics. - kernels.harness.precompile()
-
Compile the Stan program of every (given, else registered) entry that
- kernels.harness.default_max_workers()
-
Worker-pool size when the caller does not choose one: the