Skip to main content

kernels.fit_conventional_grid()

Fit one cohort from a grid of plain arrays, with no Triangle and no database queries.

Usage

Source

kernels.fit_conventional_grid(
    grid,
    candidate,
    *,
    premium=None,
)

The same estimator as fit_conventional(), giving the same factors, development proportions and ultimates for the same cells, but starting from arrays rather than a Triangle. It is meant for a service that fits one small triangle per request, where the database queries inside fit_conventional() take longer than the fit itself. Importing this module does not import ibis or pandas; the result’s three tables are pandas DataFrames, so this function imports pandas when it builds them. ibnr.methods returns the same numbers as Arrow tables without pandas.

grid is the one-cohort dict that kernels.cohort_grid_frame builds from a pandas frame with columns origin_period, dev_lag (months) and value; its page lists the keys this function reads. It must hold cumulative losses on a run-off triangle. The caller’s dict is never changed.

premium is needed for "bf" and "gcc" candidates only. It is keyed by origin period, never by position, so it cannot be lined up against the wrong origin: a dict, or a pandas Series indexed by origin period. Keys may be dates, timestamps, numpy datetime64 values or ISO strings, and amounts must be numbers. A grid can also carry premium itself, as a float array under the key "premium" in origin order; then this argument must be left out.

The information date is not an argument; it is read from the grid. It is the evaluation date of the latest observed cell, which by this package’s convention is the day before the origin period plus dev_lag months (origin 1988-01-01 at 12 months is 1988-12-31). It is returned as ConventionalFit.as_of. Origin periods must therefore be the first day of their period.

Refused, by name:

  • a grid missing one of the keys it reads, or whose arrays disagree with each other or have the wrong type: cum not a float array of shape (n_w, n_d), obs_mask not a boolean array equal to ~isnan(cum), latest_dev not an integer array of each origin’s last observed column, n_w, n_d or dev_grain_months not whole numbers, origin_periods of the wrong length or not in increasing order;
  • origin periods that are not dates or not the first day of a month;
  • cells that are not a run-off triangle, or still-developing origins whose latest cells are on different dates;
  • a grid measure other than "cumulative";
  • origin periods not one development step apart. The smallest gap between neighbouring origins must equal the development step and every gap must be a whole number of steps. A missing origin period is allowed only where every origin before it has already reached the last development step (the run-off check counts origins by position), and GCC then measures its distances in real origin periods across the gap. Quarterly origins on an annual step are refused, and so is a grid whose origins are all two or more steps apart, because a grid cannot tell an annual axis with gaps from a two-year one;
  • premium passed with a "cl" candidate (it would never be read), given both here and on the grid, missing for a "bf" or "gcc" candidate, not keyed by origin, with a key that is not a date, with two keys that are the same origin once read as dates, with an amount that is not a number, missing an origin of the grid, or carrying an origin the grid does not have (filter it first). Premium on the grid must be a float array with one value per origin. Premium must also be finite and positive, which the estimator checks.

Everything else (the horizon, exclusions, factor fallbacks) is refused exactly as fit_conventional() refuses it.