calibrated_explanations.core.CalibratedExplainer¶

class calibrated_explanations.core.CalibratedExplainer(learner, x_cal, y_cal, mode='classification', feature_names=None, categorical_features=None, categorical_labels=None, class_labels=None, bins=None, difficulty_estimator=None, **kwargs)[source]¶

Bases: object

Initialize the explainer with calibration data and metadata.

Parameters:

learner (Any) – Predictive learner that must already expose fit/predict and, for classification, predict_proba.
x_cal (array-like of shape (n_calibration_samples, n_features)) – Calibration feature matrix used to fit interval calibrators.
y_cal (array-like of shape (n_calibration_samples,)) – Calibration targets paired with x_cal.
mode ({"classification", "regression"}, default="classification") – Operating mode controlling which calibrators/plugins are used.
feature_names (Sequence[str] or None, optional) – Optional list of human-readable feature names.
categorical_features (Sequence[int] or None, optional) – Indices describing which features should be treated as categorical.
categorical_labels (Mapping[int, Mapping[int, str]] or None, optional) – Optional mapping translating categorical feature values to labels.
class_labels (Mapping[int, str] or None, optional) – Optional mapping translating class indices to display labels.
bins (array-like or None, optional) – Pre-computed Mondrian categories for fast explanations.
difficulty_estimator (Any or None, optional) – Optional crepes DifficultyEstimator instance for regression tasks.
**kwargs (Any) – Advanced configuration flags preserved for backward compatibility. Includes condition_source (“observed” or “prediction”, default=”prediction”).

Notes

Minimal lifecycle logging is available at INFO level. To enable, run:

import logging
logging.getLogger("calibrated_explanations").setLevel(logging.INFO)

Attributes:

bridge_monitors: Public alias for _bridge_monitors.
calibration_summary_shape: Return the calibration summary shape.
categorical_value_counts_cache: Return the categorical value counts cache.
explanation_orchestrator: Return the ExplanationOrchestrator provisioned by the PluginManager.
explanation_plugin_instances: Public alias for _explanation_plugin_instances.
explanation_plugin_overrides: Public alias for _explanation_plugin_overrides.
fast: Whether to use fast mode.
fast_interval_plugin_override: Public alias for _fast_interval_plugin_override.
feature_filter_config: Return the feature filter configuration.
feature_filter_per_instance_ignore: Return the per-instance feature filter ignore list.
feature_names: Get the feature names.
feature_names_internal: Public alias for _feature_names.
initialized: Return True if the explainer is initialized.
interval_context_metadata: Public alias for _interval_context_metadata.
interval_learner: Access the interval learner managed by the prediction orchestrator.
interval_plugin_fallbacks: Public alias for _interval_plugin_fallbacks.
interval_plugin_hints: Public alias for _interval_plugin_hints.
interval_plugin_identifiers: Public alias for _interval_plugin_identifiers.
interval_plugin_override: Public alias for _interval_plugin_override.
interval_preferred_identifier: Public alias for _interval_preferred_identifier.
is_initialized: Public check for whether the explainer has been initialized.
last_explanation_mode: Return the mode of the last generated explanation.
lime_helper: Public alias for _lime_helper.
noise_type: The type of noise to use.
num_features: Get the number of features in the calibration data.
numeric_sorted_cache: Return the numeric sorted cache.
parallel_executor: Return the active parallel executor.
perf_parallel: Public alias for _perf_parallel.
plot_plugin_fallbacks: Return the plot plugin fallback configuration.
plot_style_chain: Return the plot style chain.
plot_style_override: Public alias for _plot_style_override.
plugin_manager: Public accessor for the active PluginManager.
predict_bridge: Return the prediction bridge.
prediction_orchestrator: Return the PredictionOrchestrator provisioned by the PluginManager.
preprocessor_metadata: Return the telemetry-safe preprocessing snapshot if available.
pyproject_explanations: Public alias for _pyproject_explanations.
pyproject_intervals: Public alias for _pyproject_intervals.
pyproject_plots: Public alias for _pyproject_plots.
reject_orchestrator: Return the RejectOrchestrator provisioned by the PluginManager.
runtime_telemetry: Return the most recent telemetry payload reported by the explainer.
scale_factor: The scale factor for perturbations.
severity: The severity of perturbations.
shap_helper: Public alias for _shap_helper.
telemetry_interval_sources: Public alias for _telemetry_interval_sources.
x_cal: Get the calibration input data.
y_cal: Get the calibration target data.

Methods

`__call__`(x[, threshold, ...])	Call self as a function to create a `CalibratedExplanations` object for the test data with the already assigned discretizer.
`append_cal`(x, y)	Append new calibration data.
`build_instance_telemetry_payload`(explanations)	Delegate to ExplanationOrchestrator.
`build_plot_style_chain`()	Return the plot style chain.
`calibrated_confusion_matrix`()	Generate a calibrated confusion matrix.
`close`()	Reset runtime state, then shutdown any provisioned parallel pool.
`discretize`(data)	Apply the discretizer to input data.
`enable_fast_mode`()	Enable fast explanation mode.
`ensure_interval_runtime_state`()	Delegate to PredictionOrchestrator.
`explain_factual`(x[, threshold, ...])	Create a `CalibratedExplanations` object for the test data with the discretizer automatically assigned for factual explanations.
`explain_fast`(x[, threshold, ...])	Create a `CalibratedExplanations` object for the test data.
`explain_guarded_factual`(x[, threshold, ...])	Create guarded factual explanations that only use in-distribution perturbations.
`explore_alternatives`(x[, threshold, ...])	Create a `AlternativeExplanations` object for the test data with the discretizer automatically assigned for alternative explanations.
`explore_guarded_alternatives`(x[, threshold, ...])	Create guarded alternative explanations that only use in-distribution perturbations.
`gather_interval_hints`(*, fast)	Delegate to PredictionOrchestrator.
`get_calibration_summaries`([x_cal_np])	Return cached categorical counts and sorted numeric calibration values.
`get_plugin_manager`()	Return the active plugin manager, applying any derived defaults.
`get_sigma_test`(x)	Return the difficulty (sigma) of the test instances.
`infer_explanation_mode`()	Infer the explanation mode from runtime state.
`initialize_interval_learner_for_fast_explainer`(...)	Public alias for internal interval learner initialization.
`initialize_pool`([n_workers, pool_at_init])	Create a ParallelExecutor for this explainer.
`initialize_reject_learner`([calibration_set, ...])	Initialize the reject learner with a threshold value.
`instantiate_plugin`(prototype)	Delegate to ExplanationOrchestrator.
`invoke_explanation_plugin`(mode, x, ...[, ...])	Delegate to ExplanationOrchestrator.
`is_fast`()	Test if the explainer uses fast mode.
`is_mondrian`()	Test if Mondrian (per-bin) calibration is enabled.
`is_multiclass`()	Test if it is a multiclass problem.
`obtain_interval_calibrator`(*, fast, metadata)	Return the interval calibrator from the prediction orchestrator.
`plot`(x[, y, threshold])	Generate plots for the test data.
`predict`(x[, uq_interval, calibrated])	Generate predictions for the test data.
`predict_calibration`()	Predict the target values for the calibration data.
`predict_proba`(x[, uq_interval, calibrated, ...])	Generate probability predictions for the test data.
`predict_reject`(x[, bins, confidence])	Predict whether to reject the explanations for the test data.
`reinitialize`(learner[, xs, ys, bins])	Reinitialize the explainer with a new learner.
`require_plugin_manager`()	Return the plugin manager or raise if the explainer is not initialized.
`reset`()	Clear transient runtime state retained between explanation calls.
`resolve_parallel_executor`(explicit_executor)	Resolve the parallel executor honoring overrides and environment config.
`rule_boundaries`(instances[, perturbed_instances])	Extract the rule boundaries for a set of instances.
`set_difficulty_estimator`(difficulty_estimator)	Assign or update the difficulty estimator.
`set_discretizer`(discretizer[, x_cal, y_cal, ...])	Assign the discretizer to be used.
`set_mode`(mode[, initialize])	Assign the mode of the explainer.
`set_preprocessor_metadata`(metadata)	Update the stored preprocessing metadata snapshot.

require_plugin_manager() → PluginManager[source]¶

Return the plugin manager or raise if the explainer is not initialized.

Returns:: The active plugin manager instance.
Return type:: PluginManager
Raises:: NotFittedError – If the plugin manager is not initialized.

get_plugin_manager() → PluginManager[source]¶

Return the active plugin manager, applying any derived defaults.

Wrapper layers must not mutate plugin manager state directly. Any runtime-derived plugin preferences (for example, feature filter execution requirements) are enforced here so orchestration remains centralized in the explainer/manager layers.

resolve_parallel_executor(explicit_executor: Any | None) → Any | None[source]¶: Resolve the parallel executor honoring overrides and environment config.

initialize_pool(n_workers: int | None = None, *, pool_at_init: bool = False) → None[source]¶

Create a ParallelExecutor for this explainer.

Parameters:

n_workers (int | None) – Optional maximum worker count to enforce.
pool_at_init (bool) – If True, enter the pool immediately so worker processes are spawned at initialization time (useful for warm-up and initializer-based harness installation).

close() → None[source]¶: Reset runtime state, then shutdown any provisioned parallel pool.

reset() → None[source]¶: Clear transient runtime state retained between explanation calls.

infer_explanation_mode() → str[source]¶: Infer the explanation mode from runtime state.

property prediction_orchestrator: Any¶: Return the PredictionOrchestrator provisioned by the PluginManager.

property explanation_orchestrator: Any¶: Return the ExplanationOrchestrator provisioned by the PluginManager.

property reject_orchestrator: Any¶: Return the RejectOrchestrator provisioned by the PluginManager.

build_plot_style_chain() → Tuple[str, ...][source]¶

Return the plot style chain.

This is the public replacement for the legacy internal helper. It delegates to PluginManager to construct the chain when available and otherwise returns an empty tuple for minimal explainer stubs used in tests.

property plot_style_chain: Tuple[str, ...]¶

Return the plot style chain.

This property provides access to the current plot style chain used by the explainer.

instantiate_plugin(prototype: Any) → Any[source]¶: Delegate to ExplanationOrchestrator.

build_instance_telemetry_payload(explanations: Any) → Dict[str, Any][source]¶: Delegate to ExplanationOrchestrator.

invoke_explanation_plugin(mode: str, x: Any, threshold: Any, low_high_percentiles: Any, bins: Any, features_to_ignore: Any, *, extras: Mapping[str, Any] | None = None, reject_policy: Any | None = None) → Any[source]¶: Delegate to ExplanationOrchestrator.

ensure_interval_runtime_state() → None[source]¶: Delegate to PredictionOrchestrator.

gather_interval_hints(*, fast: bool) → Tuple[str, ...][source]¶: Delegate to PredictionOrchestrator.

property plot_plugin_fallbacks: Dict[str, Tuple[str, ...]]¶

Return the plot plugin fallback configuration.

Returns:: Mapping of mode to fallback identifiers.
Return type:: Dict[str, Tuple[str, …]]

property plugin_manager: PluginManager¶: Public accessor for the active PluginManager.

property interval_plugin_hints: Dict[str, Tuple[str, ...]]¶

Public alias for _interval_plugin_hints.

Tests should use this instead of accessing the private attribute.

property interval_plugin_fallbacks: Dict[str, Tuple[str, ...]]¶: Public alias for _interval_plugin_fallbacks.

property explanation_plugin_overrides: Dict[str, Any]¶: Public alias for _explanation_plugin_overrides.

property interval_plugin_override: Any¶: Public alias for _interval_plugin_override.

property fast_interval_plugin_override: Any¶: Public alias for _fast_interval_plugin_override.

property plot_style_override: Any¶: Public alias for _plot_style_override.

property interval_preferred_identifier: Dict[str, str | None]¶: Public alias for _interval_preferred_identifier.

property telemetry_interval_sources: Dict[str, str | None]¶: Public alias for _telemetry_interval_sources.

property feature_names_internal: Any¶: Public alias for _feature_names.

property perf_parallel: bool¶: Public alias for _perf_parallel.

initialize_interval_learner_for_fast_explainer(*args, **kwargs) → Any[source]¶: Public alias for internal interval learner initialization.

property interval_plugin_identifiers: Dict[str, str | None]¶: Public alias for _interval_plugin_identifiers.

property interval_context_metadata: Dict[str, Dict[str, Any]]¶: Public alias for _interval_context_metadata.

property bridge_monitors: Dict[str, Any]¶: Public alias for _bridge_monitors.

property explanation_plugin_instances: Dict[str, Any]¶: Public alias for _explanation_plugin_instances.

property pyproject_explanations: Dict[str, Any] | None¶: Public alias for _pyproject_explanations.

property pyproject_intervals: Dict[str, Any] | None¶: Public alias for _pyproject_intervals.

property pyproject_plots: Dict[str, Any] | None¶: Public alias for _pyproject_plots.

property lime_helper: Any¶: Public alias for _lime_helper.

property shap_helper: Any¶: Public alias for _shap_helper.

property initialized: bool¶: Return True if the explainer is initialized.

property is_initialized: bool¶: Public check for whether the explainer has been initialized.

Deprecated since version 0.10.1: Use initialized instead.

property last_explanation_mode: str | None¶: Return the mode of the last generated explanation.

property feature_filter_per_instance_ignore: Any¶: Return the per-instance feature filter ignore list.

property parallel_executor: Any¶: Return the active parallel executor.

property feature_filter_config: Any¶: Return the feature filter configuration.

property predict_bridge: Any¶: Return the prediction bridge.

property categorical_value_counts_cache: Any¶: Return the categorical value counts cache.

property numeric_sorted_cache: Any¶: Return the numeric sorted cache.

property calibration_summary_shape: Any¶: Return the calibration summary shape.

enable_fast_mode() → None[source]¶

Enable fast explanation mode.

This initializes the interval learner for fast explanations if not already done.

property runtime_telemetry: Mapping[str, Any]¶: Return the most recent telemetry payload reported by the explainer.

property preprocessor_metadata: Dict[str, Any] | None¶: Return the telemetry-safe preprocessing snapshot if available.

set_preprocessor_metadata(metadata: Mapping[str, Any] | None) → None[source]¶: Update the stored preprocessing metadata snapshot.

property x_cal¶

Get the calibration input data.

Returns:: The calibration input data.
Return type:: array-like

property y_cal¶

Get the calibration target data.

Returns:: The calibration target data.
Return type:: array-like

append_cal(x, y)[source]¶

Append new calibration data.

Parameters:

x (array-like of shape (n_samples, n_features)) – The new calibration input data to append.
y (array-like of shape (n_samples,)) – The new calibration target data to append.

get_calibration_summaries(x_cal_np: ndarray | None = None) → Tuple[Dict[int, Dict[Any, int]], Dict[int, ndarray]][source]¶

Return cached categorical counts and sorted numeric calibration values.

Delegates to the calibration.summaries module which manages caching of statistical summaries used during explanation generation.

property num_features¶

Get the number of features in the calibration data.

Returns:: The number of features in the calibration data. For dictionary input, returns the number of keys. For array input, returns the number of columns.
Return type:: int

property feature_names¶

Get the feature names.

Returns:: The list of feature names. If no feature names were provided during initialization, returns None.
Return type:: list

property interval_learner: Any¶

Access the interval learner managed by the prediction orchestrator.

Returns:: The interval calibrator (e.g., VennAbers, IntervalRegressor, or list for fast mode).
Return type:: Any

Notes

This is a backward-compatible property that delegates to the interval registry managed by the PredictionOrchestrator. See ADR-001.

get_sigma_test(x: ndarray) → ndarray[source]¶

Return the difficulty (sigma) of the test instances.

Parameters:: x (np.ndarray) – Test instances for which to estimate difficulty.
Returns:: Difficulty estimates (sigma values) for each test instance.
Return type:: np.ndarray

reinitialize(learner, xs=None, ys=None, bins=None)[source]¶

Reinitialize the explainer with a new learner.

This is useful when the learner is updated or retrained and the explainer needs to be reinitialized.

Parameters:

learner (predictive learner) – A predictive learner that can be used to predict the target variable. The learner must be fitted and have a predict_proba method (for classification) or a predict method (for regression).
xs (array-like, optional) – New calibration input data to append
ys (array-like, optional) – New calibration target data to append

Returns:

A CalibratedExplainer object that can be used to explain predictions from a predictive learner.

Return type:

CalibratedExplainer

obtain_interval_calibrator(*, fast: bool, metadata: Mapping[str, Any]) → Tuple[Any, str | None][source]¶: Return the interval calibrator from the prediction orchestrator.

explain_factual(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, _use_plugin: bool = True, **kwargs) → CalibratedExplanations[source]¶

Create a CalibratedExplanations object for the test data with the discretizer automatically assigned for factual explanations.

This is a thin delegator that sets up the appropriate discretizer and delegates to the orchestrator.

Parameters:

x (array-like) – A set with n_samples of test objects to predict.
threshold (float, int or array-like, default=None) – Values for which p-values should be returned. Only used for probabilistic explanations for regression.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories
**kwargs (dict) – Additional arguments passed to the explanation orchestrator.

Returns:

CalibratedExplanations – A CalibratedExplanations containing one FactualExplanation for each instance.

Return type:

CalibratedExplanations

explore_alternatives(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, _use_plugin: bool = True, **kwargs) → AlternativeExplanations[source]¶

Create a AlternativeExplanations object for the test data with the discretizer automatically assigned for alternative explanations.

This is a thin delegator that sets up the appropriate discretizer and delegates to the orchestrator.

Parameters:

x (array-like) – A set with n_samples of test objects to predict.
threshold (float, int or array-like, default=None) – Values for which p-values should be returned. Only used for probabilistic explanations for regression.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories
**kwargs (dict) – Additional arguments passed to the explanation orchestrator.

Returns:

AlternativeExplanations

Return type:

AlternativeExplanations

Notes

The explore_alternatives will eventually be used instead of the explain_counterfactual method.

explain_guarded_factual(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, _use_plugin: bool = True, significance: float = 0.1, merge_adjacent: bool = False, n_neighbors: int = 5, normalize_guard: bool = True, verbose: bool = False, **kwargs)[source]¶

Create guarded factual explanations that only use in-distribution perturbations.

Unlike explain_factual(), which uses a binary (max_depth=1) discretiser, this method uses the same multi-bin (max_depth=3) discretiser as explore_alternatives(). For each leaf an in-distribution guard tests whether the representative perturbation is conforming to the calibration distribution; leaves that fail the test are filtered out.

Rule conditions are intervals such as "30 < age <= 50" rather than simple threshold splits. Adjacent conforming bins can optionally be merged into wider intervals (merge_adjacent=True).

Parameters:

x (array-like) – A set with n_samples of test objects to explain.
threshold (float, int or array-like, optional) – Values for which p-values should be returned. Only used for probabilistic regression.
low_high_percentiles (tuple of float, default=(5, 95)) – The low and high percentile used to calculate the interval.
bins (array-like of shape (n_samples,), optional) – Mondrian categories.
features_to_ignore (sequence of int or str, optional) – Features to exclude from explanations.
significance (float, default=0.1) – Acceptable false-OOD rate. Bins are considered conforming when p_value >= significance; bins below that threshold are treated as out-of-distribution and not included.
merge_adjacent (bool, default=False) – When True, merge adjacent conforming bins into a single wider interval condition.
n_neighbors (int, default=5) – Number of nearest calibration neighbours used by the in-distribution guard for computing non-conformity scores.
normalize_guard (bool, default=True) – Apply per-feature min-max normalisation before computing KNN distances inside the guard.
verbose (bool, default=False) – When True, emit UserWarnings for guarded-explanation diagnostics.
**kwargs (dict) – Additional arguments (reserved for future use).

Returns:

A CalibratedExplanations container whose individual explanations are GuardedFactualExplanation instances.

Return type:

CalibratedExplanations

explore_guarded_alternatives(x, threshold=None, low_high_percentiles=(5, 95), bins=None, features_to_ignore=None, *, _use_plugin: bool = True, significance: float = 0.1, merge_adjacent: bool = False, n_neighbors: int = 5, normalize_guard: bool = True, verbose: bool = False, **kwargs)[source]¶

Create guarded alternative explanations that only use in-distribution perturbations.

This method extends explore_alternatives() with an in-distribution guard: for each leaf of the multi-bin discretiser, it tests whether perturbing the feature to the leaf’s representative value (while keeping all other features at their original level) produces an instance that is conforming to the calibration distribution. Non-conforming leaves are excluded from the alternatives.

Rule conditions are intervals such as "30 < age <= 50"; for the current (factual) bin a factual rule is also stored (is_factual=True). Adjacent conforming bins can optionally be merged (merge_adjacent=True).

Parameters:

x (array-like) – A set with n_samples of test objects to explain.
threshold (float, int or array-like, optional) – Values for which p-values should be returned. Only used for probabilistic regression.
low_high_percentiles (tuple of float, default=(5, 95)) – The low and high percentile used to calculate the interval.
bins (array-like of shape (n_samples,), optional) – Mondrian categories.
features_to_ignore (sequence of int or str, optional) – Features to exclude from explanations.
significance (float, default=0.1) – Acceptable false-OOD rate. Bins are considered conforming when p_value >= significance; bins below that threshold are treated as out-of-distribution and not included as alternatives.
merge_adjacent (bool, default=False) – When True, merge adjacent conforming bins into a single wider interval condition.
n_neighbors (int, default=5) – Number of nearest calibration neighbours used by the in-distribution guard for computing non-conformity scores.
normalize_guard (bool, default=True) – Apply per-feature min-max normalisation before computing KNN distances inside the guard.
verbose (bool, default=False) – When True, emit UserWarnings for guarded-explanation diagnostics.
**kwargs (dict) – Additional arguments (reserved for future use).

Returns:

An AlternativeExplanations container whose individual explanations are GuardedAlternativeExplanation instances.

Return type:

AlternativeExplanations

explain_fast(x, threshold=None, low_high_percentiles=(5, 95), bins=None, *, reject_policy: Any | None = None, _use_plugin: bool = True) → CalibratedExplanations[source]¶

Create a CalibratedExplanations object for the test data.

Parameters:

x (array-like) – A set with n_samples of test objects to predict
threshold (float, int or array-like of shape (n_samples,), default=None) – values for which p-values should be returned. Only used for probabilistic explanations for regression.
low_high_percentiles (a tuple of floats, default=(5, 95)) – The low and high percentile used to calculate the interval. Applicable to regression.
bins (array-like of shape (n_samples,), default=None) – Mondrian categories

Raises:

ValueError – The number of features in the test data must be the same as in the calibration data.:
Warning – The threshold-parameter is only supported for mode=’regression’.:
ValueError – The length of the threshold parameter must be either a constant or the same as the number of: instances in x.
RuntimeError – Fast explanations are only possible if the explainer is a Fast Calibrated Explainer.:

Returns:

CalibratedExplanations – A CalibratedExplanations containing one FastExplanation for each instance.

Return type:

CalibratedExplanations

is_multiclass() → bool[source]¶

Test if it is a multiclass problem.

Returns:: True if multiclass (num_classes > 2).
Return type:: bool

is_fast() → bool[source]¶

Test if the explainer uses fast mode.

Returns:: True if fast mode is enabled.
Return type:: bool

is_mondrian() → bool[source]¶

Test if Mondrian (per-bin) calibration is enabled.

Returns:: True if bins are configured, indicating Mondrian calibration.
Return type:: bool

discretize(data: ndarray) → ndarray[source]¶

Apply the discretizer to input data.

Parameters:: data (np.ndarray) – The data to discretize.
Returns:: The discretized data.
Return type:: np.ndarray

rule_boundaries(instances, perturbed_instances=None)[source]¶

Extract the rule boundaries for a set of instances.

Parameters:

instances (array-like) – The instances to extract boundaries for.
perturbed_instances (array-like, optional) – Discretized versions of instances. Defaults to None.

Returns:

Min and max values for each feature for each instance.

Return type:

array-like

set_difficulty_estimator(difficulty_estimator, initialize=True) → None[source]¶

Assign or update the difficulty estimator.

If initialized to a difficulty estimator, the explainer can be used to reject explanations that are deemed too difficult.

Parameters:

difficulty_estimator (crepes.extras.DifficultyEstimator or None):) – A crepes.extras.DifficultyEstimator object from the crepes package. To remove the crepes.extras.DifficultyEstimator, set to None.
(bool (initialize) – If true, then the interval learner is initialized once done. Defaults to True.
optional) – If true, then the interval learner is initialized once done. Defaults to True.

set_mode(mode, initialize=True) → None[source]¶

Assign the mode of the explainer. The mode can be either ‘classification’ or ‘regression’.

Parameters:

(str) (mode)
(bool (initialize)
optional) (If true, then the interval learner is initialized once done. Defaults to True.)

Raises:

ValueError – The mode can be either ‘classification’ or ‘regression’.:

initialize_reject_learner(calibration_set=None, threshold=None, ncf=None, w=0.5)[source]¶

Initialize the reject learner with a threshold value.

Deprecated since version 0.11.1: Use reject_orchestrator.initialize_reject_learner instead. This wrapper will be removed no earlier than v0.13.0.

Parameters:

calibration_set (array-like, optional) – Optional calibration set override.
threshold (float, optional) – Decision threshold (required for regression reject calibration).
ncf (str or None, default None) – Non-conformity function type.
w (float, default 0.5) – Blending weight used only when ncf='ensured'. Ignored for ncf='default'.

Returns:

The initialized reject learner.

Return type:

Any

predict_reject(x, bins=None, confidence=0.95)[source]¶

Predict whether to reject the explanations for the test data.

Deprecated since version 0.11.1: Use reject_orchestrator.predict_reject instead. This wrapper will be removed no earlier than v0.13.0.

Parameters:

x (array-like) – The test data.
bins (array-like, optional) – Mondrian categories for conditional calibration.
confidence (float, default=0.95) – Confidence level used by the reject predictor.

Returns:

Rejection decisions and summary rates.

Return type:

tuple

set_discretizer(discretizer, x_cal=None, y_cal=None, features_to_ignore=None, *, condition_source: str | None = None) → None[source]¶

Assign the discretizer to be used.

Parameters:

discretizer (str or discretizer object) – The discretizer to be used.
x_cal (array-like, optional) – The calibration data for the discretizer.
y_cal (array-like, optional) – The calibration target data for the discretizer.

predict(x, uq_interval=False, calibrated=True, **kwargs)[source]¶

Generate predictions for the test data.

Parameters:

x (array-like) – The test data.
uq_interval (bool, default=False) – Whether to return uncertainty intervals.
calibrated (bool, default=True) – If True, the calibrator is used for prediction. If False, the underlying learner is used for prediction.
**kwargs (Various types, optional) –
Additional parameters to customize the explanation process. Supported parameters include:
- thresholdfloat, int, or array-like of shape (n_samples,), optional, default=None
  Specifies the threshold for probabilistic regression. Returns calibrated probabilities P(y <= threshold) for regression tasks. This parameter is ignored for classification tasks.
- low_high_percentilestuple of two floats, optional, default=(5, 95)
  The lower and upper percentiles used to calculate the prediction interval for regression tasks. Determines the breadth of the interval based on the distribution of the predictions. This parameter is ignored for classification tasks and when threshold is provided.

Raises:

RuntimeError – If the learner has not been fitted prior to making predictions.
Warning – If the learner is not calibrated.

Returns:

calibrated_prediction (float or array-like, or str) – The calibrated prediction. For regression tasks without threshold, this is the median of the conformal predictive system. For probabilistic regression (with threshold), this is a probability P(y <= threshold). For classification tasks, it is the class label with the highest calibrated probability.
interval (tuple of floats, optional) – A tuple (low, high) representing the lower and upper bounds of the uncertainty interval. This is returned only if uq_interval=True.

Examples

For a prediction without prediction intervals:

w.predict(x)

For a prediction with uncertainty quantification intervals:

w.predict(x, uq_interval=True)

Notes

The threshold and low_high_percentiles parameters are only used for regression tasks.

predict_proba(x, uq_interval=False, calibrated=True, threshold=None, **kwargs)[source]¶

Generate probability predictions for the test data.

This is a wrapper around the predict_proba method which is more similar to the scikit-learn predict_proba method for classification. As opposed to predict_proba, this method may output uncertainty intervals.

Parameters:

x (array-like) – The test data for which predictions are to be made. This should be in a format compatible with sklearn (e.g., numpy arrays, pandas DataFrames).
uq_interval (bool, default=False) – If true, then the prediction interval is returned as well.
calibrated (bool, default=True) – If True, the calibrator is used for prediction. If False, the underlying learner is used for prediction.
threshold (float, int or array-like of shape (n_samples,), optional, default=None) – Threshold values used with regression to get probability of being below the threshold. Only applicable to regression.

Raises:

RuntimeError – If the learner is not fitted before predicting.
ValueError – If the threshold parameter’s length does not match the number of instances in x, or if it is not a single constant value applicable to all instances.
RuntimeError – If the learner is not fitted before predicting.
Warning – If the learner is not calibrated.

Returns:

calibrated probability – The calibrated probability of the positive class (or the predicted class for multiclass).
(low, high) (tuple of float lists, corresponding to the lower and upper bound of each prediction interval.)

Examples

For a prediction without uncertainty quantification intervals:

w.predict_proba(x)

For a prediction with uncertainty quantification intervals:

w.predict_proba(x, uq_interval=True)

Notes

The threshold parameter is only used for regression tasks.

plot(x, y=None, threshold=None, **kwargs)[source]¶: Generate plots for the test data.

calibrated_confusion_matrix()[source]¶

Generate a calibrated confusion matrix.

Generates a confusion matrix for the calibration set to provide insights about model behavior. The confusion matrix is only available for classification tasks. Stratified cross-validation is used on the calibration set to generate the confusion matrix while avoiding quadratic recalibration overhead.

Returns:: The calibrated confusion matrix.
Return type:: array-like

predict_calibration()[source]¶

Predict the target values for the calibration data.

Returns:: Predicted values for the calibration data. For models that expose a hat matrix, this returns updated predictions using that matrix; otherwise it uses the predict_function on the calibration data.
Return type:: array-like

property fast: bool¶

Whether to use fast mode.

Returns:: True if fast mode is enabled.
Return type:: bool

property noise_type: str¶

The type of noise to use.

Returns:: The noise type.
Return type:: str

property scale_factor: float | None¶

The scale factor for perturbations.

Returns:: The scale factor.
Return type:: float | None

property severity: float | None¶

The severity of perturbations.

Returns:: The severity.
Return type:: float | None