onlinerake.OnlineRakingSGD

class onlinerake.OnlineRakingSGD(targets, learning_rate=5.0, min_weight=0.001, max_weight=100.0, n_sgd_steps=3, verbose=False, track_convergence=True, convergence_window=20, compute_weight_stats=False, max_history=1000, track_kl_divergence=False)

Online raking via stochastic gradient descent.

A streaming weight calibration algorithm that adjusts observation weights to match target population margins using stochastic gradient descent (SGD). The algorithm minimizes squared-error loss between weighted margins and target proportions.

Parameters:

• targets (Targets) – Target population proportions for each feature.

• learning_rate (float | LearningRateSchedule) – Step size for gradient descent updates. Can be: - float: Fixed learning rate (default: 5.0) - LearningRateSchedule: Dynamic schedule (e.g., robbins_monro_schedule()) Larger values lead to faster convergence but may cause oscillation.

• min_weight (float) – Lower bound for weights to prevent collapse. Must be positive. Default: 0.001.

• max_weight (float) – Upper bound for weights to prevent explosion. Must exceed min_weight. Default: 100.0.

• n_sgd_steps (int) – Number of gradient steps per observation. More steps can reduce oscillations but increase computation. Default: 3.

• verbose (bool) – If True, log progress information. Default: False.

• track_convergence (bool) – If True, monitor convergence metrics. Default: True.

• convergence_window (int) – Number of observations for convergence detection. Default: 20.

• compute_weight_stats (bool | int) – Control weight statistics computation. If True: compute every observation. If False: do not compute automatically; the property remains available. If int k: compute every k observations. Default: False.

• max_history (int | None) – Maximum historical states to retain. None for unlimited (may cause memory issues). Default: 1000.

• track_kl_divergence (bool) – If True, track KL divergence between consecutive weight distributions. Useful for monitoring MWU convergence and comparing to IPF. Default: False.

targets

The target proportions.

history

List of historical states after each update.

Examples

>>> from onlinerake import OnlineRakingSGD, Targets
>>> targets = Targets(owns_car=0.4, is_subscriber=0.2)
>>> raker = OnlineRakingSGD(targets, learning_rate=5.0)

One observation cannot be reweighted into two different margins, so the loss after it is just how far that single respondent sits from target:

>>> raker.partial_fit({"owns_car": 1, "is_subscriber": 0})
>>> print(f"{raker.loss:.4f}")
0.4000

Feed it a stream and the margins converge on the targets:

>>> stream = [
...     {"owns_car": 1, "is_subscriber": 0},
...     {"owns_car": 0, "is_subscriber": 1},
...     {"owns_car": 1, "is_subscriber": 1},
...     {"owns_car": 0, "is_subscriber": 0},
... ] * 5
>>> for obs in stream:
...     raker.partial_fit(obs)
>>> {name: round(value, 2) for name, value in raker.margins.items()}
{'is_subscriber': 0.22, 'owns_car': 0.4}
>>> raker.loss < 1e-3
True

Raises:

ValueError – If any parameter is invalid (negative learning rate, invalid weight bounds, non-positive convergence window, invalid compute_weight_stats).

Parameters:

• targets (Targets)

• learning_rate (float | LearningRateSchedule)

• min_weight (float)

• max_weight (float)

• n_sgd_steps (int)

• verbose (bool)

• track_convergence (bool)

• convergence_window (int)

• compute_weight_stats (bool | int)

• max_history (int | None)

• track_kl_divergence (bool)

Note

The algorithm supports arbitrary binary features, not limited to demographics. Feature names must match those defined in targets.

__init__(targets, learning_rate=5.0, min_weight=0.001, max_weight=100.0, n_sgd_steps=3, verbose=False, track_convergence=True, convergence_window=20, compute_weight_stats=False, max_history=1000, track_kl_divergence=False)

Parameters:

• targets (Targets)

• learning_rate (float | LearningRateSchedule)

• min_weight (float)

• max_weight (float)

• n_sgd_steps (int)

• verbose (bool)

• track_convergence (bool)

• convergence_window (int)

• compute_weight_stats (bool | int)

• max_history (int | None)

• track_kl_divergence (bool)

Return type:

None

Methods

__init__(targets[, learning_rate, ...])
check_convergence([tolerance])	Check the current squared moment error against an absolute tolerance.
detect_oscillation([threshold])	Detect if loss is oscillating rather than converging.
partial_fit(obs)	Process single observation and update weights.
partial_fit_batch(observations)	Process multiple observations in batch.

Attributes

converged	Return True if the algorithm has detected convergence.
convergence_step	Get step number where convergence was detected.
cumulative_kl_divergence	Get total KL divergence accumulated over all updates.
current_learning_rate	Get current learning rate (may vary if using a schedule).
effective_sample_size	Return the effective sample size (ESS).
gradient_norm_history	Get history of gradient norms.
kl_divergence_history	Get history of KL divergence between consecutive weight updates.
learning_rate_history	Get history of learning rates used at each observation.
loss	Get current squared-error loss.
loss_moving_average	Return moving average of loss over convergence window.
margins	Get current weighted margins.
raw_margins	Get unweighted (raw) margins.
uses_lr_schedule	Return True if using a dynamic learning rate schedule.
weight_distribution_stats	Return comprehensive weight distribution statistics.
weights	Get copy of current weight vector.