EmpiricalMaxProfit#

class empulse.metrics.EmpiricalMaxProfit[source]#

Strategy for the (empirical) maximum profit found by ranking samples by predicted score.

Unlike MaxProfit, which searches for the profit-maximizing threshold inside the integral over any stochastic variables (via a closed-form profit function of the population’s true/false positive rates), EmpiricalMaxProfit first simplifies any stochastic variable to its mean, and only then searches for the profit-maximizing threshold, empirically: samples are ranked by predicted score, the cumulative profit of targeting (predicting positive for) the top-ranked fraction is tracked per sample (rather than through population-level true/false positive rates), and the maximum of that curve is the metric’s score.

Because the threshold search happens per-sample rather than through population aggregates, this strategy naturally supports instance-dependent (array-like) costs and benefits, unlike MaxProfit.

EmpiricalMaxProfit does not support use as a model training objective (no logit_objective or gradient_boost_objective): the profit-maximizing threshold is found via an empirical argmax over the ranked samples, which is piecewise-constant (and therefore not differentiable) in the predicted scores.

See also

empb_score : the underlying metric function.

build(tp_benefit, tn_benefit, fp_cost, fn_cost)[source]#

Build the metric strategy.

gradient_boost_objective(y_true, y_score, **parameters)#

Compute the gradient of the metric with respect to gradient boosting instances.

Parameters:
y_true: array-like of shape (n_samples,)

The ground truth labels.

y_score: array-like of shape (n_samples,)

The predicted labels, probabilities, or decision scores (based on the chosen metric).

parameters: float or array-like of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric. If any parameter is a stochastic variable, you should pass values for their distribution parameters. You can set the parameter values for either the symbol names or their aliases.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
gradientNDArray of shape (n_samples,)

The gradient of the metric loss with respect to the gradient boosting weights.

hessianNDArray of shape (n_samples,)

The hessian of the metric loss with respect to the gradient boosting weights.

logit_objective(features, y_true, C, l1_ratio, soft_threshold, fit_intercept, **parameters)#

Compute the logit loss and its gradient with respect to the logistic regression weights.

Parameters:
featuresNDArray of shape (n_samples, n_features)

The features of the samples.

y_trueNDArray of shape (n_samples,)

The ground truth labels.

Cfloat

Regularization strength parameter. Smaller values specify stronger regularization.

l1_ratiofloat

The Elastic-Net mixing parameter, with range 0 <= l1_ratio <= 1. l1_ratio=0 corresponds to L2 penalty, l1_ratio=1 to L1 penalty.

soft_thresholdbool

Indicator of whether soft thresholding is applied during optimization.

fit_interceptbool

Specifies if an intercept should be included in the model.

parametersfloat or NDArray of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric. If any parameter is a stochastic variable, you should pass values for their distribution parameters. You can set the parameter values for either the symbol names or their aliases.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
logistic_objectiveLogitObjective

A class that implements the logit loss and its gradient.

optimal_rate(y_true, y_score, **parameters)[source]#

Compute the fraction of samples that should be targeted (predicted positive) to maximize profit.

Parameters:
y_true: array-like of shape (n_samples,)

The ground truth labels.

y_score: array-like of shape (n_samples,)

The predicted labels, probabilities, or decision scores used to rank the samples.

parameters: float or array-like of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
optimal_rate: float

The optimal predicted positive rate.

optimal_threshold(y_true, y_score, **parameters)[source]#

Compute the score threshold above which a sample should be targeted to maximize profit.

Parameters:
y_true: array-like of shape (n_samples,)

The ground truth labels.

y_score: array-like of shape (n_samples,)

The predicted labels, probabilities, or decision scores used to rank the samples.

parameters: float or array-like of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
optimal_threshold: float

The optimal classification threshold.

prepare_boost_objective(y_true, **parameters)#

Compute the gradient’s constant term of the metric wrt gradient boost.

Parameters:
y_trueNDArray of shape (n_samples,)

The ground truth labels.

parametersfloat or NDArray of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric. If any parameter is a stochastic variable, you should pass values for their distribution parameters. You can set the parameter values for either the symbol names or their aliases.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
gradient_constNDArray of shape (n_samples, n_features)

The constant term of the gradient.

property requires_dynamic_boost_objective#

Whether gradients must be recomputed from the metric each boosting round.

True for strategies whose per-sample loss is not linear in the predicted probability (e.g. LogCost) or that need the current round’s scores to locate a threshold (e.g. MaxProfit); such strategies cannot use the precomputed constant returned by prepare_boost_objective.

score(y_true, y_score, **parameters)[source]#

Compute the empirical maximum profit.

Parameters:
y_true: array-like of shape (n_samples,)

The ground truth labels.

y_score: array-like of shape (n_samples,)

The predicted labels, probabilities, or decision scores used to rank the samples.

parameters: float or array-like of shape (n_samples,)

The parameter values for the costs and benefits defined in the metric. If any parameter is a stochastic variable, you should pass values for their distribution parameters; the stochastic variable is replaced by its mean before computing the metric. You can set the parameter values for either the symbol names or their aliases.

  • If float, the same value is used for all samples (class-dependent).

  • If array-like, the values are used for each sample (instance-dependent).

Returns:
score: float

The empirical maximum profit.

to_latex(tp_benefit, tn_benefit, fp_cost, fn_cost)[source]#

Return the LaTeX representation of the metric.