bayesianbandits.DirichletClassifier#

class bayesianbandits.DirichletClassifier(alphas: Dict[int | str, float], *, learning_rate: float = 1.0, random_state: int | None | Generator = None)#

Bases: BaseEstimator, ClassifierMixin

Intercept-only Dirichlet-Multinomial classifier.

Maintains a separate Dirichlet posterior over class probabilities for each unique value of the first feature. Supports sample weights (for importance-weighted updates in adversarial bandit algorithms) and online learning via partial_fit.

Parameters:

  • alphas (dict of {int or str: float}) – Prior concentration parameters for each class. Keys define the set of classes; values are the initial Dirichlet \(\alpha_k\). A uniform prior (e.g. {0: 1, 1: 1}) encodes no prior preference.

  • learning_rate (float, default 1.0) – Decay rate for the concentration parameters. Values less than 1 geometrically shrink the posterior on each call to decay, increasing uncertainty over time. 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.

classes_#

Class labels derived from the keys of alphas.

Type:

ndarray of shape (n_classes,)

n_classes_#

Number of classes.

Type:

int

n_features_#

Number of features seen during fit. Must be 1.

Type:

int

prior_#

Prior concentration parameters (values of alphas).

Type:

ndarray of shape (n_classes,)

known_alphas_#

Posterior concentration parameters for each observed feature value. Unseen feature values default to the prior.

Type:

dict of {int or str: ndarray of shape (n_classes,)}

See also

GammaRegressor

Bayesian regression for positive continuous outcomes.

NormalRegressor

Bayesian linear regression for real-valued outcomes.

Notes

This model implements the Dirichlet-Multinomial conjugate model described in Chapter 3 of [1]. The posterior update is:

\[\alpha_k^{\text{post}} = \alpha_k^{\text{prior}} + \sum_{i=1}^{N} w_i \, \mathbb{1}[y_i = k]\]

where \(w_i\) are sample weights (defaulting to 1).

The predictive distribution for class probabilities is:

\[\mathbb{E}[\theta_k] = \frac{\alpha_k}{\sum_j \alpha_j}\]

When learning_rate < 1, calling decay scales all concentration parameters by the decay rate, uniformly increasing posterior uncertainty.

References

Examples

Basic classification with a uniform prior:

>>> from bayesianbandits import DirichletClassifier
>>> X = np.array([1, 1, 1, 2, 2, 2, 3, 3, 3]).reshape(-1, 1)
>>> y = np.array([1, 1, 2, 2, 2, 3, 3, 3, 3])
>>> clf = DirichletClassifier({1: 1, 2: 1, 3: 1}, random_state=0)
>>> clf.fit(X, y)
DirichletClassifier(alphas={1: 1, 2: 1, 3: 1}, random_state=0)

Using sample weights for importance-weighted updates:

>>> weights = np.array([2.0, 1.0, 0.5, 1.0, 2.0, 1.0, 0.5, 1.0, 2.0])
>>> clf.fit(X, y, sample_weight=weights)
DirichletClassifier(alphas={1: 1, 2: 1, 3: 1}, random_state=0)

Online learning with partial_fit:

>>> clf.partial_fit(X, y, sample_weight=weights)
DirichletClassifier(alphas={1: 1, 2: 1, 3: 1}, random_state=0)
__init__(alphas: Dict[int | str, float], *, learning_rate: float = 1.0, random_state: int | None | Generator = None) → None#
decay(X: NDArray[Any], *, decay_rate: float | None = None) → None#

Decay concentration parameters to increase uncertainty.

Scales the posterior concentration parameters \(\alpha_k \leftarrow \gamma \, \alpha_k\) for each group present in X. This uniformly increases posterior variance, allowing the model to adapt to non-stationary environments.

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 concentration 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 Dirichlet prior from alphas and updates the posterior concentration parameters using the observed class 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 Dirichlet posterior.

  • y (array-like of shape (n_samples,)) – Class labels. Must be a subset of the keys in alphas.

  • 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:

DirichletClassifier

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 Dirichlet posterior.

  • y (array-like of shape (n_samples,)) – Class labels. Must be a subset of the keys in alphas.

  • 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:

DirichletClassifier

See also

fit

Fit from scratch, resetting the prior.

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

Predict the most likely class for each sample.

Returns the class with the highest posterior mean probability \(\arg\max_k \alpha_k\).

Parameters:

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

Returns:

y_pred – Predicted class labels.

Return type:

ndarray of shape (n_samples,)

See also

predict_proba

Return full probability vectors.

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

Predict class probabilities using the posterior mean.

Computes the expected class probabilities under the Dirichlet posterior: \(\mathbb{E}[\theta_k] = \alpha_k / \sum_j \alpha_j\).

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 Dirichlet posterior.

Returns:

proba – Predicted class probabilities. Each row sums to 1.

Return type:

ndarray of shape (n_samples, n_classes)

See also

predict

Return the most likely class label.

sample

Draw from the Dirichlet posterior.

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

Sample class probability vectors from the Dirichlet posterior.

For each input, draws from \(\text{Dir}(\alpha_1, \ldots, \alpha_K)\) where the \(\alpha_k\) are the posterior concentration 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 Dirichlet posterior.

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

Returns:

samples – Sampled probability vectors. Each sample along the last axis sums to 1.

Return type:

ndarray of shape (size, n_samples, n_classes)

See also

predict_proba

Point estimate using the posterior mean.