engine
HistoryMatching — the main user-facing class for running a calibration.
Configure everything in one constructor call (parameter bounds, observations, simulator function, and options), then call HistoryMatching.run for an automated workflow or HistoryMatching.step / commit_step / revert_step for interactive, wave-by-wave control.
Classes
| Name | Description |
|---|---|
| EngineState | Possible states of the HistoryMatching engine. |
| HistoryMatching | Bayesian history matching — configure everything in one constructor call. |
| IterationSnapshot | Snapshot of engine state at a specific iteration. |
EngineState
engine.EngineState()Possible states of the HistoryMatching engine.
HistoryMatching
engine.HistoryMatching(
function=None,
bounds=None,
observations=None,
*,
sampling_strategy='lhs',
feature_selection=None,
emulator_type='bayes_linear',
emulator_factory=None,
emulator_bank=None,
n_samples=1000,
implausibility_threshold=3.0,
max_iterations=10,
random_seed=None,
auto_reduce_space=False,
oversample_factor=1.1,
max_batch_size=10000,
output_dir='./hm_output',
run_name=None,
convergence_threshold=0.0,
nroy_method='auto',
nroy_options=None,
max_candidate_factor=1000,
)Bayesian history matching — configure everything in one constructor call.
Pass your parameter bounds, observations, and simulator function as plain arguments. Friendly values (strings, dicts, lists) are accepted for the strategy options and turned into the underlying objects for you; sensible defaults are used for anything you omit.
Examples
import historymatching as hm
# The simulator takes a DataFrame of samples and returns one row of outputs per sample.
# Each output name must match an observation key.
def run_sir(samples):
rows = []
for _, row in samples.iterrows():
rows.append({'peak_incidence': simulate_peak(row['beta'], row['gamma'])})
return rows # a DataFrame is also accepted
engine = HistoryMatching(
function=run_sir,
bounds={'beta': (0.5, 3.0), 'gamma': (0.1, 1.0)},
observations={'peak_incidence': (120.0, 50.0)}, # (mean, std)
emulator_type='bayes_linear',
n_samples=500,
max_iterations=4,
)
# Automated execution
results = engine.run()
plausible = engine.get_nroy_samples() # NROY = "Not Ruled Out Yet"
# Interactive, step-by-step execution
result = engine.step() # run one wave
engine.commit_step() # accept it (or engine.revert_step())
engine.feature_selection = ['different_output'] # reconfigure on the fly
result = engine.step()The simulator function receives a pandas DataFrame of parameter samples (one row per sample) and may return either a DataFrame or a list of dicts (one dict per sample) mapping output names to values.
Attributes
| Name | Description |
|---|---|
| emulator_factory | The emulator factory. Assign an EmulatorFactory for full control. |
| emulator_type | Emulator type as a string. Assign 'gpr'/'glm'/'linear' to change it. |
| feature_selection | Which outputs to emulate each wave. Assign a name/list/dict/strategy (e.g. engine.feature_selection = ['peak']). |
| max_iterations | Maximum number of waves to run (you may raise it mid-run). |
| outputs | Names of the observed outputs being matched. |
| parameters | Names of the parameters being calibrated. |
| results | All committed IterationResult objects, in order. |
| sampling_strategy | Sampling strategy. Assign a name/dict/strategy to change it (e.g. engine.sampling_strategy = 'grid'). |
Methods
| Name | Description |
|---|---|
| add_iteration_callback | Add callback to be called after each iteration. |
| add_progress_callback | Add callback to be called on progress updates. |
| commit_step | Commit the pending iteration results. |
| drop_emulator_from_pending | Remove a specific emulator from the pending iteration before committing. |
| enumerate | Iterate over committed waves as (iteration, result, samples) tuples. |
| get_all_results | Get all committed iteration results. |
| get_iteration_result | Get result for a specific iteration. |
| get_nroy_samples | Get plausible parameter samples — the calibration result. |
| get_pending_next_samples | Get the proposed samples for the next iteration, if available. |
| get_status_summary | Get a human-readable, multi-line summary of the current status. |
| implausibility | Implausibility of each parameter point under every committed emulator. |
| in_nroy | Test whether each parameter point is inside the current NROY region. |
| load_checkpoint | Load engine state from checkpoint file. |
| nroy_summary | Print and return a text summary of the current NROY region: number of |
| plot_constrained_dims | Constrained-direction (variance-reduction) plot of the NROY cloud |
| plot_convergence | Plot the NROY fraction per wave (delegates to |
| plot_ensemble_fan | Fan/spaghetti plot of an ensemble of trajectories vs observed data. |
| plot_marginals | Marginal histograms of the NROY samples (delegates to |
| plot_nroy | Corner/pairplot of the NROY parameter cloud (delegates to |
| plot_nroy_parameters | Deprecated alias for plot_nroy. |
| plot_zscores | Standardised outputs vs targets across waves (delegates to |
| print_emulator_quality_metrics | Print and return per-feature emulator quality metrics for a wave. |
| revert_step | Revert the pending iteration results. |
| run | Run automated history matching workflow. |
| save_checkpoint | Save engine state to checkpoint file. |
| save_diagnostics | Save every committed wave’s artifacts under directory. |
| step | Execute a single history matching iteration. |
| validate | Validate the engine’s configuration. |
add_iteration_callback
engine.HistoryMatching.add_iteration_callback(callback)Add callback to be called after each iteration.
add_progress_callback
engine.HistoryMatching.add_progress_callback(callback)Add callback to be called on progress updates.
commit_step
engine.HistoryMatching.commit_step()Commit the pending iteration results.
This makes the changes from the last step() permanent and advances the iteration counter.
Raises
| Name | Type | Description |
|---|---|---|
| RuntimeError | If no pending iteration to commit |
drop_emulator_from_pending
engine.HistoryMatching.drop_emulator_from_pending(feature)Remove a specific emulator from the pending iteration before committing.
Call this after step() but before commit_step() to exclude an emulator whose diagnostics indicate a poor fit. The emulator will not be stored in the bank and will not contribute to implausibility filtering in future waves.
The simulation data for this wave is unaffected — only the emulator is dropped. The remaining emulators are committed as normal.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| feature | str | Name of the feature whose emulator should be dropped. | required |
Raises
| Name | Type | Description |
|---|---|---|
| RuntimeError | If called when no step is pending. | |
| KeyError | If the feature was not emulated in the pending step. |
Example
result = engine.step()
metrics = result.get_emulator_quality_metrics()
for output in result.emulated_outputs:
print(f"{output}: R²={metrics[output]['r2']:.3f}")
# Drop any emulator with a poor fit before committing
engine.drop_emulator_from_pending('output_c')
engine.commit_step()enumerate
engine.HistoryMatching.enumerate()Iterate over committed waves as (iteration, result, samples) tuples.
Example
for i, result, samples in engine.enumerate():
print(i, result.nroy_fraction, len(samples))get_all_results
engine.HistoryMatching.get_all_results()Get all committed iteration results.
get_iteration_result
engine.HistoryMatching.get_iteration_result(iteration)Get result for a specific iteration.
get_nroy_samples
engine.HistoryMatching.get_nroy_samples(n=None, method=None, **kwargs)Get plausible parameter samples — the calibration result.
Returns the NROY (“Not Ruled Out Yet”) samples: parameter sets that pass ALL committed emulators’ implausibility checks. By default returns the pre-computed set from the last wave (n_samples of them). Pass n to draw a fresh, larger set filtered through the current emulator bank. No new simulations are run — only fast emulator predictions are used.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | Optional[int] | Number of NROY samples to return. If None, returns the pre-computed set from the last committed wave. | None |
| method | Optional[str] | NROY sampling method: 'auto' (LHS first, escalates to ray+importance if needed), 'lhs' (pure rejection only), or None (uses engine default). For unbiased final samples (e.g. trajectory selection), use method='lhs'. |
None |
| **kwargs | Extra options passed to generate_nroy_design(): n_lines, points_per_line (ray_resample); max_candidates (lhs); imp_scale, maximin_reps, etc. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
| pd.DataFrame | DataFrame of NROY samples, or empty DataFrame if no iterations committed. |
Example
results = engine.run()
nroy = engine.get_nroy_samples() # cached from last wave
nroy = engine.get_nroy_samples(10000) # larger draw (default method)
nroy = engine.get_nroy_samples(5000, method='lhs') # unbiased for posterior
nroy = engine.get_nroy_samples(5000, method='auto',
n_lines=40, points_per_line=100)get_pending_next_samples
engine.HistoryMatching.get_pending_next_samples()Get the proposed samples for the next iteration, if available.
This allows inspection of pre-computed samples after step() but before commit_step(). The samples are computed during step() execution and will be used for the next iteration if the current step is committed.
Returns
| Name | Type | Description |
|---|---|---|
| Optional[pd.DataFrame] | DataFrame of proposed samples for next iteration, or None if no step is pending |
Example
result = engine.step()
next_samples = engine.get_pending_next_samples()
if next_samples is not None:
print(f"Proposed {len(next_samples)} samples for next iteration")
# Inspect the samples before deciding to commit
engine.commit_step() # or engine.revert_step()get_status_summary
engine.HistoryMatching.get_status_summary()Get a human-readable, multi-line summary of the current status.
(To reconfigure mid-run, just assign to the matching attribute, e.g. engine.feature_selection = ['peak'] or engine.max_iterations = 20.)
implausibility
engine.HistoryMatching.implausibility(samples)Implausibility of each parameter point under every committed emulator.
A diagnostic companion to in_nroy(): it evaluates every emulator on every point, without short-circuiting, so you can see which wave and target ruled a point out, and by how much. A point is in NROY when it is inside the bounds and every value in its row is at most implausibility_threshold.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| samples | pd.DataFrame | DataFrame with one column per parameter. | required |
Returns
| Name | Type | Description |
|---|---|---|
| pd.DataFrame | DataFrame indexed like samples, with one column per committed |
|
| pd.DataFrame | emulator. Columns are a MultiIndex of (iteration, feature). Use | |
| pd.DataFrame | .max(axis=1) for each point’s maximum implausibility. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If a parameter column is missing. |
in_nroy
engine.HistoryMatching.in_nroy(samples, batch_size=None)Test whether each parameter point is inside the current NROY region.
A point is in NROY when it lies inside the parameter bounds and passes the implausibility threshold for every committed emulator. This is the same test get_nroy_samples() applies to its candidates, so the two always agree. Use it for points you supply yourself: a known truth in a re-identification run, a uniform or Sobol design for trajectory selection, an MCMC proposal, or samples from another method.
No simulations are run — only emulator predictions. Pending (uncommitted) emulators are not used.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| samples | pd.DataFrame | DataFrame with one column per parameter; extra columns are ignored. | required |
| batch_size | Optional[int] | Optional number of rows to test at a time, to bound the memory of emulator predictions on very large candidate sets. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | Boolean array of shape (len(samples),), in row order. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If a parameter column is missing. |
Example
mask = engine.in_nroy(candidates) nroy = candidates[mask] engine.in_nroy(pd.DataFrame([true_params]))[0] # truth ruled out?
load_checkpoint
engine.HistoryMatching.load_checkpoint(
filepath,
sampling_strategy,
feature_selection,
emulator_factory,
)Load engine state from checkpoint file.
nroy_summary
engine.HistoryMatching.nroy_summary()Print and return a text summary of the current NROY region: number of waves and samples, latest NROY fraction, and each parameter’s median with its 95% interval.
plot_constrained_dims
engine.HistoryMatching.plot_constrained_dims(n_top=5, axes=None, **kwargs)Constrained-direction (variance-reduction) plot of the NROY cloud (delegates to historymatching.plotting.plot_constrained_dims).
plot_convergence
engine.HistoryMatching.plot_convergence(ax=None, **kwargs)Plot the NROY fraction per wave (delegates to historymatching.plotting.plot_convergence).
plot_ensemble_fan
engine.HistoryMatching.plot_ensemble_fan(
trajectories,
observed=None,
x=None,
xlabel='Index',
ylabel='Value',
title='Ensemble vs observed',
ax=None,
show=False,
**kwargs,
)Fan/spaghetti plot of an ensemble of trajectories vs observed data.
Delegates to historymatching.plotting.plot_ensemble_fan. Handy for eyeballing how well a set of plausible (NROY) parameter sets reproduces the data.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| trajectories | 2-D array-like, shape (n_runs, n_timepoints) — one row per simulated trajectory. |
required | |
| observed | Optional observed series of length n_timepoints. |
None |
|
| x | Optional x-axis values (defaults to 0..n_timepoints-1). |
None |
|
| xlabel, ylabel, title | Axis labels / title. | required | |
| ax | Optional matplotlib Axes to draw into (a new figure is made if None). | None |
|
| show | bool | If True, call plt.show() before returning. |
False |
| **kwargs | Forwarded to the plotting function (e.g. ci, show_members, show_band). |
{} |
Returns
| Name | Type | Description |
|---|---|---|
The Matplotlib Axes. |
plot_marginals
engine.HistoryMatching.plot_marginals(truth=None, axes=None, **kwargs)Marginal histograms of the NROY samples (delegates to historymatching.plotting.plot_marginals).
plot_nroy
engine.HistoryMatching.plot_nroy(
samples=None,
truth=None,
derived=None,
bins=25,
axes=None,
**kwargs,
)Corner/pairplot of the NROY parameter cloud (delegates to historymatching.plotting.plot_pairplot).
Pass derived to overlay computed quantities, e.g. {'R0': lambda df: df['beta'] / df['gamma']}.
plot_nroy_parameters
engine.HistoryMatching.plot_nroy_parameters(
samples=None,
derived=None,
true_parameters=None,
bins=25,
fig_kwargs=None,
show=False,
)Deprecated alias for plot_nroy.
Deprecated since v2.0.1. Use plot_nroy instead (true_parameters= is now truth=). Retained as a thin forwarder that returns (fig, axes) for backwards compatibility; fig_kwargs is no longer applied.
plot_zscores
engine.HistoryMatching.plot_zscores(ax=None, **kwargs)Standardised outputs vs targets across waves (delegates to historymatching.plotting.plot_zscores_vs_targets).
print_emulator_quality_metrics
engine.HistoryMatching.print_emulator_quality_metrics(iteration=None)Print and return per-feature emulator quality metrics for a wave.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| iteration | Optional[int] | Wave number to report (1-based). Defaults to the most recently committed wave. | None |
Returns
| Name | Type | Description |
|---|---|---|
| dict | Dict mapping feature name -> metrics dict (R², MSE, training size, …). |
revert_step
engine.HistoryMatching.revert_step()Revert the pending iteration results.
This discards the changes from the last step() and returns to the previous state.
Raises
| Name | Type | Description |
|---|---|---|
| RuntimeError | If no pending iteration to revert |
run
engine.HistoryMatching.run(auto_commit=True, resume=False)Run automated history matching workflow.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| auto_commit | bool | Whether to automatically commit each iteration | True |
| resume | bool | If True, load checkpoint from output_dir and continue. If False (default), start fresh. Raises if a checkpoint exists and resume is False (to prevent accidental overwrites). | False |
Returns
| Name | Type | Description |
|---|---|---|
| list[IterationResult] | List of IterationResult objects for all iterations |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If simulation function is not set or configuration is invalid |
save_checkpoint
engine.HistoryMatching.save_checkpoint(filepath)Save engine state to checkpoint file.
save_diagnostics
engine.HistoryMatching.save_diagnostics(directory, verbose=False)Save every committed wave’s artifacts under directory.
Writes one wave{N}/ subdirectory per wave (samples, simulator outputs, pickled emulators, predicted-vs-actual + ARD diagnostic plots, a convergence figure, and metrics.json) by calling IterationResult.save for each wave. This is the manual equivalent of the per-wave output written automatically when output_dir is set.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| directory | str | Directory to write into (created if needed). | required |
| verbose | bool | If True, print the path written for each wave. | False |
step
engine.HistoryMatching.step(features=None)Execute a single history matching iteration.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| features | Optional[list[str]] | Optional list of features to emulate (overrides strategy) | None |
Returns
| Name | Type | Description |
|---|---|---|
| IterationResult | IterationResult for this iteration |
Raises
| Name | Type | Description |
|---|---|---|
| RuntimeError | If engine is not in a valid state for stepping | |
| ValueError | If simulation function is not set or configuration is invalid |
validate
engine.HistoryMatching.validate()Validate the engine’s configuration.
Checks that the required components are present and that all numeric and enumerated options are within their valid ranges. Called automatically at the start of run and step (configuration attributes are public and may be changed after construction); may also be called directly.
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If any required component is missing or an option is invalid. |
IterationSnapshot
engine.IterationSnapshot(
iteration,
parameter_space,
emulator_bank,
result=None,
next_samples=None,
total_samples_generated=0,
total_samples_accepted=0,
acceptance_rate=1.0,
metadata=dict(),
)Snapshot of engine state at a specific iteration.