Inherent Interpretation

Inherent-interpretation tests for models with intrinsic structure (effects, importance, trees, mixture-of-experts and LLM summaries), exposed by TestSuite.

TestSuite.interpret_effects(features: str | Tuple = None, dataset: str = 'test', grid_size: int = 200)

Analyze and visualize how one or two features influence model predictions through main effects or interaction effects.

This method computes and visualizes how specified features affect the model’s output, allowing for both single and dual feature analysis. It generates visualizations such as line plots, bar plots, or heatmaps based on the type of features provided, and returns a structured result encapsulating the effects and visual options.

Parameters:
featuresstr or tuple of str

Name of single feature or tuple of two feature names to analyze their effects on model output.

  • If features=(“X1”, ) or “X1”, visualize the main effect for X1.

  • If features=(“X1”, “X2”), visualize the interaction for X1 and X2.

  • If features=((“X1”, ), (“X2”, )), visualize the main effect for X1 and X2 separately.

Note: Batch mode for 2D effect plot is not supported. If None, all 1D features will be used.

dataset{“main”, “train”, “test”}, default=”test”

Dataset partition to use for effect calculations. Controls which data points are used to determine the range and importance of effects.

grid_sizeint, default=200

Resolution of the effect visualization grid. Higher values create smoother visualizations but increase computation time.

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_effect”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Value”: Feature values used for effect calculation

    • “Effect”: Calculated effect values

    • “Details”: A dict containing details about the effects

  • table: DataFrame containing the effect results

    • For single feature: columns are “Value” and “Effect”

    • For two features: 2D table with features as row/column indices

  • options: Dictionary of visualizations configuration for a line (1D numerical) / bar (1D categorical) / heatmap (2D) effect plot. Run results.plot() to show all plots; To display one preferred plot by results.plot(name=xxx), and the following names are available:

    • None: Effect plots of all effects specified in features.

    • “<effect_name>”: Effect plot of the selected main effect or pairwise interaction.

Examples

TestSuite.interpret_ei(dataset: str = 'test')

Calculate and visualize global effect importance for model features.

This function computes the global effect importance of features in a specified dataset and generates a visualization of the importance values. It retrieves the feature data, calculates their importance, and returns a structured result containing the feature names, their importance values, and a visualization.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

Dataset partition to use for calculating effect importance. Controls which data points are used in the analysis.

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_ei”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Name”: Names of the features/effects

    • “Importance”: Corresponding importance values

  • table: DataFrame with feature names and importance values

  • options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is importance, and y-axis is the effect names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_local_ei(dataset: str = 'test', sample_index: int = 0)

Calculate and visualize local effect importance for a specific data sample.

This function computes the importance of different features’ effects on the model’s prediction for a single instance and visualizes the results.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

sample_indexint, default=0

Index of the specific sample in the selected dataset to analyze.

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_local_ei”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Name”: List of feature names

    • “Importance”: Feature importance scores

    • “Values”: Feature values for the selected sample

  • table: DataFrame containing feature names and importance values

  • options: Dictionary of visualizations configuration for a horizontal bar-stem plot where x-axis is importance, and y-axis is the feature names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_coef(features: str | Tuple[str] = None)

Extracts and visualizes the coefficients of linear model features.

This function retrieves the coefficients from the model’s main effects and creates both a tabular and graphical representation of the coefficients. The coefficients can be filtered to show only specific features of interest.

Parameters:
featuresstr or tuple of str, default=None

Specific features whose coefficients should be displayed. If None, coefficients for all features will be shown. Can be either a single feature name (str) or multiple feature names (tuple).

Returns:
ValidationResult

A result object containing:

  • key: “interpret_glm_coef”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Name”: List of feature names

    • “Coefficients”: List of corresponding feature coefficients

  • table: pandas DataFrame of feature names and coefficients

  • options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is coefficients, and y-axis is the feature names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_fi(dataset: str = 'test')

Calculate and visualize global feature importance for the model.

This function computes the importance of each feature in the model’s predictions and creates a horizontal bar plot visualization of the results.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_ei”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Name”: List of feature names

    • “Importance”: List of corresponding feature importance values

  • table: DataFrame containing feature names and importance values

  • options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is importance, and y-axis is the feature names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_local_fi(dataset: str = 'test', sample_index: int = 0, centered: bool = True)

Calculates and visualizes feature importance scores for a single sample.

This function computes the local feature importance scores for a specified sample from the dataset, visualizes the results, and returns a structured validation result containing the analysis details.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

sample_indexint, default=0

Index of the specific sample to analyze within the selected dataset

centeredbool, default=True

Whether to center the feature importance scores by subtracting the mean effect of each feature across all samples

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_fi_local”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters used for the analysis

  • value: Dictionary containing:

    • “Name”: List of feature names

    • “Importance”: Feature importance scores

    • “Values”: Original feature values

  • table: DataFrame version of the value dictionary

  • options: Dictionary of visualizations configuration for a horizontal bar-stem plot where x-axis is importance, and y-axis is the feature names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_local_linear_fi(dataset: str = 'test', sample_index: int = 0, centered: bool = True)

Calculate and visualize local feature importance for a specific data sample using linear approximation.

This function computes the local feature importance scores for a given sample from the specified dataset using a linear model. It visualizes the importance scores alongside the original feature values and coefficients, providing insights into the contribution of each feature to the model’s prediction.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

Specifies which dataset partition to use for the analysis.

sample_indexint, default=0

Index of the specific sample in the selected dataset to analyze.

centeredbool, default=True

If True, features are centered by subtracting their mean values before calculating importance scores.

Returns:
ValidationResult

A container object with the following components:

  • key: “interpret_local_linear_fi”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Name”: List of feature names

    • “Importance”: Feature importance scores

    • “Values”: Original feature values

    • “Coefficients”: Linear coefficients

  • table: DataFrame containing feature names, scores, values, and coefficients

  • options: Dictionary of visualizations configuration for a horizontal bar-stem plot where x-axis is importance, and y-axis is the feature names. Run results.plot() to show this plot.

Examples

TestSuite.interpret_global_tree()

Generate a visualization of the complete decision tree model structure.

This method creates a tree diagram showing all nodes and splits in the decision tree model, providing a global view of the model’s decision-making structure.

Returns:
ValidationResult

A result object containing:

  • key: “interpret_tree_global”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • options: Dictionary of visualizations configuration for the global tree diagram. Run results.plot() to show this plot.

Examples

TestSuite.interpret_local_tree(dataset: str = 'test', sample_index: int = 0)

Generate a visualization of the decision path for a specific sample through the decision tree.

This method creates a tree diagram highlighting the specific nodes and path traversed when classifying/predicting a single sample.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

sample_indexint, default=0

The index of the sample in the selected dataset to visualize the decision path for.

Returns:
ValidationResult

A result object containing:

  • key: “interpret_tree_local”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • options: Dictionary of visualizations configuration for the local tree diagram. Run results.plot() to show this plot.

Examples

TestSuite.interpret_local_moe_weights(dataset: str = 'test', sample_index: int = 0)

Calculate and visualize expert weights for a specific sample.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The dataset containing the sample to analyze.

sample_indexint, default=0

The index of the sample in the selected dataset.

Returns:
ValidationResult

Contains mixture-of-experts weight analysis:

  • key: “interpret_local_moe_weights”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary with expert names, weights, feature names and values

  • options: Dictionary of visualizations configuration for a bar plot where x-axis is expert id, and y-axis is the expert weights. Run results.plot() to show this plot.

Examples

TestSuite.interpret_effects_moe_average(features: str | Tuple, dataset: str = 'test', grid_size: int = 100, sample_size: int = 5000, random_state: int = 0)

Analyze feature effects averaged across all mixture-of-experts clusters.

Parameters:
featuresstr or tuple/list of str

One or two feature names to analyze. If two features are provided, their interaction effect is analyzed.

dataset{“main”, “train”, “test”}, default=”test”

The dataset to use for the analysis.

grid_sizeint, default=100

Number of points to evaluate for creating the visualization grid.

sample_sizeint, default=5000

Maximum number of random samples to use for calculation efficiency. If None, uses all data.

random_stateint, default=0

Random seed for reproducible sampling.

Returns:
ValidationResult

Contains averaged effect analysis results:

  • key: “interpret_effects_moe_average”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Weighted average effect values

  • table: Tabular representation of results

  • options: Dictionary of visualizations configuration for a line (1D numerical) / bar (1D categorical) / heatmap (2D) averaged effect plot. Run results.plot() to show this plot.

Examples

TestSuite.interpret_moe_cluster_analysis(dataset: str = 'test', metric: str = None)

Analyze and summarize characteristics of mixture-of-experts clusters.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The dataset to analyze cluster assignments.

metricstr, metric=None

Model performance metric to use.

  • For classification (default=”AUC”): “ACC”, “AUC”, “F1”, “LogLoss”, “Precision”, “Recall”, and “Brier”

  • For regression (default=”MSE”): “MSE”, “MAE”, and “R2”

Returns:
ValidationResult

Contains cluster analysis results:

  • key: “interpret_cluster_analysis”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Nested dictionary containing the (“<expert_id>”, item) pairs for each group, and the item is also a dictionary with:

    • “size”: Number of samples in cluster

    • “score”: The performance metric of this cluster

    • “center”: Cluster centroid coordinates

    • “data_info”: Sample indices for in/out of cluster comparison, which can be further used for data distribution test, e.g.,

      data_results = ds.data_drift_test(**results.value[2]["data_info"])
data_results.plot("summary")
data_results.plot(("density", "MedInc"))

  • table: DataFrame with performance metrics for each cluster

  • options: Dictionary of visualizations configuration. Run results.plot(name=xxx) to show all plots; Run results.plot(name=xxx) to display one preferred plot; and the following names are available:

    • “cluster_performance”: Bar plot visualizing the performance scores of final MOE model against each cluster.

Examples

TestSuite.interpret_llm_summary(dataset: str = 'test')

This method generates a table populated with unwrapper summary statistics.

The statistics include count, response mean, response std deviation, local MSE/AUC and global MSE/AUC for selected top LLMs

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

Returns:
ValidationResult

A container object with the following components:

  • key: “llm_summary”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • table: DataFrame containing summary statistics including:

    • “count”

    • “response mean”

    • “response standard deviation”

    • “local MSE/AUC”

    • “global MSE/AUC”

Examples

TestSuite.interpret_llm_pc(dataset: str = 'test')

Generate and visualize parallel coordinate plots for Local Linear Model (LLM) coefficients.

This function calculates LLM statistics, feature importance, and creates a parallel coordinate plot to visualize the relationships between features and their coefficients across different local linear models.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

Returns:
ValidationResult

A container object with the following components:

  • key: “llm_pc”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “Names”: Feature names

    • “Bias & Weights”: LLM coefficients including bias terms

    • “STD_DEV”: Standard deviations of LLM predictions

    • “Importance”: Feature importance scores

  • options: Dictionary of visualizations configuration for a parallel coordinate plot where x-axis is feature names, and y-axis is the local linear coefficients. Run results.plot() to show this plot.

Examples

TestSuite.interpret_llm_profile(feature: str = None, dataset: str = 'test')

Calculate local feature importance for a specific feature using LLM profiles.

This function computes the local feature importance for a given feature by analyzing the LLM profiles and visualizes the results. It retrieves the necessary data, calculates the feature importance, and generates a plot that illustrates the distribution of feature importance across different LLMs.

Parameters:
featurestr

Feature name to explain.

dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

nllmsint, default=30

The number of top LLMs to show.

Returns:
ValidationResult

A container object with the following components:

  • key: “llm_profile”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “feature”: Name of the feature being analyzed

    • “sample_idx_by_llms”: Sample indices grouped by LLMs

    • “feature_names”: List of feature names

    • “feature_importance”: Feature importance scores

  • options: Dictionary of visualizations configuration for a LLM profile plot. Run results.plot() to show this plot.

Examples

TestSuite.interpret_llm_violin(feature: str = None, dataset: str = 'test')

Generates the LLM coefficients and statistics. (Violin plot under development)

This function processes the specified dataset to calculate the LLM coefficients and their associated statistics, ultimately returning a ValidationResult object that encapsulates the results of the analysis, including feature names, importance scores, and bias weights.

Parameters:
dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

Returns:
ValidationResult

A container object with the following components:

  • key: “llm_violin”

  • data: Name of the dataset used

  • model: Name of the model used

  • inputs: Input parameters

  • value: Dictionary containing:

    • “feature_names”: List of feature names

    • “all_bias_weight”: LLM coefficients including bias terms

    • “count_llms”: Count of LLMs

    • “feature_importance”: Feature importance scores

Examples