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 onself.X_train/self.y_trainand setself.training_complete = True.predict— return anEmulationResultswith 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.