saealib.SurrogatePrediction#

class saealib.SurrogatePrediction(channels, x=None, label=None, metadata=<factory>)[source]#

Bases: object

Unified return type for surrogate model predictions.

channels is the canonical representation: one named PredictionChannel per prediction output (e.g. "objective", "win_rate"). value/std are convenience properties delegating to the "objective" channel and raise KeyError when it is absent.

Parameters:

  • channels (dict[str, PredictionChannel])

  • x (ndarray | None)

  • label (ndarray | None)

  • metadata (dict[str, object])

channels#

Named prediction channels. Channel names are unique, non-empty strings.

Type:

dict[str, PredictionChannel]

x#

The query points passed to predict(). shape: (n_samples, n_features). None unless the surrogate populates it. Needed by acquisition functions that have no other channel to the points being scored (e.g. CORSDistance).

Type:

np.ndarray or None

label#

Predicted class labels. shape: (n_samples,). None unless the surrogate is a classification model.

Type:

np.ndarray or None

metadata#

Implementation-specific additional information (e.g., SHAP values, gradient estimates).

Type:

dict

Methods

__init__

objective

Build a single-"objective"-channel SurrogatePrediction.

select_channel

Project a single named channel into a standalone SurrogatePrediction.

Method Details

SurrogatePrediction.__init__(channels, x=None, label=None, metadata=<factory>)#
Parameters:

  • channels (dict[str, PredictionChannel])

  • x (ndarray | None)

  • label (ndarray | None)

  • metadata (dict[str, object])

Return type:

None

classmethod SurrogatePrediction.objective(value, std=None, x=None, metadata=None)[source]#

Build a single-"objective"-channel SurrogatePrediction.

Equivalent to constructing channels={"objective": PredictionChannel(value, std)} by hand.

Parameters:

  • value (ndarray)

  • std (ndarray | None)

  • x (ndarray | None)

  • metadata (dict[str, object] | None)

Return type:

SurrogatePrediction

SurrogatePrediction.select_channel(name, *, as_objective=True)[source]#

Project a single named channel into a standalone SurrogatePrediction.

Parameters:

  • name (str) – Channel name to select. Raises KeyError if not present in self.channels.

  • as_objective (bool, optional) – If True (default), the result’s channels is {"objective": self.channels[name]} so .value/.std resolve normally. If False, the result’s channels is {name: self.channels[name]}, preserving the original name for callers that want to project without claiming the channel is the objective.

Returns:

A new prediction carrying forward self.x and self.metadata unchanged. The selected PredictionChannel (with its own covariance/samples) is reused, not copied.

Return type:

SurrogatePrediction