Reference index

Aggregated Explainer

This module provides the AggregatedExplainer class, which combines multiple explanation methods into one aggregated explanation.

class xai_agg.agg_exp.AggregatedExplainer(explainer_types: list[~typing.Type[~xai_agg.explainers.ExplainerWrapper]], model: ~typing.Any, X_train: ~pandas.core.frame.DataFrame | ~numpy.ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, explainer_params_list: dict[~typing.Type[~xai_agg.explainers.ExplainerWrapper], dict] | None = None, metrics: list[~typing.Literal['complexity', 'sensitivity_spearman', 'faithfulness_corr', 'nrc', 'rb_faithfulness_corr']] = ['complexity', 'sensitivity_spearman', 'faithfulness_corr'], mcdm_method: ~pymcdm.methods.mcda_method.MCDA_method = <pymcdm.methods.topsis.TOPSIS object>, aggregation_algorithm: ~typing.Literal['wsum', 'w_bordafuse', 'w_condorcet'] = 'wsum', **kwargs)

Bases: ExplainerWrapper

An explainer that aggregates multiple explanation methods based on their performance metrics.

This class implements a meta-explainer that combines explanations from multiple underlying explainers. It evaluates each explainer’s performance using various metrics, then uses a Multi-Criteria Decision Making (MCDM) method to assign weights to each explainer. These weighted explanations are then aggregated using a specified algorithm.

Parameters:

  • explainer_types (list[Type[ExplainerWrapper]]) – List of explainer classes to use for generating explanations

  • model (Any) – The machine learning model to explain

  • X_train (pd.DataFrame or np.ndarray) – Training data used for initializing explainers

  • categorical_feature_names (list[str], optional) – Names of categorical features in the dataset

  • predict_fn (callable, optional) – Custom prediction function, defaults to None

  • explainer_params_list (dict[Type[ExplainerWrapper], dict], optional) – Dictionary mapping explainer types to their initialization parameters

  • metrics (list[Literal['complexity', 'sensitivity_spearman', 'faithfulness_corr', 'nrc', 'rb_faithfulness_corr']]) – List of metrics to evaluate explainers with

  • mcdm_method (MCDA_method) – Multi-criteria decision making method used to calculate weights

  • aggregation_algorithm (Literal["wsum", "w_bordafuse", "w_condorcet"]) – Algorithm used to combine multiple explanations

Variables:

  • explainer_types – List of explainer classes

  • explainers – List of instantiated explainer objects

  • xai_evaluator – Evaluator object used to compute metrics for explainers

  • metrics – List of metrics used to evaluate explainers

  • mcdm_method – MCDM method used to determine weights

  • aggregation_algorithm – Algorithm used to combine explanations

  • last_explanation_components – List of explanations from individual explainers for the last instance

  • _last_explanation_weights – Weights assigned to each explainer in the last explanation

  • _last_explanation_metrics – Metrics calculated for each explainer in the last explanation

Note

The aggregation is performed dynamically for each instance based on the performance of each explainer on that specific instance.

explain_instance(instance_data_row: Series) → DataFrame
This method performs the following steps:

  1. Obtains individual explanations from each explainer.

  2. Converts explanations to ranking runs.

  3. Computes performance metrics for each explainer.

  4. Determines aggregation weights based on the computed metrics.

  5. Fuses the individual runs using the specified aggregation algorithm.

Parameters:

instance_data_row (pandas.Series) – The instance to explain, represented as a pandas Series.

Returns:

A DataFrame containing the aggregated explanation, with features as rows and their importance scores as values.

Return type:

pandas.DataFrame

Note

The method stores the individual explainer results in last_explanation_components and the computed metrics in _last_explanation_metrics for later inspection.

get_last_explanation_info() → DataFrame

Returns a DataFrame containing the explanation metrics and weights for the aggregated explainer types for the last explained instance.

The DataFrame’s rows are indexed by the explainer class names, with columns for each metric used in the aggregation plus a ‘weight’ column showing the weight assigned to each explainer.

Returns:

A DataFrame with explanation metrics and weights where: - Each row corresponds to an explainer in self.explainers - Columns include all metrics in self.metrics plus a ‘weight’ column - Index consists of the explainer class names

Return type:

pandas.DataFrame

Experiment Utilities

This module provides utility functions for conducting, analyzing, and visualizing experiments with aggregated explainer models. It includes tools for evaluating explainer performance across different metrics, calculating statistics, and presenting results.

Functions

evaluate_aggregate_explainer

Evaluate aggregated explainers across various configurations, metrics, and algorithms.

get_expconfig_mean_results

Calculate mean results for a specific experiment configuration.

count_worst_case_avoidances

Count instances where an explainer avoids worst-case performance scenarios.

get_average_metric_rank

Calculate average rank of each method across multiple instances for each metric.

present_experiment_run

Present and analyze comprehensive results from an experiment run.

Classes

ExperimentRun

Data container for storing experiment metadata and results.

class xai_agg.exp_utils.ExperimentRun(metadata: dict, results: any)

Bases: object

A dataclass representing a single experiment run.

This class is used to store the metadata and results of an experiment run. It can be used to keep track of experimental settings, hyperparameters, and outcomes.

Variables:

  • metadata (dict) – A dictionary containing metadata about the experiment run, such as hyperparameters, dataset information, model configurations, etc.

  • results (any) – The results of the experiment run. This can be any data type depending on the specific experiment, such as metrics, model outputs, or evaluation results.

metadata: dict
results: any
xai_agg.exp_utils.count_worst_case_avoidances(config_results: list[DataFrame], is_more_better: list[bool], not_avoidence_tolerance: int = 0, row_of_interest='AggregateExplainer')

Count the number of dataframes in which the specified row avoids the worst-case scenario across all columns, with varying levels of tolerance.

Parameters:

  • config_results (list[pd.DataFrame]) – A list of pandas DataFrames containing the results to be analyzed.

  • is_more_better (list[bool]) – A list of boolean values indicating whether a higher value is better (True) or a lower value is better (False) for each column.

  • not_avoidence_tolerance (int, optional) – The tolerance level for not avoiding the worst case. Default is 0.

  • row_of_interest (str, optional) – The index of the row to be analyzed. Default is “AggregateExplainer”.

Returns:

A list of counts where each element represents the number of dataframes in which the row of interest avoids the worst-case scenario with the corresponding level of tolerance.

Return type:

list[int]

xai_agg.exp_utils.evaluate_aggregate_explainer(clf, X_train, X_test, categorical_feature_names, predict_proba=None, explainer_components_sets: list[list[~typing.Type[~xai_agg.explainers.ExplainerWrapper]]] = [[<class 'xai_agg.explainers.LimeWrapper'>, <class 'xai_agg.explainers.ShapTabularTreeWrapper'>, <class 'xai_agg.explainers.AnchorWrapper'>]], mcdm_algs: list[~pymcdm.methods.mcda_method.MCDA_method] = [<pymcdm.methods.topsis.TOPSIS object>], aggregation_algs: list[~typing.Literal['wsum', 'w_bordafuse', 'w_condorcet']] = ['wsum'], metrics_sets: list[list[~typing.Literal['complexity', 'sensitivity_spearman', 'faithfulness_corr', 'rb_faithfulness_corr', 'nrc']]] = [['nrc', 'sensitivity_spearman', 'rb_faithfulness_corr']], extra_explainer_params: dict = {}, n_instances: int = 10, indexes: list[int] | None = None, mp_jobs=10, **kwargs) → list[list[DataFrame]]

Evaluate the aggregate explainer with various settings.

This function evaluates the aggregate explainer by iterating over different combinations of explainer components, MCDM algorithms, aggregation algorithms, and metrics. It returns the results as a list of lists of dataframes, where each dataframe corresponds to an instance check, and each list of dataframes corresponds to a specific setting configuration.

Parameters:

  • clf (object) – The classifier model to be explained

  • X_train (pd.DataFrame) – The training dataset

  • X_test (pd.DataFrame) – The test dataset

  • categorical_feature_names (list[str]) – List of names of categorical features

  • predict_proba (callable, optional) – Function to predict probabilities. If None, clf.predict_proba is used

  • explainer_components_sets (list[list[Type[ExplainerWrapper]]], optional) – List of lists of explainer components to be used in the aggregate explainer

  • mcdm_algs (list[MCDA_method], optional) – List of MCDM (Multi-Criteria Decision Making) algorithms to be used

  • aggregation_algs (list[Literal["wsum", "w_bordafuse", "w_condorcet"]], optional) – List of aggregation algorithms to be used

  • metrics_sets (list[list[Literal['complexity', 'sensitivity_spearman', 'faithfulness_corr', 'nrc']]], optional) – List of lists of metrics to be evaluated

  • extra_explainer_params (dict, optional) – Additional parameters for explainers

  • n_instances (int, optional) – Number of instances to be evaluated. Default is 10

  • indexes (list[int], optional) – List of indexes of instances to be evaluated. If None, random instances are selected

  • mp_jobs (int, optional) – Number of parallel jobs to be used. Default is 10

  • kwargs (dict) – Additional keyword arguments

Returns:

A list of lists of dataframes containing the evaluation results for each instance and setting configuration

Return type:

list[list[pd.DataFrame]]

xai_agg.exp_utils.get_average_metric_rank(config_results: list[DataFrame], is_more_better: list[bool])

Calculate the average rank of each method across multiple instances for each metric.

For each instance in config_results, ranks are assigned to methods based on their performance for each metric, considering whether higher or lower values are better. Then, the average rank across all instances is calculated.

Parameters:

  • config_results (list[pd.DataFrame]) – List of DataFrames where each DataFrame contains the results for one instance. Each DataFrame should have methods as indices and metrics as columns.

  • is_more_better (list[bool]) – List of boolean values indicating whether higher values are better for each metric. True means higher values are better, False means lower values are better. Length should match the number of columns in each DataFrame in config_results.

Returns:

DataFrame containing the average rank of each method across all instances. Methods are in the index, and metrics are in the columns.

Return type:

pd.DataFrame

xai_agg.exp_utils.get_expconfig_mean_results(exp: ExperimentRun, config: int)

Calculate the mean results for a specific experiment configuration.

This function aggregates all results for a given configuration in an experiment and computes the mean values grouped by the 0-level index.

Parameters:

  • exp (ExperimentRun) – The experiment run object containing results

  • config (int) – The configuration index to retrieve results for

Returns:

A DataFrame containing the mean values of all results for the specified configuration, grouped by the 0-level index

Return type:

pandas.DataFrame

xai_agg.exp_utils.present_experiment_run(exp: ExperimentRun, labels: list[Any], is_more_better: list[bool] = [False, True, True])

Presents and analyzes results from an experiment run.

This function displays the results for each method in the experiment, calculates worst-case avoidances, shows the average results, and computes average metric rankings.

Parameters:

  • exp (ExperimentRun) – The experiment run object containing results to be presented

  • labels (list) – Labels for the different methods being compared in the experiment

  • is_more_better (list[bool], optional) – List of boolean flags indicating for each metric whether higher values are better. Defaults to [False, True, True]

Returns:

This function only prints and displays results, it doesn’t return any value

Return type:

None

Note

The function displays various performance metrics and statistics for each method:

  • Raw results

  • Worst case avoidance counts (for all metrics and for 2/3 of metrics)

  • Average results across experiment configurations

  • Average rank for each metric

Explainer Wrappers

This module provides a consistent interface to various explainable AI (XAI) algorithms by wrapping them in the ExplainerWrapper abstract base class and its subclasses. It offers uniform access to different explanation techniques, making them interchangeable in higher-level components like the aggregated explainer.

Classes

  • ExplanationModel

  • ExplainerWrapper

  • LimeWrapper

  • ShapTabularTreeWrapper

  • ShapTabularKernelWrapper

  • AnchorWrapper

Supported Explainer Types

  • LIME: Local Interpretable Model-agnostic Explanations

  • SHAP Tree: Tree-based implementation of SHAP (SHapley Additive exPlanations)

  • SHAP Kernel: Kernel-based implementation of SHAP for any model

  • Anchor: Rule-based explanations with high precision

Examples

import pandas as pd
from sklearn.ensemble import RandomForestClassifier
from xai_agg.explainers import LimeWrapper, ShapTabularTreeWrapper

# Train a model
model = RandomForestClassifier()
model.fit(X_train, y_train)

# Create a LIME explainer
lime_explainer = LimeWrapper(model=model, X_train=X_train)

# Explain a prediction
instance = X_test.iloc[0]
explanation = lime_explainer.explain_instance(instance)
print(explanation)
class xai_agg.explainers.AnchorWrapper(model: Any, X_train: DataFrame | ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, mode: Literal['classification', 'regression', 'auto'] = 'auto', abs_score: bool = True, **additional_args)

Bases: ExplainerWrapper

Wrapper for the Anchor explainer, converting rule-based explanations to feature importance scores.

Anchor typically generates rule-based explanations, not feature importance scores. This wrapper converts Anchor’s rules into a feature importance format by calculating the coverage of each rule and assigning scores to features based on rule coverage: the lower the coverage, the more impactful the feature is considered to be (thus the higher the score).

Parameters:

  • model (Any) – The machine learning model to be explained

  • X_train (pandas.DataFrame or numpy.ndarray) – Training data used to initialize the explainer

  • categorical_feature_names (list[str], optional) – Names of categorical features in the dataset

  • predict_fn (callable, optional) – Custom prediction function, defaults to model.predict_proba or model.predict

  • mode (Literal["classification", "regression", "auto"], optional) – Prediction type (‘classification’, ‘regression’, or ‘auto’), defaults to ‘auto’

  • abs_score (bool, optional) – Whether to return absolute values for feature importance scores, defaults to True

  • additional_args (dict, optional) – Additional arguments to pass to the underlying explainer

Raises:

ValueError – If rule parsing fails due to invalid column names in the data

Note

This wrapper requires data column names to be valid Python variable names/identifiers. Column names should not start with numbers and should not contain spaces or special characters that would make them invalid in Python syntax.

Warning

The rule extraction method may not work correctly for column names that have spaces or don’t contain any alphabetic characters.

explain_instance(instance_data_row: Series | ndarray) → DataFrame[ExplanationModel]

Explains the prediction for a single instance.

This abstract method must be implemented by subclasses to provide specific explanation functionality. The implementation should process the instance and return feature importance scores.

Parameters:

instance_data_row (pandas.Series or numpy.ndarray) – The instance to explain

Returns:

A DataFrame with two columns: ‘feature’ (feature names) and ‘score’ (feature importance values)

Return type:

DataFrame[ExplanationModel]

Note

If self.abs_score is True, all feature importance scores should be returned as absolute values.

class xai_agg.explainers.ExplainerWrapper(model: any, X_train: DataFrame | ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, mode: Literal['classification', 'regression', 'auto'] = 'auto', abs_score: bool = True, **additional_args)

Bases: object

Abstract base class providing a uniform interface for feature-importance explainers.

This class serves as a foundation for wrapping various explainable AI (XAI) algorithms, ensuring they share a common interface. This standardization makes different explanation techniques interchangeable in higher-level components like the AggregatedExplainer.

Parameters:

  • model (Any) – The machine learning model to be explained

  • X_train (pandas.DataFrame or numpy.ndarray) – Training data used to initialize the explainer

  • categorical_feature_names (list[str], optional) – Names of categorical features in the dataset

  • predict_fn (callable, optional) – Custom prediction function, defaults to model.predict_proba or model.predict

  • mode (Literal["classification", "regression", "auto"], optional) – Prediction type (‘classification’, ‘regression’, or ‘auto’), defaults to ‘auto’

  • abs_score (bool, optional) – Whether to return absolute values for feature importance scores, defaults to True

  • additional_args (dict, optional) – Additional arguments to pass to the underlying explainer

Variables:

  • model – The machine learning model being explained

  • predict_fn – Function used to make predictions

  • mode – Prediction type (‘classification’ or ‘regression’)

  • X_train – Training data used to initialize the explainer

  • categorical_feature_names – Names of categorical features

  • abs_score – Whether absolute values are used for feature importance scores

  • additional_args – Additional arguments passed to the underlying explainer

Note

Subclasses must implement the explain_instance method to provide specific explanation functionality.

explain_instance(instance_data_row: Series | ndarray) → DataFrame[ExplanationModel]

Explains the prediction for a single instance.

This abstract method must be implemented by subclasses to provide specific explanation functionality. The implementation should process the instance and return feature importance scores.

Parameters:

instance_data_row (pandas.Series or numpy.ndarray) – The instance to explain

Returns:

A DataFrame with two columns: ‘feature’ (feature names) and ‘score’ (feature importance values)

Return type:

DataFrame[ExplanationModel]

Note

If self.abs_score is True, all feature importance scores should be returned as absolute values.

class xai_agg.explainers.ExplanationModel(*args, **kwargs)

Bases: DataFrameModel

class Config

Bases: Config

name: str | None = 'ExplanationModel'

name of schema

feature: str = 'feature'
score: float = 'score'
class xai_agg.explainers.LimeWrapper(model: any, X_train: DataFrame | ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, mode: Literal['classification', 'regression', 'auto'] = 'auto', abs_score: bool = True, **additional_args)

Bases: ExplainerWrapper

explain_instance(instance_data_row: Series | ndarray) → DataFrame[ExplanationModel]

Explains the prediction for a single instance.

This abstract method must be implemented by subclasses to provide specific explanation functionality. The implementation should process the instance and return feature importance scores.

Parameters:

instance_data_row (pandas.Series or numpy.ndarray) – The instance to explain

Returns:

A DataFrame with two columns: ‘feature’ (feature names) and ‘score’ (feature importance values)

Return type:

DataFrame[ExplanationModel]

Note

If self.abs_score is True, all feature importance scores should be returned as absolute values.

class xai_agg.explainers.ShapTabularKernelWrapper(model: Any, X_train: DataFrame | ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, abs_score: bool = True, **additional_args)

Bases: ExplainerWrapper

explain_instance(instance_data_row: ndarray) → DataFrame[ExplanationModel]

Explains the prediction for a single instance.

This abstract method must be implemented by subclasses to provide specific explanation functionality. The implementation should process the instance and return feature importance scores.

Parameters:

instance_data_row (pandas.Series or numpy.ndarray) – The instance to explain

Returns:

A DataFrame with two columns: ‘feature’ (feature names) and ‘score’ (feature importance values)

Return type:

DataFrame[ExplanationModel]

Note

If self.abs_score is True, all feature importance scores should be returned as absolute values.

class xai_agg.explainers.ShapTabularTreeWrapper(model: Any, X_train: DataFrame | ndarray, categorical_feature_names: list[str] = [], predict_fn: callable | None = None, abs_score: bool = True, **additional_args)

Bases: ExplainerWrapper

explain_instance(instance_data_row: ndarray) → DataFrame[ExplanationModel]

Explains the prediction for a single instance.

This abstract method must be implemented by subclasses to provide specific explanation functionality. The implementation should process the instance and return feature importance scores.

Parameters:

instance_data_row (pandas.Series or numpy.ndarray) – The instance to explain

Returns:

A DataFrame with two columns: ‘feature’ (feature names) and ‘score’ (feature importance values)

Return type:

DataFrame[ExplanationModel]

Note

If self.abs_score is True, all feature importance scores should be returned as absolute values.