pyuncertainnumber.calibration.epistemic_filter

Classes

EpistemicFilter

The EpistemicFilter method to reduce the epistemic uncertainty space based on discrepancy scores.

Functions

filter_by_discrepancy(→ tuple)

Computes the intersection of convex hull bounding boxes based on a discrepancy threshold.

plot_convex_hull_with_bounds(filtered_xe[, hull, ax, ...])

Plot points, their convex hull, and the axis-aligned bounding box.

intersect_convex_hulls(hulls)

Compute intersection of several ConvexHull polytopes.

plot_multiple_convex_hulls(xe_list[, hulls, ...])

Plot multiple 2D point sets with their convex hulls.

Module Contents

class pyuncertainnumber.calibration.epistemic_filter.EpistemicFilter(xe_samples: numpy.typing.NDArray, discrepancy_scores: numpy.typing.NDArray = None, sets_of_discrepancy: list = None)

The EpistemicFilter method to reduce the epistemic uncertainty space based on discrepancy scores.

Parameters:

  • xe_samples (NDArray) – Proposed Samples of epistemic parameters, shape (ne, n_dimensions). Typically samples from a bounded set of some epistemic parameters.

  • discrepancy_scores (NDArray, optional) – Discrepancy scores between the model simulations and the observation. Associated with each xe sample, shape (ne,). Defaults to None.

  • sets_of_discrepancy (list, optional) – List of sets of discrepancy scores for multiple datasets. Each element should be an NDArray of shape (ne,). Defaults to None.

Tip

For performance functions that output multiple responses, some aggregation of discrepancy scores may be used. Depending on the number of observation, either a single set of discrepancy scores or multiple sets can be provided.

convex hull with bounds

Convex hull with bounds illustration.

xe_samples
discrepancy_scores = None
sets_of_discrepancy
filter(threshold: float | list)

Filter the epistemic samples based on a discrepancy threshold.

Parameters:

threshold (float | list) – The discrepancy threshold(s) for filtering data points.

Returns:

  • the filtered xe samples;

  • hull;

  • lower bounds;

  • upper bounds of the bounding box, or (None, None) if unsuccessful.

Return type:

tuple

iterative_filter(thresholds: list) → list

Iteratively filter the epistemic samples based on multiple thresholds.

Parameters:

  • thresholds (list) – List of discrepancy thresholds for filtering data points.

  • simulation_model (callable, optional) – A function that takes xe_samples as input and returns discrepancy scores. Required if re_sample is True. Defaults to None.

Note

thresholds are assumed to be sorted in ascending order.

iterative_filter_w_simulation_model(thresholds: list, re_sample: bool = False, simulation_model=None)

Iteratively filter the epistemic samples based on multiple thresholds.

Parameters:

  • thresholds (list) – List of discrepancy thresholds for filtering data points.

  • re_sample (bool, optional) – If True, re-evaluate discrepancy scores at each iteration using the simulation_model. Defaults to False.

  • simulation_model (callable, optional) – A function that takes xe_samples as input and returns discrepancy scores. Required if re_sample is True. Defaults to None.

Note

if re_sample is True, the simulation_model should be provided to re-evaluate discrepancy scores.

filter_on_sets(plot_hulls: bool = True)

Filter the epistemic samples based on multiple sets of discrepancy scores.

Parameters:

plot_hulls (bool, optional) – If True, plots the convex hulls of the first five sets. Defaults to True.

Returns:

  • lower bounds;

  • upper bounds of the intersected bounding box, or (None, None) if unsuccessful

Return type:

tuple

Note

self.sets_of_discrepancy must exist.

plot_hull_with_bounds(filtered_xe, hull=None, ax=None, show=True, x_title=None, y_title=None, hull_alpha=0.25)

Plot the convex hull and bounding box of the epistemic samples.

Parameters:

  • hull (ConvexHull, optional) – Precomputed convex hull. If None, it is computed.

  • ax (matplotlib Axes, optional) – Existing axes to draw on. If None, a new figure/axes is created.

  • show (bool, optional) – If True, calls plt.show() at the end. Defaults to True.

  • x_title (str, optional) – Label for the x-axis. Defaults to None.

  • y_title (str, optional) – Label for the y-axis. Defaults to None.

  • hull_alpha (float, optional) – Transparency of the hull surface. Defaults to 0.25.

Returns:

The axes containing the plot.

Return type:

ax (matplotlib Axes)

pyuncertainnumber.calibration.epistemic_filter.filter_by_discrepancy(xe_samples, discrepancy_scores, threshold=0.1) → tuple

Computes the intersection of convex hull bounding boxes based on a discrepancy threshold.

Parameters:

threshold (float) – The scalar discrepancy threshold for filtering data points.

Returns:

the hull, and Lower and upper bounds of the intersected bounding box, or (None, None) if unsuccessful.

Return type:

tuple

Note

Assume the threshold is a scalar value.

pyuncertainnumber.calibration.epistemic_filter.plot_convex_hull_with_bounds(filtered_xe: numpy.typing.NDArray, hull=None, ax=None, show=True, x_title=None, y_title=None, hull_alpha=0.25)

Plot points, their convex hull, and the axis-aligned bounding box.

args: filtered_xe (NDArray): array-like, shape (n_samples, n_dims)

Input points. Supports 2D or 3D.

hullscipy.spatial.ConvexHull, optional

Precomputed convex hull. If None, it is computed.

axmatplotlib Axes or 3D Axes, optional

Existing axes to draw on. If None, a new figure/axes is created.

showbool, default True

If True, calls plt.show() at the end.

hull_alphafloat, default 0.25

Transparency of the hull surface.

Returns:

matplotlib.figure.Figure ax : matplotlib.axes.Axes or mplot3d.Axes3D hull : scipy.spatial.ConvexHull min_bound : ndarray max_bound : ndarray

Return type:

fig

pyuncertainnumber.calibration.epistemic_filter.intersect_convex_hulls(hulls)

Compute intersection of several ConvexHull polytopes. Works in 2D or 3D (and in principle higher).

Parameters:

hulls – list of scipy.spatial.ConvexHull

Returns:

(m, d) ndarray

Vertices of the intersection polytope (may be empty).

hull_intConvexHull or None

ConvexHull of the intersection vertices, or None if empty.

Return type:

vertices

pyuncertainnumber.calibration.epistemic_filter.plot_multiple_convex_hulls(xe_list, hulls=None, show_bounds=True, hull_alpha=0.25, ax=None, show=True)

Plot multiple 2D point sets with their convex hulls.

Parameters:

  • xe_list – list of ndarray Each array must be shape (n_i, 2)

  • hulls – list of ConvexHull or None If None, hulls are computed automatically.

  • show_bounds – bool Whether to draw dashed bounding rectangles.

  • hull_alpha – float Transparency of hull fill.

  • ax – matplotlib Axes Optional existing axes.

  • show – bool Whether to call plt.show()

Returns:

fig, ax, hulls