Calibration#

Rake#

Weight calibration with exact and approximate balance constraints.

Rake solves the single-group calibration problem, minimizing a Distance penalty subject to equality, imbalance, weight-cap and design-effect constraints. Joint treatment/control calibration lives in joint_calibrator, which builds on this module.

class pyrake.calibration.rake.Rake(distance, X, mu, Z=None, nu=None, psi=None, phi=None, min_weight=0.0, max_weight=None, constrain_mean_weight_to=1.0, settings=None, engine='ipm')[source]#

Bases: object

Calibrated weights with exact and approximate covariate balance.

Solves problems of the form:

minimize    D(w, v)
subject to  (1/M) Xᵀw = μ,
            ‖(1/M) Zᵀw - ν‖∞ ≤ ψ (optional),
            (1/M) ‖w‖₂² ≤ φ (optional),
            w ≥ min_weight,

with optional constraints on max covariate imbalance and on the mean of the weights.

Parameters:
  • distance (Distance) – Distance object representing distance from baseline weights.

  • X (npt.NDArray[np.float64]) – Matrix of covariates for which we desire exact balance.

  • mu (npt.NDArray[np.float64]) – Vector of mean covariate values in the target population corresponding to X.

  • Z (npt.NDArray[np.float64], optional) – Matrix of covariates for which we desire approximate balance.

  • nu (npt.NDArray[np.float64], optional) – Vector of mean covariate values in the target population corresponding to Z. Required when Z is specified.

  • psi (float or list[float], optional) – Bound on maximum covariate imbalance. See Notes. Defaults to 1.5 / sqrt(M), following guidance from (Cochran and Chambers, 1965, §3.1).

  • phi (float) – Constraint on mean squared weight.

  • min_weight (float or list[float], optional) – Lower bound on weights. Defaults to 0.

  • max_weight (float or list[float] or None, optional) – Upper bound on weights (a “weight cap”). A common use is to cap the influence of any single response: e.g. max_weight=20 prevents one observation from driving the estimate. None (the default) disables the upper bound. Like min_weight, may be scalar (broadcasts to all components) or a vector of per-component caps; vectors are particularly useful when jointly calibrating (the cap can vary by group).

  • constrain_mean_weight_to (float or None, default=1) – If not None, add a constraint that the average weight must equal constrain_mean_weight_to, which must be strictly positive. The default is an average weight of 1. Another common option is for the average weight to equal the average baseline weight. If no such constraint is desired, manually specify constrain_mean_weight_to=None.

  • settings (OptimizationSettings) – Optimization settings.

Notes

Three levels of balance are supported here. The lowest level implicitly relies on the balancing property of propensity scores: inverse weighting approximately balances all covariates used to fit the models, all interactions, higher order moments, etc. But this is only true asymptotically; with finite sample sizes, some imbalance may remain.

The next level is a constraint on the maximum imbalance. For covariates corresponding to the inputs Z and nu, the vector of covariate imbalances, after weighting, is (1/M) Zᵀw - ν. We want these imbalances to be close to zero, but not necessarily exactly zero. Even a true random sample would have some chance imbalances. The ℓ∞ constraint allows us to achieve an adjustment strategy that mimics a random sample.

When we assess covariate balance (using the tools in visualizations.py), we plot z statistics: adjusted sample mean minus population mean divided by √M times the population standard deviation. If we whiten Z and nu (divide by the population standard deviation), which we typically recommend to put all covariates on a common scale, then setting psi to, say 1.96 / √M will constrain covariate imbalances to be not-stat-sig at level 0.05. But (Cochran and Chambers, 1965, §3.1) emphasizes bias can occur even without stat sig differences in covariates. Their recommendation is equivalent to setting psi = 1.5 / √M, which is the default here.

The highest level is to force the adjusted sample mean to match the population mean exactly. This can typically only be done for a few covariates without drastically inflating the variance.

We thus recommend having a strong point of view on the covariates that are most important for predicting the response. Use propensity scores to balance all covariates approximately; balance the means of the more important covariates using the ℓ∞ constraint; balance exactly the means only of the most important covariates.

In a sense, the ideal weight to use is (M/N) / π, where N is the population size and π the true propensity score. That yields unbiased estimates, but of course requires known propensity scores. Weights that are less than (M/N) correspond to propensity scores > 1, which are impossible a priori. Thus, weights should generally never be less than M/N, which can be incorporated into the optimization problem using the min_weight argument.

min_weight and psi can both be vector arguments. This is particularly helpful when jointly calibrating weights for treatment and control groups. In this case, min_weight for the control (treated) observations should be the control (treated) sample size divided by the population size, so different bounds should be specified for the two groups. For joint calibration, we may have up to 3 groups of imbalance constraints, comparing treatment and control (internal validity), comparing control to the target population (external validity), and comparing treatment to the target population (external validity). The two sets of external validity constraints would use, e.g. 1.5 / sqrt(control sample size) or 1.5 / sqrt(treated sample size), while the internal validity constraint would use

1.5 * sqrt(1 / (control sample size) + 1 / (treated sample size)),

corresponding to a 2 sample z test.

References

  • Cochran, William Gemmell and Chambers, S. Paul, The Planning of Observational Studies of Human Populations, Journal of the Royal Statistical Society, 1965.

solve(x0=None)[source]#

Dispatch to the configured solver engine.

engine='ipm' (default) routes through Cvxium’s BarrierSolver; engine='pd' dispatches through PrimalDualSolver. Both consume the same cached Problem and handle equality feasibility themselves – the barrier projects a supplied x0 onto the manifold and runs its structured Phase I; PD’s infeasible-start step drives the equality residual to zero.

When x0 is None it defaults – for BOTH engines – to a domain-informed warm start: self.distance.v when defined (the Distance’s reference weights, e.g. KLDivergence(v=...)) else np.full(M, 1.0), clipped into [min_weight, max_weight] (the bare default can fall outside the box, e.g. when max_weight < 1.0 or when self.distance.v itself does). See _default_x0. A user-supplied x0 is passed through unchanged.

Parameters:

x0 (npt.NDArray[np.float64] | None) – Starting weights, or None for the domain-informed default.

Returns:

res – The solver result; res.solution is the weight vector of length M.

Return type:

SolveResult

property equality_layer#

Return the cached EqualityConstraintLayer for the (A, b) equality system.

Use this when constructing Phase I solvers that share the same equality system (e.g. the Pareto-frontier corner solvers). Reusing the cached layer preserves the EqualityConstraintLayer.svd_A() cache across Phase I builds; constructing a fresh layer per call site forces an SVD recompute and defeats that cache.

Returns:

layer – The cached (A, b) equality layer.

Return type:

EqualityConstraintLayer

update_phi(phi=None)[source]#

Update phi, mostly for EfficientFrontier.

Rebuilds the cached Problem so its SquaredNormConstraintLayer membership (present only when phi is set) matches the new phi.

Parameters:

phi (float | None) – New design-effect bound, or None to drop the constraint.

update_psi(psi=None)[source]#

Update the imbalance tolerance, rebuilding the cached Problem.

The sibling of update_phi, and necessary for the same reason: Problem is assembled once at construction, so assigning self.psi alone leaves solve running against the band the calibrator was built with. Used by solve_with_fallback when the external band is chosen from the frontier’s knee rather than requested up front (frontier.solve_with_knee_fallback).

Parameters:

psi (float | list[float] | npt.NDArray[np.float64] | None) – New imbalance band, or None to drop the imbalance layer.

Joint Calibration#

Joint calibration of treatment/control weights with internal validity.

JointCalibrator extends Rake to calibrate two experiment groups at once, trading each group’s external validity against variance while holding the groups’ internal validity fixed. FallbackOptimizationResult labels which constraint the fallback cascade had to relax.

class pyrake.calibration.joint_calibrator.FallbackOptimizationResult(result, fallback_message, fallback_status, m1=0, frontier=None, psi=None, relaxed_rows=(), band_scales=<factory>)[source]#

Bases: object

Result of JointCalibrator.solve_with_fallback.

Composes the underlying SolveResult with the calibration-specific fallback label. fallback_status is a separate axis from the solver’s own SolveResult.status: it records which constraint the cascade had to relax, not whether a given solve converged.

Fields:
  • result (SolveResult) – The underlying solve; result.solution is the weight vector (dimension M1 + M2).

  • fallback_message (str) – What kind of solution was achieved.

  • fallback_status (int) – Numeric status code: 0 = full solution, 1 = design effect minimized (but not to the level desired), 2 = external validity relaxed on the constraints that could not be met, 3 = internal validity relaxed on the constraints that could not be met, 4 = external validity deliberately relaxed to the frontier’s knee (the desired band was attainable and was declined in exchange for effective sample size; see frontier.solve_with_knee_fallback).

  • m1 (int) – Length of block 1 (control), i.e. the split point of the combined weight vector: solution[:m1] are the control weights and solution[m1:] the treatment weights.

  • psi (npt.NDArray[np.float64] or None) – The imbalance band the weights were calibrated to, one entry per row of the assembled imbalance constraints (external control, external treatment, internal). Equal to the calibrator’s psi unless a layer was relaxed, in which case the rows that could not be met carry what they achieved. None when there are no imbalance constraints.

  • relaxed_rows (tuple[int, …]) – Indices, among the assembled imbalance rows, of those the weights leave outside their requested band – the rows that absorbed what could not be balanced. Empty unless a layer was relaxed.

  • band_scales (dict[str, float]) – The factor by which a layer’s requested band was widened, keyed by the layer (“internal validity”, “external validity”). A band is widened only when it is too tight for the constraints that could each meet it to all do so at once; see JointCalibrator.solve_with_fallback. Empty when no band was widened.

property solution#

Return the weight vector (delegated to the underlying solve).

Returns:

w – The combined weight vector, of length M1 + M2.

Return type:

npt.NDArray[np.float64]

property control_effective_sample_size#

Return Kish’s effective sample size of the control (block 1) weights.

Returns:

n_eff – The effective sample size of solution[:m1].

Return type:

float

property treatment_effective_sample_size#

Return Kish’s effective sample size of the treatment (block 2) weights.

Returns:

n_eff – The effective sample size of solution[m1:].

Return type:

float

property combined_effective_sample_size#

Return Kish’s effective sample size of the pooled weights.

Returns:

n_eff – The effective sample size of the control + treatment weights.

Return type:

float

static from_result(result, fallback_message, fallback_status, m1, psi=None)[source]#

Wrap a SolveResult with a fallback-path label.

Parameters:
  • result (SolveResult) – The underlying solve.

  • fallback_message (str) – What kind of solution was achieved.

  • fallback_status (int) – Numeric status code; see the class docstring.

  • m1 (int) – Length of block 1 (control).

  • psi (npt.NDArray[np.float64] | None) – The imbalance band the weights were calibrated to, or None when there are no imbalance constraints.

Returns:

out – The labeled result.

Return type:

FallbackOptimizationResult

class pyrake.calibration.joint_calibrator.JointCalibrator(distance, X1=None, X2=None, X3=None, X4=None, mu1=None, mu2=None, Z1=None, Z2=None, Z3=None, Z4=None, nu1=None, nu2=None, psi1=None, psi2=None, psi3=None, phi=None, min_weight1=0.0, min_weight2=0.0, max_weight1=None, max_weight2=None, constrain_mean_weight1_to=1.0, constrain_mean_weight2_to=1.0, settings=None, engine='ipm')[source]#

Bases: Rake

Jointly calibrated weights for treatment and control groups.

Solves problems of the form:

minimize    D([w1, w2], [v1, v2])
subject to  (1/M1) X1ᵀw1 = μ1                                 (external validity)
            (1/M2) X2ᵀw2 = μ2                                 (external validity)
            (1/M1) X3ᵀw1 = (1/M2) X4ᵀw2                       (internal validity)
            ‖(1/M1) Z1ᵀw1 - ν1‖∞ ≤ ψ1                         (external validity)
            ‖(1/M2) Z2ᵀw2 - ν2‖∞ ≤ ψ2                         (external validity)
            ‖(1/M2) Z4ᵀw2 - (1/M1) Z3ᵀw1‖∞ ≤ ψ3               (internal validity)
            (1/(M1 + M2)) (‖w1‖₂² + ‖w2‖₂²) ≤ φ
            w1 ≥ min_weight1
            w2 ≥ min_weight2

The use case is calibrating weights for treatment and control groups at the same time, to achieve internal and external validity.

Parameters:
  • X1 (npt.NDArray[np.float64], optional) – Matrices for achieving exact covariate balance.

  • X2 (npt.NDArray[np.float64], optional) – Matrices for achieving exact covariate balance.

  • X3 (npt.NDArray[np.float64], optional) – Matrices for achieving exact covariate balance.

  • X4 (npt.NDArray[np.float64], optional) – Matrices for achieving exact covariate balance.

  • mu1 (npt.NDArray[np.float64], optional) – Population means corresponding to X1, X2, resp.

  • mu2 (npt.NDArray[np.float64], optional) – Population means corresponding to X1, X2, resp.

  • Z1 (npt.NDArray[np.float64], optional) – Matrices for constraining covariate imbalance.

  • Z2 (npt.NDArray[np.float64], optional) – Matrices for constraining covariate imbalance.

  • Z3 (npt.NDArray[np.float64], optional) – Matrices for constraining covariate imbalance.

  • Z4 (npt.NDArray[np.float64], optional) – Matrices for constraining covariate imbalance.

  • nu1 (npt.NDArray[np.float64], optional) – Population means corresponding to Z1, Z2, resp.

  • nu2 (npt.NDArray[np.float64], optional) – Population means corresponding to Z1, Z2, resp.

  • psi1 (float or list[float], optional) – Constraints on covariate imbalances.

  • psi2 (float or list[float], optional) – Constraints on covariate imbalances.

  • psi3 (float or list[float], optional) – Constraints on covariate imbalances.

  • phi (float) – Constraint on mean squared weight.

  • min_weight1 (float or list[float], optional) – Lower bound on weights. Defaults to 0.

  • min_weight2 (float or list[float], optional) – Lower bound on weights. Defaults to 0.

  • max_weight1 (float or list[float] or None, optional) – Upper bound on weights for each block (a “weight cap”). None (the default) disables the cap on that block. May be set independently per block; if neither is set the wrapped Rake runs with no upper bound, otherwise the unbounded side is filled with +inf internally so the bound is in effect only on the requested block. See Rake.max_weight for scalar/vector broadcast semantics and validation.

  • max_weight2 (float or list[float] or None, optional) – Upper bound on weights for each block (a “weight cap”). None (the default) disables the cap on that block. May be set independently per block; if neither is set the wrapped Rake runs with no upper bound, otherwise the unbounded side is filled with +inf internally so the bound is in effect only on the requested block. See Rake.max_weight for scalar/vector broadcast semantics and validation.

  • constrain_mean_weight1_to (float or None, default=1) – If not None, add a constraint that the average weight must equal constrain_mean_weight_to, which must be strictly positive. The default is an average weight of 1. Another common option is for the average weight to equal the average baseline weight. If no such constraint is desired, manually specify constrain_mean_weight_to=None.

  • constrain_mean_weight2_to (float or None, default=1) – If not None, add a constraint that the average weight must equal constrain_mean_weight_to, which must be strictly positive. The default is an average weight of 1. Another common option is for the average weight to equal the average baseline weight. If no such constraint is desired, manually specify constrain_mean_weight_to=None.

  • settings (OptimizationSettings) – Optimization settings.

  • engine ({"ipm", "pd"}, default="ipm") – Inner solver engine, forwarded to Rake.__init__. "ipm" uses the barrier interior-point method (current production behavior). "pd" dispatches the happy-path solve through PrimalDualSolver. solve_with_fallback always runs its feasibility probes on the IPM Phase I machinery regardless of engine (PrimalDual has no progressive-relaxation probe); engine governs only its final distance-minimizing solve.

Notes

This is really just a wrapper around Rake. Let:

  • w = [w1; w2] and v = [v1; v2], with M = M1 + M2;

  • mu = [mu1; mu2; 0] and nu = [nu1; nu2; 0];

  • psi = a vector with q1 entries of psi1, followed by q2 entries of psi2, followed by q3 entries of psi3, where q1, q2, and q3 are the numbers of columns in Z1, Z2, and Z3, respectively;

  • min_weight = a vector with M1 entries of min_weight1, followed by M2 entries of min_weight2, where M1 and M2 are the lengths of w1 and w2, respectively;

and stack the covariates as

      _                                        _
     |   (M / M1) * X1ᵀ             0           |
Xᵀ = |          0               (M / M2) * X2ᵀ  |
     |_ -(M / M1) * X3ᵀ         (M / M2) * X4ᵀ _|

and

      _                                        _
     |   (M / M1) * Z1ᵀ             0           |
Zᵀ = |          0               (M / M2) * Z2ᵀ  |
     |_ -(M / M1) * Z3ᵀ         (M / M2) * Z4ᵀ _|

Then the problem is equivalent to:

minimize    D(w, v)
subject to  (1/M) Xᵀw = μ                    (exact balance)
            -ψ ≤ (1/M) Zᵀw - ν ≤ ψ           (approximate balance)
            (1/M) ‖w‖₂² ≤ φ                  (variance)
            w ≥ min_weight                   (positivity)

Many of the constraints in the above optimization problem are optional. The user may wish to approximately balance some covariates for internal validity only, in which case they would specify Z3 and Z4 only, not X1, X2, X3, X4, Z1, or Z2. Then Zᵀ would just be:

 _                                       _
|_ -(M / M1) * Z3ᵀ        (M / M2) * Z4ᵀ _|

Due to a technical limitation in Rake, we require at least one equality constraint in the optimization problem. Thankfully, we typically want to constrain the mean weight to be 1, which is represented as (1/M) 1ᵀw = 1, where 1ᵀ is a vector of all ones. In our case, it makes sense to constrain w1 and w2 separately, e.g. (1 / M1) 1ᵀw1 = 1 and (1 / M2) 1ᵀw2 = 1. If the user does not specify any of the X’s, we can just use these two constraints to satisfy Rake’s requirement. Otherwise, corresponding constraints should be prepended as the first rows of X1 and X2, respectively, e.g. X1 = np.vstack([np.ones((M1,)), X1]) and mu1 = np.concatenate([[constrain_mean_weight1_to], mu1]).

solve_with_fallback()[source]#

Solve with graceful fallback through progressively relaxed constraints.

The fallback cascade is:

  1. Try the full problem (bounds + imbalance + phi + distance minimization).

  2. If phi is infeasible, return the imbalance-feasible min-norm solution (“phi_relaxed”).

  3. If full imbalance is infeasible but internal validity is feasible, hold internal validity (and the bounds) as the feasible background and relax the external-validity constraints that cannot be met (“ambivalent”).

  4. If internal validity is infeasible, relax the internal-validity constraints that cannot be met (“sad”).

  5. If even bounds + equality are infeasible, re-raise ProblemInfeasibleError.

A relaxed imbalance layer does not end the cascade. Only the rows that cannot be met are loosened, holding their summed excess to the least achievable (see _relax_imbalance); the relaxed layer then joins the feasible background and the remaining steps run as usual, so the design effect and the distance are still minimized.

When the band is too tight for the rows that can meet it to all do so at once – relaxing would put excess on a row that could meet the band on its own – the band is first widened, by the least factor that avoids that (see _relax_or_widen). A band below what the data allow is therefore met where it can be at the tightest band that does not force anything, rather than failing.

The status reports the most severe relaxation. The result’s psi holds the band each row was held to, band_scales the factor any band was widened by, and relaxed_rows the rows that could not meet even that.

Returns:

Contains the solution and a status message.

Return type:

FallbackOptimizationResult

Raises:

ProblemInfeasibleError – If even the basic bounds + equality constraints are infeasible.

Distance Metrics#

Distance penalties for PyRake’s calibration objectives.

The calibration problem minimizes a distance D(w, v) between the weight vector w and a baseline v, subject to balance constraints. Distance is the abstract base class, itself a Cvxium Objective; SquaredL2, KLDivergence and Huber are the concrete penalties. Every distance is convex in w and additive across components, so its Hessian is diagonal and hessian_contribution wraps hessian_diagonal in a DiagonalSystem for the solver.

class pyrake.calibration.distance_metrics.Distance(v=None, dimension=None)[source]#

Bases: Objective, ABC

Abstract distance penalty between weights and a baseline, as a Cvxium objective.

A distance is a function D(w, v), for example the averaged squared error

D(w, v) = (1 / M) ‖w - v‖₂².

It need not satisfy the mathematical definition of a distance (no triangle inequality required), but it should be convex in w, so it can be minimized, and additive in the components of w, so that its Hessian is diagonal.

A Distance subclasses Cvxium’s Objective, so it can be passed directly anywhere Cvxium expects one, for example as the objective of a Problem. The full Objective interface comes from defaults built on the diagonal Hessian: hessian_contribution returns a DiagonalSystem.

Parameters:
  • v (npt.NDArray[np.float64] | None) – Baseline the distance is measured against. When omitted, v is the vector of all ones. When given, its length pins the decision-variable dimension M.

  • dimension (int | None) – Decision-variable dimension M. Used only when v is omitted; it may be given here or deferred and bound later with bind_dimension (as Rake does from its data).

Raises:

ValueError – When an explicit dimension disagrees with len(v).

property dimension#

Return the decision-variable dimension M.

Returns:

M – The dimension set at construction or bound later with bind_dimension.

Return type:

int

Raises:

ValueError – When the dimension was deferred (bare construction) and not yet bound.

bind_dimension(dimension)[source]#

Bind the decision-variable dimension M deferred at construction.

A bare distance (no v, no dimension) carries no length until a consumer that owns the data binds M here, before the distance serves as a Problem objective. Rebinding to the same value is a no-op.

Parameters:

dimension (int) – Decision-variable dimension M to bind.

Raises:

ValueError – When a different dimension was already set.

abstractmethod evaluate(w)[source]#

Evaluate the distance at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

d – The distance D(w, v).

Return type:

float

abstractmethod gradient(w)[source]#

Compute the gradient of the distance at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

grad – The gradient ∇D(w), of length M.

Return type:

npt.NDArray[np.float64]

abstractmethod hessian_diagonal(w)[source]#

Compute the diagonal of the Hessian at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

diag – The Hessian diagonal, of length M.

Return type:

npt.NDArray[np.float64]

hessian_contribution(w)[source]#

Return the Hessian as a diagonal system for Cvxium.

The distance is additive in the components of w, so its Hessian is diagonal; this wraps hessian_diagonal in a DiagonalSystem (a MatrixSystem) that a Problem assembles via build_hessian_system.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

system – The Hessian of the distance at w, as a DiagonalSystem.

Return type:

MatrixSystem

class pyrake.calibration.distance_metrics.SquaredL2(v=None, dimension=None)[source]#

Bases: Distance

Squared L2 distance, averaged over components.

The distance, gradient and Hessian diagonal are

D(w, v) = (1 / M) ‖w - v‖₂²,
∇D(w) = (2 / M) (w - v),
diag(∇²D) = (2 / M) 1.

When v is omitted it defaults to the vector of all ones.

Parameters:
  • v (npt.NDArray[np.float64] | None) – Baseline; see Distance.

  • dimension (int | None) – Decision-variable dimension M; see Distance.

evaluate(w)[source]#

Evaluate the squared L2 distance at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

d – The distance (1 / M) ‖w - v‖₂².

Return type:

float

gradient(w)[source]#

Compute the gradient of the squared L2 distance at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

grad – The gradient (2 / M) (w - v), of length M.

Return type:

npt.NDArray[np.float64]

hessian_diagonal(w)[source]#

Compute the Hessian diagonal of the squared L2 distance at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

diag – The constant diagonal (2 / M) 1, of length M.

Return type:

npt.NDArray[np.float64]

class pyrake.calibration.distance_metrics.KLDivergence(v=None, dimension=None)[source]#

Bases: Distance

Kullback-Leibler divergence, averaged over components.

The distance, gradient and Hessian diagonal are

D(w, v) = (1 / M) Σᵢ (wᵢ log(wᵢ / vᵢ) - wᵢ + vᵢ),
∇D(w) = (1 / M) log(w / v),
diag(∇²D) = (1 / M) / w,

with operations understood componentwise. When v is omitted it defaults to the vector of all ones.

Parameters:
  • v (npt.NDArray[np.float64] | None) – Baseline; see Distance.

  • dimension (int | None) – Decision-variable dimension M; see Distance.

Notes

Requires strictly positive weights (and baseline); the code does not check this, and nonpositive inputs propagate nan through the logarithm.

evaluate(w)[source]#

Evaluate the KL divergence at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M, strictly positive.

Returns:

d – The divergence (1 / M) Σᵢ (wᵢ log(wᵢ / vᵢ) - wᵢ + vᵢ).

Return type:

float

gradient(w)[source]#

Compute the gradient of the KL divergence at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M, strictly positive.

Returns:

grad – The gradient (1 / M) log(w / v), of length M.

Return type:

npt.NDArray[np.float64]

hessian_diagonal(w)[source]#

Compute the Hessian diagonal of the KL divergence at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M, strictly positive.

Returns:

diag – The diagonal (1 / M) / w, of length M.

Return type:

npt.NDArray[np.float64]

class pyrake.calibration.distance_metrics.Huber(v=None, delta=0.1, dimension=None)[source]#

Bases: Distance

Huber penalty, averaged over components.

The distance applies the Huber function h to each residual:

D(w, v) = (1 / M) Σᵢ h(wᵢ - vᵢ),
h(x) = x², if |x| ≤ δ,
h(x) = δ (2|x| - δ), if |x| > δ.

The gradient is (2 / M) (wᵢ - vᵢ) within δ of the baseline and (2 / M) δ sign(wᵢ

  • vᵢ) outside it; the Hessian diagonal is 2 / M within δ and 0 outside it. When

v is omitted it defaults to the vector of all ones.

Parameters:
  • v (npt.NDArray[np.float64] | None) – Baseline; see Distance.

  • delta (float) – Knee δ where the penalty switches from quadratic to linear.

  • dimension (int | None) – Decision-variable dimension M; see Distance.

evaluate(w)[source]#

Evaluate the Huber penalty at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

d – The penalty (1 / M) Σᵢ h(wᵢ - vᵢ).

Return type:

float

gradient(w)[source]#

Compute the gradient of the Huber penalty at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

grad – The gradient, of length M: (2 / M) (wᵢ - vᵢ) within δ of the baseline, (2 / M) δ sign(wᵢ - vᵢ) outside it.

Return type:

npt.NDArray[np.float64]

hessian_diagonal(w)[source]#

Compute the Hessian diagonal of the Huber penalty at w.

Parameters:

w (npt.NDArray[np.float64]) – Weight vector, of length M.

Returns:

diag – The diagonal, of length M: 2 / M within δ of the baseline, 0 outside.

Return type:

npt.NDArray[np.float64]