bayesianbandits.GammaRegressor#

class bayesianbandits.GammaRegressor(alpha: float, beta: float, *, learning_rate: float = 1.0, random_state: int | None | Generator = None)#

Bases: BaseEstimator, RegressorMixin

Intercept-only Gamma-Poisson conjugate regression model.

Maintains a separate Gamma posterior over the rate parameter \(\lambda\) for each unique value of the first feature. Designed for modeling count data where the rate may differ across groups. Supports sample weights (for importance-weighted updates in adversarial bandit algorithms) and online learning via partial_fit.

Parameters:

  • alpha (float) – Prior shape parameter of the Gamma distribution. The prior is \(\lambda \sim \text{Gamma}(\alpha, \beta)\). Larger values concentrate the prior more tightly around the prior mean \(\alpha / \beta\).

  • beta (float) – Prior rate (inverse scale) parameter. Together with alpha, determines the prior mean \(\mathbb{E}[\lambda] = \alpha / \beta\) and prior variance \(\text{Var}[\lambda] = \alpha / \beta^2\).

  • learning_rate (float, default 1.0) – Decay rate for the posterior parameters. Values less than 1 geometrically shrink both \(\alpha\) and \(\beta\) on each call to decay, increasing posterior variance while preserving the mean. This converts the model into a forgetting estimator suitable for restless bandit problems.

  • random_state (int, np.random.Generator, or None, default None) – Controls the random number generator for sample. Pass an int for reproducible results across calls.

coef_#

Posterior parameters [alpha, beta] for each observed feature value. Unseen feature values default to the prior.

Type:

dict of {int or float: ndarray of shape (2,)}

n_features_#

Number of features seen during fit. Must be 1.

Type:

int

prior_#

Prior parameters [alpha, beta].

Type:

ndarray of shape (2,)

See also

DirichletClassifier

Bayesian classification for categorical outcomes.

NormalRegressor

Bayesian linear regression for real-valued outcomes.

Notes

This model implements the Gamma-Poisson conjugate model. Given observations \(y_i\) with sample weights \(w_i\), the posterior update is [1]:

\[\alpha^{\text{post}} = \alpha^{\text{prior}} + \sum_{i=1}^{N} w_i \, y_i, \qquad \beta^{\text{post}} = \beta^{\text{prior}} + \sum_{i=1}^{N} w_i\]

The posterior mean rate is \(\mathbb{E}[\lambda] = \alpha / \beta\) and the posterior variance is \(\text{Var}[\lambda] = \alpha / \beta^2\).

When learning_rate < 1, calling decay scales both \(\alpha\) and \(\beta\) equally, so the posterior mean is preserved but the variance increases.

References

Examples

Basic rate estimation:

>>> import numpy as np
>>> X = np.array([[1], [2], [3], [4], [5]])
>>> y = np.array([1, 2, 3, 4, 5])
>>> model = GammaRegressor(alpha=1, beta=1, random_state=0)
>>> model.fit(X, y)
GammaRegressor(alpha=1, beta=1, random_state=0)

Using sample weights for importance-weighted updates:

>>> weights = np.array([1.0, 2.0, 1.0, 0.5, 1.5])
>>> model.fit(X, y, sample_weight=weights)
GammaRegressor(alpha=1, beta=1, random_state=0)

Online learning with partial_fit:

>>> model.partial_fit(X, y, sample_weight=weights)
GammaRegressor(alpha=1, beta=1, random_state=0)
__init__(alpha: float, beta: float, *, learning_rate: float = 1.0, random_state: int | None | Generator = None) → None#
decay(X: NDArray[Any], *, decay_rate: float | None = None) → None#

Decay posterior parameters to increase uncertainty.

Scales both shape and rate by the decay factor: \(\alpha \leftarrow \gamma \alpha,\; \beta \leftarrow \gamma \beta\). Because both parameters are scaled equally, the posterior mean \(\alpha / \beta\) is preserved but the variance \(\alpha / \beta^2\) increases.

Has no effect if the model has not been fitted.

Parameters:

  • X (array-like of shape (n_samples, 1)) – Input features. Each unique value of X[:, 0] identifies a group whose parameters are decayed.

  • decay_rate (float, default None) – Multiplicative decay factor \(\gamma\) in (0, 1]. If None, uses self.learning_rate.

See also

partial_fit

Update the model with new observations.

fit(X: NDArray[Any], y: NDArray[Any], sample_weight: NDArray[Any] | None = None) → Self#

Fit the model from scratch, resetting the prior.

Initializes the Gamma prior from alpha and beta and updates the posterior parameters using the observed counts (optionally weighted).

Parameters:

  • X (array-like of shape (n_samples, 1)) – Training data. Only the first column is used; each unique value indexes a separate Gamma posterior.

  • y (array-like of shape (n_samples,)) – Target values (non-negative integer counts).

  • sample_weight (array-like of shape (n_samples,), default None) – Individual weights for each sample. If None, all samples are given weight 1.0.

Returns:

self – Fitted estimator.

Return type:

GammaRegressor

See also

partial_fit

Incremental update without resetting the prior.

partial_fit(X: NDArray[Any], y: NDArray[Any], sample_weight: NDArray[Any] | None = None)#

Incrementally update the model with new observations.

Uses the current posterior as the prior for the new update. If the model has not been fitted yet, this is equivalent to calling fit.

Parameters:

  • X (array-like of shape (n_samples, 1)) – Training data. Only the first column is used; each unique value indexes a separate Gamma posterior.

  • y (array-like of shape (n_samples,)) – Target values (non-negative integer counts).

  • sample_weight (array-like of shape (n_samples,), default None) – Individual weights for each sample. If None, all samples are given weight 1.0.

Returns:

self – Updated estimator.

Return type:

GammaRegressor

See also

fit

Fit from scratch, resetting the prior.

predict(X: NDArray[Any]) → NDArray[Any]#

Predict the posterior mean rate for each sample.

Returns the mean of the Gamma posterior \(\mathbb{E}[\lambda] = \alpha / \beta\).

If the model has not been fitted, returns the prior mean.

Parameters:

X (array-like of shape (n_samples, 1)) – Input features. Each unique value of X[:, 0] indexes a separate Gamma posterior.

Returns:

y_pred – Predicted rates (posterior means).

Return type:

ndarray of shape (n_samples,)

See also

sample

Draw from the Gamma posterior.

sample(X: NDArray[Any], size: int = 1) → NDArray[np.float64]#

Sample rates from the Gamma posterior.

For each input, draws from \(\text{Gamma}(\alpha, \beta)\) where \(\alpha\) and \(\beta\) are the posterior shape and rate parameters for that input’s group. If the model has not been fitted, samples from the prior.

Parameters:

  • X (array-like of shape (n_samples, 1)) – Input features. Each unique value of X[:, 0] indexes a separate Gamma posterior.

  • size (int, default 1) – Number of independent draws from each posterior.

Returns:

samples – Sampled rates from the Gamma posterior.

Return type:

ndarray of shape (size, n_samples)

See also

predict

Point estimate using the posterior mean.