Skip to main content

emulators.base

emulators.base

Abstract base class that every history matching emulator implements.

Classes

Name Description
BaseEmulator Abstract base class for all emulators.

BaseEmulator

emulators.base.BaseEmulator(x=None, y=None, test_fraction=0.25)

Abstract base class for all emulators.

An emulator is a fast statistical surrogate of the user’s simulator: it is trained on a set of parameter samples x and the corresponding simulator outputs y, and then predicts the output (with uncertainty) at new parameter points. History matching uses those predictions to decide which regions of parameter space are implausible.

This class handles the train/test split and the shared diagnostics (test, get_implausibility); concrete emulators only need to implement the fitting and prediction logic.

To write your own emulator, subclass BaseEmulator and implement the four abstract methods:

  • train — fit the emulator on self.X_train / self.y_train and set self.training_complete = True.
  • predict — return an EmulationResults with a predictive mean and variance for the given input DataFrame.
  • print_emulator_description — print the fitted specification (coefficients, lengthscales, etc.).
  • get_hyperparameters — return the fitted hyperparameters as a JSON-serializable dict.

Register the subclass with EmulatorFactory to make it selectable via emulator_type= on HistoryMatching.

See BayesLinear (the default), GPR, LinearModel, and GLM for reference implementations.

Methods

Name Description
get_hyperparameters Return emulator hyperparameters as a JSON-serializable dict.
get_implausibility Get implausibility for a given set of parameters.
info Prints report about the emulator and its performance.
plot_diagnostics Diagnostics plots for the trained emulator.
plot_implausibility Get implausibility for a given set of parameters.
plot_predictions Plot the predicted and true testing values.
plot_residuals Plot residuals of predicted vs. true testing values.
plot_zscore Plot a Z-score diagnoses for testing and training data.
predict Predict an output using the trained emulator.
predict_bounds Cheap bounds on the mean and variance predict would return; optional.
print_emulator_description Display detailed specifications (for example, emulator coefficients)
test Tests and runs diagnostics on the trained emulator.
train Trains the emulator.
get_hyperparameters
emulators.base.BaseEmulator.get_hyperparameters()

Return emulator hyperparameters as a JSON-serializable dict.

Subclasses should include all fitted hyperparameters relevant to understanding the emulator (e.g. lengthscales, noise variance, regression coefficients). Parameter names in the input space should use the original column names where possible.

get_implausibility
emulators.base.BaseEmulator.get_implausibility(
    x,
    target,
    target_var,
    model_discrepancy=0,
)

Get implausibility for a given set of parameters.

Parameters
Name Type Description Default
x pd.DataFrame Input data. Pandas dataframe with columns representing parameter values where the implausibility metric will be evaluated. required
target Scalar indicating the value to use as reference for the implausibility computation. This is typically extracted from observed data. required
target_var Variance of the target point. required
model_discrepancy Model discrepancy, expressed as a standard deviation (sigma), quantifying the difference between the model output and real-life data. It is added in quadrature, matching ObservationData.calculate_implausibility. 0

Returns: Numpy array with implausibility values for each of the data points in x.

info
emulators.base.BaseEmulator.info()

Prints report about the emulator and its performance.

plot_diagnostics
emulators.base.BaseEmulator.plot_diagnostics()

Diagnostics plots for the trained emulator.

plot_implausibility
emulators.base.BaseEmulator.plot_implausibility(
    x=None,
    target=0,
    target_var=0,
    model_discrepancy=0,
    threshold=3,
)

Get implausibility for a given set of parameters.

Parameters
Name Type Description Default
x Input data. Pandas dataframe with columns representing parameter values where the implausibility metric will be evaluated. If not provided, both testing and training data will be used for generating the plots. None
target Scalar indicating the value to use as reference for the implausiblity computation. This is typically extracted from observed data. 0
target_var Variance of the target point. 0
model_discrepancy Model discrepancy or variance. This parameter quantifies the discrepancy between the model output and real life data. 0
threshold Implausibility threshold. Sets of parameters within this threshold are deemed as non-implausible. 3
plot_predictions
emulators.base.BaseEmulator.plot_predictions()

Plot the predicted and true testing values.

plot_residuals
emulators.base.BaseEmulator.plot_residuals()

Plot residuals of predicted vs. true testing values.

plot_zscore
emulators.base.BaseEmulator.plot_zscore(
    target=0,
    target_var=0,
    model_var=0,
    threshold=3,
)

Plot a Z-score diagnoses for testing and training data.

Parameters
Name Type Description Default
target Scalar indicating the value to use as reference for the implausiblity computation. This is typically extracted from observed data. 0
target_var Variance of the target point. 0
model_var Model discrepancy or variance. This parameter quantifies the discrepancy between the model output and real life data. 0
threshold Implausibility threshold. Sets of parameters within this threshold are deemed as non-implausible. 3
predict
emulators.base.BaseEmulator.predict(x)

Predict an output using the trained emulator.

Parameters
Name Type Description Default
x pd.DataFrame Input data. Pandas dataframe with columns representing parameter values. required
Returns
Name Type Description
EmulationResults EmulationResults with predicted values and uncertainty information.
predict_bounds
emulators.base.BaseEmulator.predict_bounds(x)

Cheap bounds on the mean and variance predict would return; optional.

An emulator whose variance costs much more than its mean can implement this to speed up the NROY test. It returns a PredictionBounds: an approximate mean with a tolerance, and lower and upper bounds on the variance, such that predict(x) is within them at every point, up to floating-point rounding. historymatching.nroy_sampling.nroy_mask then rules a point out if it is implausible for every mean and variance within the bounds, and in if it is plausible for all of them, and calls predict only on the points in between. The mask is the same as without screening.

Parameters
Name Type Description Default
x pd.DataFrame Input data. Pandas dataframe with columns representing parameter values. required
Returns
Name Type Description
Optional[PredictionBounds] A PredictionBounds, or None if the emulator does not offer
Optional[PredictionBounds] screening (the default), in which case nroy_mask calls predict
Optional[PredictionBounds] on every point.
print_emulator_description
emulators.base.BaseEmulator.print_emulator_description()

Display detailed specifications (for example, emulator coefficients) for the trained emulator.

test
emulators.base.BaseEmulator.test()

Tests and runs diagnostics on the trained emulator.

train
emulators.base.BaseEmulator.train()

Trains the emulator.