Validation

Actuarial validation toolkit for model comparison and calibration assessment. All functions accept raw numpy arrays and work with any model framework.

Charts

lift_chart(y_obs, y_pred, sample_weight=None, exposure=None, *, n_bins=10, ax=None)

Lift chart: observed vs predicted across equal-exposure quantile bins.

Parameters:

Name	Type	Description	Default
y_obs	array - like	Observed response values.	required
y_pred	array - like	Predicted response values.	required
sample_weight	array - like or None	Observation weights for aggregation.	None
exposure	array - like or None	Exposure measure for rate models. When provided, bins are equal-exposure quantiles and averages are exposure-weighted.	None
n_bins	int	Number of quantile bins.	10
ax	matplotlib Axes or None	If provided, plot onto this axes (figure in result will be None).	None

Returns:

Type	Description
LiftChartResult	Contains a bins DataFrame and an optional figure.

double_lift_chart(y_obs, y_pred_model, y_pred_current, sample_weight=None, exposure=None, *, n_bins=10, labels=('Actual', 'Model', 'Current'), ax=None)

CAS-style double lift chart (CAS RPM 2016 methodology).

Sorts by the ratio y_pred_model / y_pred_current, bins into equal-exposure quantiles, and plots three indexed series: Actual, Model, and Current — each indexed to its own overall average.

This is the standard actuarial double lift chart for comparing a new model against a current/baseline model on holdout data.

Parameters:

Name	Type	Description	Default
y_obs	array - like	Observed response values (frequency, severity, or loss ratio).	required
y_pred_model	array - like	New model predictions (holdout).	required
y_pred_current	array - like	Current/baseline/manual predictions (holdout).	required
sample_weight	array - like or None	Observation weights (case/frequency weights).	None
exposure	array - like or None	Exposure measure for rate models.	None
n_bins	int	Number of equal-exposure quantile bins.	10
labels	tuple of (str, str, str)	Display labels as (Actual, Model, Current). Each element names the corresponding series in the plot legend and axis labels.	('Actual', 'Model', 'Current')
ax	matplotlib Axes or None	If provided, plot onto this axes (figure in result will be None).	None

Returns:

Type	Description
DoubleLiftChartResult	Contains a bins DataFrame and an optional figure.

References

CAS RPM 2016, "Predictive Modeling — Lift and Double Lift Charts", https://www.casact.org/sites/default/files/presentation/rpm_2016_presentations_pm-lm-4.pdf

lorenz_curve(y_obs, y_pred, sample_weight=None, exposure=None, *, engine='matplotlib', ax=None)

Lorenz curve with Gini coefficient computation.

Parameters:

Name	Type	Description	Default
y_obs	array - like	Observed response values.	required
y_pred	array - like	Predicted response values.	required
sample_weight	array - like or None	Observation weights.	None
exposure	array - like or None	Exposure measure. When provided, the Lorenz curve uses cumulative exposure share on the x-axis.	None
engine	('matplotlib', 'plotly')	Plotting backend. "plotly" requires the optional plotly dependency.	"matplotlib"
ax	matplotlib Axes or None	If provided, plot onto this axes. Only valid with engine="matplotlib".	None

Returns:

Type	Description
LorenzCurveResult	Contains curve DataFrame, gini_model, gini_perfect, gini_ratio, and an optional figure.

loss_ratio_chart(y_obs, y_pred, sample_weight=None, exposure=None, *, n_bins=10, feature_values=None, feature_name=None, ax=None)

Loss ratio chart: observed vs predicted loss ratios per bin.

Parameters:

Name	Type	Description	Default
y_obs	array - like	Observed response values.	required
y_pred	array - like	Predicted response values.	required
sample_weight	array - like or None	Observation weights.	None
exposure	array - like or None	Exposure measure for rate models.	None
n_bins	int	Number of quantile bins.	10
feature_values	array - like or None	If provided, bin by this feature's values instead of predicted values.	None
feature_name	str or None	Label for the feature axis.	None
ax	matplotlib Axes or None	If provided, plot onto this axes.	None

Returns:

Type	Description
LossRatioChartResult	Contains a bins DataFrame and an optional figure.

Result types

LiftChartResult dataclass

Result from :func:lift_chart.

Attributes:

Name	Type	Description
bins	DataFrame	One row per quantile bin with columns: bin, exposure_share, observed, predicted, obs_pred_ratio.
figure	Figure or None	The generated figure, or None if an external ax was provided.

DoubleLiftChartResult dataclass

Result from :func:double_lift_chart.

Attributes:

Name	Type	Description
bins	DataFrame	One row per quantile bin with columns: bin, n_rows, exposure_sum, exposure_share, target_sum, actual_avg, model_avg, current_avg, actual_index, model_index, current_index, sort_score_min, sort_score_median, sort_score_max.
figure	Figure or None	The generated figure, or None if an external ax was provided.

LorenzCurveResult dataclass

Result from :func:lorenz_curve.

Attributes:

Name	Type	Description
curve	DataFrame	Lorenz curve data with columns: cum_exposure_share, cum_loss_share_ordered, cum_loss_share_model, cum_loss_share_perfect.
gini_model	float	Gini coefficient for the model ordering.
gini_perfect	float	Gini coefficient for perfect-foresight ordering.
gini_ratio	float	Normalised Gini: gini_model / gini_perfect.
figure	object or None	The generated matplotlib or Plotly figure, or None if an external matplotlib ax was provided.

LossRatioChartResult dataclass

Result from :func:loss_ratio_chart.

Attributes:

Name	Type	Description
bins	DataFrame	One row per quantile bin with columns: bin, exposure_share, observed, predicted.
figure	Figure or None	The generated figure, or None if an external ax was provided.