MetricStrategy

class empulse.metrics.MetricStrategy(name, direction)

Abstract base class for metric strategies.

This class defines the interface for metric strategies. Metric strategies are used to compute the metric value, gradient, and hessian.

Parameters:

namestr

Human-readable name of the strategy, surfaced through Metric.__name__.

directionDirection

Whether the user-facing metric value is to be maximized or minimized.

Attributes:

namestr

The name passed to the constructor.

directionDirection

The direction passed to the constructor.

abstractmethod build(tp_benefit, tn_benefit, fp_cost, fn_cost)

Compile the four cost-matrix expressions into the strategy’s scoring functions.

Called once by Metric at construction.

Parameters:

tp_benefitsympy.Expr

Benefit of a true positive.

tn_benefitsympy.Expr

Benefit of a true negative.

fp_costsympy.Expr

Cost of a false positive.

fn_costsympy.Expr

Cost of a false negative.

Returns:

MetricStrategy

The built strategy, to allow method chaining.

property capabilities

The set of Capability members this strategy supports.

Combines _capabilities with whatever optimal_threshold, optimal_rate, logit_objective, gradient_boost_objective and prepare_boost_objective this strategy overrides – see _capabilities_from_overrides. A caller should use this instead of isinstance(strategy, SomeConcreteStrategy) or calling a method and catching NotImplementedError.

gradient_boost_objective(y_true, y_score, **parameters)

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

Parameters:

y_truearray-like of shape (n_samples,)

The ground truth labels.

y_scorearray-like of shape (n_samples,)

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

**parametersfloat 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, 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.

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)

Compute the predicted positive rate to optimize the metric value.

Parameters:

y_truearray-like of shape (n_samples,)

The ground truth labels.

y_scorearray-like of shape (n_samples,)

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

**parametersfloat 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:

optimal_ratefloat

The optimal predicted positive rate.

optimal_threshold(y_true, y_score, **parameters)

Compute the classification threshold(s) to optimize the metric value.

i.e., the score threshold at which an observation should be classified as positive to optimize the metric. For instance-dependent costs and benefits, this will return an array of thresholds, one for each sample. For class-dependent costs and benefits, this will return a single threshold value.

Parameters:

y_truearray-like of shape (n_samples,)

The ground truth labels.

y_scorearray-like of shape (n_samples,)

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

**parametersfloat 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:

optimal_thresholdfloat | FloatNDArray

The optimal classification threshold(s).

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.

Deprecated since version Use: Capability.PRECOMPUTED_BOOST_OBJECTIVE not in strategy.capabilities instead.

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.

abstractmethod score(y_true, y_score, **parameters)

Compute the metric score or loss.

Parameters:

y_truearray-like of shape (n_samples,)

The ground truth labels.

y_scorearray-like of shape (n_samples,)

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

**parametersfloat 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:

scorefloat

The computed metric score or loss.

abstractmethod to_latex(tp_benefit, tn_benefit, fp_cost, fn_cost)

Return the LaTeX representation of the metric.

Parameters:

tp_benefitsympy.Expr

Benefit of a true positive.

tn_benefitsympy.Expr

Benefit of a true negative.

fp_costsympy.Expr

Cost of a false positive.

fn_costsympy.Expr

Cost of a false negative.

Returns:

str

The metric’s formula as a LaTeX string.