Skip to content

Deep Ensembles API

This page documents the regression and classification ensemble wrappers in deepuq.methods.ensembles. The manual notes here explain the public variants and their tensor contracts; the generated section below contains the exact signatures and source docstrings.

Public objects

  • DeepEnsembleRegressor
  • HeteroscedasticDeepEnsembleRegressor
  • DeepEnsembleClassifier
  • MultiOutputDeepEnsembleRegressor
  • HeteroscedasticMultiOutputDeepEnsembleRegressor
  • DeepEnsembleWrapper (backward-compatible alias of DeepEnsembleRegressor)

Parameter and variable conventions

Name Meaning
models sequence of independently trained deterministic members
epochs number of optimization epochs per member in fit(...)
optimizer_cls optimizer factory used to train each member
lr member learning rate
weight_decay member weight decay
device optional training device
seed base seed; member i uses seed + i
min_variance lower bound for heteroscedastic predicted variances

Input and output shapes

  • ensemble members must share the same input/output contract
  • predict_members(...) returns a stacked tensor with leading axis [n_members, ...]
  • classification members must emit logits with shape [batch, n_classes]
  • heteroscedastic regressors must emit mean and log-variance concatenated in a single tensor
  • multi-output regressors preserve the full output shape and report per-output uncertainty

UQResult mapping

  • DeepEnsembleRegressor: mean, epistemic_var, total_var
  • HeteroscedasticDeepEnsembleRegressor: mean, epistemic_var, aleatoric_var, total_var
  • DeepEnsembleClassifier: mean, probs, probs_var, epistemic_var
  • MultiOutputDeepEnsembleRegressor: same fields as plain regression, but vector-valued
  • HeteroscedasticMultiOutputDeepEnsembleRegressor: same fields as heteroscedastic regression, but vector-valued

Common preconditions and failure modes

  • models must contain at least one member
  • all members must accept the same x shape and emit the same output shape
  • heteroscedastic members must concatenate mean and log-variance correctly; odd channel counts raise ValueError
  • classification targets are cast to integer labels inside DeepEnsembleClassifier

Minimal example

ensemble = DeepEnsembleRegressor([model_a, model_b, model_c])
ensemble.fit(train_loader, epochs=50, lr=1e-3)
uq = ensemble.predict_uq(x_test)

deepuq.methods.ensembles

Deep ensemble wrappers for regression and classification uncertainty.

The ensemble variants in this module aggregate independently trained deterministic models. predict_uq returns a :class:deepuq.types.UQResult with either regression moments or class-probability moments.

DeepEnsembleClassifier

Bases: _BaseDeepEnsemble

Classification ensemble using member-wise logits and probability averaging.

Shape contract
  • input: any tensor accepted by the wrapped classifier
  • member output: logits with shape [batch, n_classes]
  • predict returns (mean_probs, probs_var)

Parameters:

Name Type Description Default
models Sequence[Module]

Ensemble members that output logits with a shared class dimension.

 required

predict_uq 

predict_uq(x: Tensor) -> UQResult

Return mean class probabilities and probability variance.

Classification ensembles populate probs and probs_var. The regression variance fields mirror probability variance for convenience.

DeepEnsembleRegressor

Bases: _BaseDeepEnsemble

Deterministic regression ensemble with epistemic uncertainty.

Shape contract
  • input: any tensor accepted by the wrapped regressor
  • member output: [batch, ...]
  • predict returns (mean, variance) with the same prediction shape
Example 
ensemble = DeepEnsembleRegressor([model_a, model_b, model_c])
ensemble.fit(train_loader, epochs=50, lr=1e-3)
uq = ensemble.predict_uq(x_test)

predict_members 

predict_members(x: Tensor) -> torch.Tensor

Return stacked member predictions with shape [n_members, batch, ...].

predict_uq 

predict_uq(x: Tensor) -> UQResult

Return predictive mean and epistemic variance in a UQResult.

DeepEnsembleWrapper

Bases: DeepEnsembleRegressor

Backward-compatible alias for the original regression-first wrapper.

Prefer :class:DeepEnsembleRegressor in new code.

HeteroscedasticDeepEnsembleRegressor

Bases: _BaseDeepEnsemble

Regression ensemble with predicted aleatoric noise per member.

Each member must output concatenated mean and log-variance tensors. For vector outputs the concatenation is along the last dimension. For field outputs it is along channel dimension 1.

Parameters:

Name Type Description Default
models Sequence[Module]

Ensemble members. Each member must emit mean and log-variance in a single concatenated tensor.

 required
min_variance float

Floor applied after exponentiating predicted log-variance.

 1e-06

predict_uq 

predict_uq(x: Tensor) -> UQResult

Return predictive mean plus epistemic, aleatoric, and total variance.

HeteroscedasticMultiOutputDeepEnsembleRegressor

Bases: HeteroscedasticDeepEnsembleRegressor

Multi-output regression ensemble with epistemic and aleatoric uncertainty.

Each member must emit concatenated mean and log-variance tensors for every output component.

MultiOutputDeepEnsembleRegressor

Bases: DeepEnsembleRegressor

Multi-output regression ensemble with epistemic uncertainty.

Member predictions are vector-valued, typically with shape [batch, n_outputs].

predict_uq reports one epistemic variance value per output component.