Models and evaluation API

Per-segment observed vs predicted pure premium, exposure, and O/P ratio.

y_true = claim_amount, y_pred = predicted pure premium, sample_weight = exposure. When groups is None, segments are deciles of predicted risk, exposure-weighted when sample_weight is supplied. Otherwise groups is an array-like of one segment label per row; NaN labels form their own segment (dropna=False). Columns: group, exposure, claim_amount, predicted_claim_amount, observed_pure_premium, predicted_pure_premium, o_p_ratio; plus claim_count when provided. Constant predictions form one real group, including without weights.

Per-decile observed pure premium ordered by the pred_a / pred_b ratio.

Policies are bucketed into exposure-weighted deciles of the ratio (high ratio = A predicts a higher rate relative to B), and per decile the table reports mean ratio, exposure, observed pure premium, and predicted pure premium for both A and B. Compare each predicted rate with observations within each ratio group; rising observations alone cannot select a model. Extreme ratio groups contain the largest relative disagreements, whose credibility depends on exposure and claims. Rates are absolute, not normalized by portfolio means. Use azoic.plots.plot_double_lift to render.

Both predictions are floored at _RATIO_EPS to avoid division-by-zero when a GBM objective returns exact zeros (Poisson on never-claimed rows). Generated model columns must be distinct and must not match reserved output columns (for example, label_a="observed" is invalid). Each segment must sum to at least one day of exposure, as in calibration and one-way tables.

Exposure-weighted concentration Gini (actuarial low-to-high convention).

y_true is aggregate claim amount, y_pred is predicted rate, and sample_weight is exposure (unit exposure when omitted). Order by ascending prediction and integrate cumulative claim share C(u) against cumulative exposure share u: G = 1 - 2 * integral(C(u), u=0..1). This is twice the signed area from the curve to the diagonal, within [-1, 1] for non-negative claims and positive exposure. Negative values indicate claims concentrated toward lower predictions; zero need not imply random predictions. Observed-rate ordering gives a hindsight upper bound, generally below one, equal to exposure-weighted inequality Gini.

Pairwise absolute-difference inequality Gini measures observed-rate dispersion independently of predictions. This implementation instead integrates tied-score blocks, equivalently the Frees-Meyers-Cummings midrank formula. Ties are independent of row order; positive scaling preserves Gini. Returns 0 when total claims or total exposure is 0.

Return the ascending concentration curve plus the Gini.

exposure_pct and claims_pct both start at 0.0 and end at 1.0, suitable for direct plotting. Policies are ordered by predicted rate, with equal scores aggregated before integration. The curve may cross the diagonal; Gini is twice its signed area to that diagonal. A lower curve dominates another only when it is nowhere above it.

Per-level observed vs predicted pure premium for one feature.

Buckets rows by feature. Categorical / low-cardinality features are kept at their actual level (grouped levels from AutoGrouper are preserved as-is, including declared ordered-category order). Numeric features with n_bins=None get one level per unique raw value (natural-value one-way on test rows: driver age has as many points as distinct values); an integer n_bins exposure- weight quantiles numeric features into n_bins bins for near- continuous features like density.

y_true = claim_amount, y_pred = predicted pure premium (rate), sample_weight = exposure. Output columns:

level, level_label, level_center, exposure, claim_amount, predicted_claim_amount, observed_pure_premium, predicted_pure_premium, o_p_ratio.

level is the grouping key (integer code for numeric binned, raw value for numeric unique-value mode and categorical). level_label is a human-readable label (bin interval [a, b] for quantiled numeric, the actual level otherwise). level_center is the exposure-weighted mean of the raw feature within the bin (quantiled numeric only); the raw value itself in unique-value mode; NaN for categorical or missing values. Numeric missing rows retain their totals as Missing with an undefined centre, and their exposure does not affect bin boundaries.

Portfolio observed/predicted pure-premium ratio (1.0 = perfect level).

observed = sum(claim_amount) / sum(exposure) predicted = sum(pure_premium * exposure) / sum(exposure)

Return exposure-weighted diagnostics for each naturally sorted period.

y_true is aggregate claim amount, y_pred is predicted pure premium, and sample_weight is exposure. The fixed-power Tweedie deviance and period-relative :math:D^2 use power=1.5. D^2 is NaN when the period's exposure-weighted observed-mean prediction has zero deviance.

All inputs must be non-empty, one-dimensional, equal-length arrays without missing periods. Claim amounts must be non-negative and finite; predictions and exposures must be positive and finite.

Apply the azoic chart style (fivethirtyeight base + CVD-safe overrides).

Stable Okabe-Ito color per model name, consistent across all charts.

Hexbin density of observed vs predicted rates with a residual panel.

y_true is aggregate claim amount, y_pred is predicted pure-premium rate, and sample_weight is exposure. Observed amounts are divided by exposure before plotting; omitted exposure means unit exposure. Left panel: observed rate on x, predicted rate on y, y=x dashed reference. Right panel: rate residuals (observed − predicted) vs predicted rate with a zero reference. Density colouring is exposure-weighted (Σ exposure per hex) when supplied, otherwise log counts; the two panels get independent colorbars. cividis by default (CVD-safe). Inputs must be finite, one-dimensional, and equal-length; claims must be non-negative and exposure strictly positive for rate division.

Interpret credible exposure-weighted grouped mean residuals, not the densest band in zero-heavy outcomes. A constant non-zero mean residual indicates an additive discrepancy. If observed rate equals c * y_pred, residuals equal (c - 1) * y_pred: a slope can be purely multiplicative and removable by one factor. Review remaining curvature only after level.

logy=True uses a log y axis for positive predictions and a symmetric log (symlog) y axis for signed residuals, with Matplotlib's default linear threshold of 2 around zero. logy=False keeps linear y axes. Callers can adjust the axes after plotting. bins="log" controls density colour independently of the residual axis scale.

Scatter of observed vs predicted pure premium per segment.

table is the output of azoic.metrics.calibration_table. Point size is proportional to segment exposure; the dashed y=x line is perfect calibration. The decile-level observed-vs-paired view lives in :func:plot_lift.

Per-decile observed pure premium, ordered by the pred_a / pred_b ratio.

table is the output of azoic.metrics.double_lift_table. Three lines: observed (grey o-), predicted A (s--), predicted B (^:), one color per model, per ratio decile (mean ratio on tick labels). Compare each prediction with observations within each ratio group; observed direction alone cannot select a model. Extreme groups capture the largest relative disagreements; check their exposure and claims credibility. Curves show absolute rates, without normalization by portfolio means. Stand-alone draws a bottom exposure panel; embedded grids get background bars.

Observed vs predicted pure premium per exposure-balanced decile.

table is the output of azoic.metrics.calibration_table (deciles of predicted risk by default). Observed is the grey o- line, predicted the model-colored s-- line: the two should track in level (calibration) while observed rises with the decile (ranking); crossings expose deciles where the model over- or under-prices. Translucent background bars show the exposure share per decile (sklearn-example style).

Plot exposure-vs-claims concentration curves, one color per model.

y_pred is a single prediction array or a mapping {model_name: predictions}. The diagonal (random ranking) is drawn exactly once; with show_oracle=True the oracle ranks by observed rate (aggregate claims divided by exposure; omitted weights mean unit exposure). Aggregate claims and exposure still determine the cumulative shares. This hindsight ranking bound is not a deployable model and need not have Gini one. It is overlaid once as a grey dash-dot reference. Curves are sorted from safest to riskiest (ascending prediction). Gini, shown in the legend, is twice the signed area from each curve to the diagonal; even a positive-Gini curve can cross the diagonal. Shading shows the area, not twice its value.

Per-level observed vs predicted pure premium with the exposure layout.

Use the output of azoic.metrics.one_way_table. With n_bins=None the table has one level per unique value (natural numeric axis: driver age has as many points as distinct test values). If any centre is missing, all groups use labelled positions so the missing segment remains visible. Observed is the grey o- line, predicted the model-colored s-- line. Stand-alone (ax=None, default exposure="panel") a bottom exposure-share panel is drawn via subplot_mosaic; pass exposure="background" when embedding in a caller grid to underlay translucent exposure bars instead.