MaxProfit

class empulse.metrics.MaxProfit(integration_method='auto', n_mc_samples_exp=16, random_state=None, alpha=1.0)

Strategy for the Expected Maximum Profit (EMP) metric.

Parameters:

integration_method{‘auto’, ‘quad’, ‘monte-carlo’, ‘quasi-monte-carlo’}, default=’auto’

The integration method to use when the metric has stochastic variables.

• If 'auto', the integration method is automatically chosen based on the number of stochastic variables, balancing accuracy with execution speed. For a single stochastic variable, piecewise integration is always used, splitting the support at the points where the optimal operating point changes; this is exact when the profit function is polynomial in the stochastic variable and its distribution supports closed-form partial moments, and numerically integrated otherwise. For two or more stochastic variables, ‘quasi-monte-carlo’ is used if every distribution is supported, and ‘monte-carlo’ otherwise.

• If 'quad', the metric is integrated using the quad function from scipy. Be careful, as this can be slow for more than 2 stochastic variables.

• If 'monte-carlo', the metric is integrated using a Monte Carlo simulation. The monte-carlo simulation is less accurate but faster than quad for many stochastic variables.

• If 'quasi-monte-carlo', the metric is integrated using a Quasi Monte Carlo simulation. The quasi-monte-carlo simulation is more accurate than monte-carlo but only supports a few distributions present in sympy.stats:

  • sympy.stats.Arcsin

  • sympy.stats.Beta

  • sympy.stats.BetaPrime

  • sympy.stats.BoundedPareto

  • sympy.stats.Chi

  • sympy.stats.ChiSquared

  • sympy.stats.Dagum

  • sympy.stats.Erlang

  • sympy.stats.ExGaussian

  • sympy.stats.Exponential

  • ExponentialPower (not published in SymPy’s own documentation, so no link is possible)

  • sympy.stats.FDistribution

  • sympy.stats.Frechet

  • sympy.stats.Gamma

  • sympy.stats.GammaInverse

  • GaussianInverse (not published in SymPy’s own documentation, so no link is possible)

  • sympy.stats.Gompertz

  • sympy.stats.Laplace

  • sympy.stats.Logistic

  • sympy.stats.LogLogistic

  • sympy.stats.LogNormal

  • sympy.stats.Lomax

  • sympy.stats.Maxwell

  • sympy.stats.Moyal

  • sympy.stats.Nakagami

  • sympy.stats.Normal

  • sympy.stats.Pareto

  • sympy.stats.PowerFunction

  • sympy.stats.RaisedCosine

  • sympy.stats.Rayleigh

  • sympy.stats.Reciprocal

  • sympy.stats.StudentT

  • sympy.stats.Trapezoidal

  • sympy.stats.Triangular

  • sympy.stats.Uniform

  • sympy.stats.Weibull

  • sympy.stats.WignerSemicircle

n_mc_samples_expint, default=16

2**n_mc_samples_exp is the number of (Quasi-) Monte Carlo samples to use when integration_method == 'monte-carlo'. Increasing the number of samples improves the accuracy of the metric estimation but slows down the speed. This argument is ignored when the integration_method == 'quad'.

random_stateint | np.random.Generator | None, default=None

The random state to use when integration_method == 'monte-carlo' or integration_method == 'quasi-monte-carlo'. Determines the points sampled from the distribution of the stochastic variables. This argument is ignored when integration_method == 'quad'.

alphafloat, default=1.0

Temperature of the smooth sigmoid approximation used by logit_objective and gradient_boost_objective to make the (otherwise piecewise-constant) TPR/FPR differentiable. Held constant here; to anneal it during logistic-regression training, pass an alpha_schedule to the optimizer instead (e.g. SGD, Adam, RMSProp) - ExponentialSchedule and StepSchedule both support a growth factor with a max_value ceiling.

Notes

Unlike Cost and Savings, this strategy does not take instance-dependent costs/benefits into account: the EMP framework is defined on the aggregate class priors and the score/rate/threshold it computes are global, classifier-level quantities, not per-instance ones. Any array-like parameter you pass is silently reduced to its mean before use - passing an instance-dependent array gives the exact same result as passing that array’s mean as a plain float.

build(tp_benefit, tn_benefit, fp_cost, fn_cost)

Build the metric strategy.

property capabilities

The set of Capability members this strategy supports.

LOGIT_OBJECTIVE and BOOST_OBJECTIVE are only present once build has run and picked a deterministic or BasePositiveDistribution stochastic score function – the same condition logit_objective and gradient_boost_objective check before raising NotImplementedError. Before build, or for any other stochastic distribution, neither is present.

gradient_boost_objective(y_true, y_score, **parameters)

Compute gradient and hessian for boosting with MaxProfit.

Automatically handles deterministic and stochastic piecewise integrals.

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

Build the prepared logit-gradient objective for the current metric configuration.

Uses the Envelope Theorem combined with a smooth sigmoid approximation of the ROC curve to derive an analytically differentiable proxy for the Expected Maximum Profit.

Only supported for deterministic metrics or metrics with one stochastic variable following a distribution with positive support.

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 value is used as-is (class-dependent).

• If array-like, the mean of the values is used: this strategy does not take instance-dependent costs/benefits into account (see the class docstring), so passing an array gives the same result as passing that array’s mean directly.

Returns:

logistic_objectiveCallable[[NDArray], tuple[float, NDArray]]

A function that takes logistic regression weights as input and returns the negated metric value and its gradient (negated for minimization). The function signature is: logistic_objective(weights) -> (value, gradient).

Raises:

NotImplementedError

If the metric is neither purely deterministic nor a BasePositiveDistribution stochastic variant.

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 value is used as-is (class-dependent).

• If array-like, the mean of the values is used: this strategy does not take instance-dependent costs/benefits into account (see the class docstring), so passing an array gives the same result as passing that array’s mean directly.

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 value is used as-is (class-dependent).

• If array-like, the mean of the values is used: this strategy does not take instance-dependent costs/benefits into account (see the class docstring), so passing an array gives the same result as passing that array’s mean directly.

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.

score(y_true, y_score, **parameters)

Compute the maximum profit score.

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 value is used as-is (class-dependent).

• If array-like, the mean of the values is used: this strategy does not take instance-dependent costs/benefits into account (see the class docstring), so passing an array gives the same result as passing that array’s mean directly.

Returns:

scorefloat

The maximum profit score.

to_latex(tp_benefit, tn_benefit, fp_cost, fn_cost)

Return the LaTeX representation of the metric.