Skip to main content

kernels.cohort_grid_frame()

One cohort’s rows as a plain pandas frame, turned into the dense grid dict.

Usage

Source

kernels.cohort_grid_frame(
    df,
    *,
    dev_grain_months,
    units=None,
    loss_field=None,
    segment=None,
    measure
)

This is the array entry point to the chain-ladder fits: no Triangle and no database queries, just a pandas frame with three columns, one row per observed cell:

  • origin_period: the first day of the origin period. Dates, timestamps, a datetime64 column and ISO strings such as "2010-01-01" are all read as dates.
  • dev_lag: months from the start of the origin period, a whole multiple of dev_grain_months (the first cell of an annual triangle is at 12).
  • value: the amount in that cell, cumulative or incremental as the measure argument says.

The other arguments:

  • dev_grain_months: months per development step, 12 for an annual triangle.
  • measure: "cumulative" or "incremental", and required. It is written onto the grid as given, because a bare frame cannot show which one it holds; the fits that read the grid refuse anything but cumulative.
  • units, loss_field and segment: labels copied onto the grid for the caller’s own records. Nothing here checks them.

The result is a dict. The keys the array fits (kernels.fit_conventional_grid and kernels.fit_mack_grid) read are:

  • n_w, n_d: the number of origins and of development steps.
  • cum: a float array of shape (n_w, n_d), NaN where a cell is not observed. cum[i, j] is origin i at (j + 1) * dev_grain_months months.
  • obs_mask: a boolean array equal to ~isnan(cum).
  • latest_dev: an integer array, each origin’s last observed column.
  • origin_periods: the origins as dates, oldest first.
  • dev_grain_months, and the measure as passed in.

It also carries w and d (the 1-based origin and development index of every observed cell) and the labels above. A caller may build this dict by hand instead; both fits check it again before using it.

Refused, by name: a measure other than the two above, a dev_lag that is not positive or not on the declared grain, more than one row for the same cell, an origin with no observation at the first development step, and cells that do not form a run-off triangle. A run-off triangle has every origin observed from the first development step up to one common diagonal, or up to the last development step once that origin has run off. The check counts origins by position, so a missing origin period is accepted only where every origin before it has already run off.

The Triangle path to the same dict is kernels.contract.cohort_grid, which builds it through this function, and so does kernels.mack.fit_mack_many for each cohort of a multi-cohort triangle it has read once.