Plotting Functions

Overview

The fdfi.plots module provides static Matplotlib visualizations for FDFI diagnostics and results. All functions return Matplotlib objects and accept show=False for tests, scripts, and documentation builds.

Typical inputs come directly from explainer results:

results = explainer(X_test)
ci = explainer.conf_int(alpha=0.05, target="X")
feature_names = [f"X{i}" for i in range(X_test.shape[1])]

summary_bar(results["phi_X"], results["se_X"], feature_names, show=False)
summary_plot(explainer.ueifs_X, features=X_test, feature_names=feature_names, show=False)
confidence_interval_plot(ci, feature_names=feature_names, show=False)
diagnostics_plot(explainer.diagnostics, feature_names=feature_names, show=False)

Global Importance

fdfi.plots.summary_bar(phi_X, se_X=None, feature_names=None, group_colors=None, savepath=None, max_display=None, ax=None, show=True, **kwargs)[source]

Plot global FDFI feature importance as a sorted bar chart.

Parameters:

  • phi_X (array-like of shape (n_features,)) – Global FDFI scores such as results["phi_X"] or results["phi_Z"]. Bar lengths use abs(phi_X) so signed attribution summaries are also supported.

  • se_X (array-like of shape (n_features,), optional) – Standard errors such as results["se_X"]. Missing values default to zero. NaN, inf, and negative entries are sanitized before plotting.

  • feature_names (sequence of str, optional) – Feature names. Defaults to Feature 0, Feature 1, …

  • group_colors (mapping, optional) – Mapping from feature name to a Matplotlib color. Missing features use a neutral gray. When omitted, a colormap gradient is used.

  • savepath (str, optional) – Path where the figure should be saved.

  • max_display (int, optional) – Maximum number of features to show.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • **kwargs – Styling options. Common keys include figsize, title, cmap, capsize, elinewidth, dpi, and bbox_inches.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object.

  • importance_df (pandas.DataFrame) – Sorted table with columns feature, phi, and se.

Examples

>>> fig, ax, table = summary_bar(
...     results["phi_X"],
...     se_X=results["se_X"],
...     feature_names=feature_names,
...     show=False,
... )

summary_bar is the public global bar-chart API for aggregate arrays such as results["phi_X"] and results["phi_Z"]. It sorts features by absolute importance, sanitizes missing or infinite standard errors, supports optional feature-color mappings, and returns the sorted table used for plotting.

Summary Plot

fdfi.plots.summary_plot(shap_values, features=None, feature_names=None, max_display=20, show=True, ax=None, savepath=None, **kwargs)[source]

Create a SHAP-like summary plot for FDFI attributions.

Parameters:

  • shap_values (array-like of shape (n_features,) or (n_samples, n_features)) – FDFI attribution values. Use aggregate arrays such as results["phi_X"] for bar summaries, or per-sample arrays such as explainer.ueifs_X for beeswarm summaries.

  • features (array-like of shape (n_samples, n_features), optional) – Feature values used for point colors in a 2D beeswarm plot.

  • feature_names (sequence of str, optional) – Feature names.

  • max_display (int, default=20) – Maximum number of features to display.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options. For 1D input, forwarded to summary_bar().

Returns:

  • fig, ax (tuple) – Matplotlib figure and axes for 2D input.

  • fig, ax, importance_df (tuple) – For 1D input, the return value from summary_bar().

Examples

>>> summary_plot(explainer.ueifs_X, features=X_test, show=False)
>>> summary_plot(results["phi_X"], se_X=results["se_X"], show=False)

summary_plot draws a SHAP-like dot summary for 2D per-sample attribution arrays such as explainer.ueifs_X or explainer.ueifs_Z. For 1D aggregate arrays, it delegates to summary_bar.

Single-Explanation Views

fdfi.plots.waterfall_plot(shap_values, features=None, feature_names=None, max_display=10, base_value=0.0, show=True, ax=None, savepath=None, **kwargs)[source]

Create a single-explanation waterfall plot.

Parameters:

  • shap_values (array-like of shape (n_features,)) – Single-sample FDFI attributions, for example explainer.ueifs_X[0].

  • features (array-like of shape (n_features,), optional) – Feature values for label annotations.

  • feature_names (sequence of str, optional) – Feature names.

  • max_display (int, default=10) – Maximum number of features to display. Extra features are summed into a final “remaining features” row.

  • base_value (float, default=0.0) – Starting value for the additive explanation.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options.

Returns:

fig, ax – Matplotlib figure and axes.

Return type:

tuple

Examples

>>> waterfall_plot(explainer.ueifs_X[0], feature_names=feature_names, show=False)
fdfi.plots.force_plot(base_value, shap_values, features=None, feature_names=None, max_display=10, show=True, ax=None, savepath=None, **kwargs)[source]

Create a static force-style contribution plot.

Parameters:

  • base_value (float) – Baseline model output.

  • shap_values (array-like of shape (n_features,) or (n_samples, n_features)) – FDFI attributions. If a 2D array is supplied, values are averaged across samples before plotting.

  • features (array-like, optional) – Feature values for single-sample label annotations.

  • feature_names (sequence of str, optional) – Feature names.

  • max_display (int, default=10) – Maximum number of features to display. Extra features are grouped.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options.

Returns:

fig, ax – Matplotlib figure and axes.

Return type:

tuple

Examples

>>> force_plot(0.0, explainer.ueifs_X[0], feature_names=feature_names, show=False)

Use these for one row of per-sample UEIFs:

waterfall_plot(explainer.ueifs_X[0], feature_names=feature_names, show=False)
force_plot(0.0, explainer.ueifs_X[0], feature_names=feature_names, show=False)

Dependence Plot

fdfi.plots.dependence_plot(feature_idx, shap_values, features, feature_names=None, interaction_index=None, show=True, ax=None, savepath=None, **kwargs)[source]

Create a feature-dependence scatter plot.

Parameters:

  • feature_idx (int or str) – Feature index or feature name to plot.

  • shap_values (array-like of shape (n_samples, n_features)) – Per-sample FDFI attributions such as explainer.ueifs_X.

  • features (array-like of shape (n_samples, n_features)) – Feature values for the same samples.

  • feature_names (sequence of str, optional) – Feature names. Required when feature_idx or interaction_index is a string.

  • interaction_index (int or str, optional) – Feature used to color points.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options.

Returns:

fig, ax – Matplotlib figure and axes.

Return type:

tuple

Examples

>>> dependence_plot("age", explainer.ueifs_X, X_test,
...                 feature_names=feature_names, show=False)

dependence_plot accepts integer or string feature identifiers and can color points by an interaction feature:

dependence_plot(
    "X0",
    explainer.ueifs_X,
    X_test,
    feature_names=feature_names,
    interaction_index="X1",
    show=False,
)

Feature Correlation

fdfi.plots.correlation_heatmap(X_background, feature_names=None, savepath=None, show=True, ax=None, **kwargs)[source]

Plot a clustered Pearson correlation heatmap for background features.

Parameters:

  • X_background (array-like of shape (n_samples, n_features)) – Background or training feature matrix used to estimate correlation structure.

  • feature_names (sequence of str, optional) – Feature names. Defaults to Feature 0, Feature 1, …

  • savepath (str, optional) – Path where the figure should be saved.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • **kwargs – Styling options including figsize, cmap, vmin, vmax, fontsize, dpi, and bbox_inches.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object containing the heatmap.

  • feature_names_reordered (list of str) – Feature names in clustered order.

Examples

>>> correlation_heatmap(X_background, feature_names, show=False)

The heatmap uses Pearson correlation and hierarchical clustering based on 1 - abs(correlation) to reveal correlated feature blocks in the background data.

Inference and Diagnostics

fdfi.plots.confidence_interval_plot(ci_results, feature_names=None, max_display=20, ax=None, show=True, savepath=None, **kwargs)[source]

Plot FDFI confidence intervals from conf_int() output.

Parameters:

  • ci_results (mapping) – Dictionary returned by explainer.conf_int(). Required keys are score, ci_lower, and ci_upper. reject_null and ranking are used when present.

  • feature_names (sequence of str, optional) – Feature names. If ci_results contains groups, those group names are used by default.

  • max_display (int, default=20) – Maximum number of rows to display.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options.

Returns:

fig, ax – Matplotlib figure and axes.

Return type:

tuple

Examples

>>> ci = explainer.conf_int(alpha=0.05, target="X")
>>> confidence_interval_plot(ci, feature_names=feature_names, show=False)
fdfi.plots.diagnostics_plot(diagnostics, feature_names=None, ax=None, show=True, savepath=None, **kwargs)[source]

Plot FDFI disentanglement diagnostics.

Parameters:

  • diagnostics (mapping) – Diagnostics dictionary from an explainer. Existing keys include latent_independence_median, distribution_fidelity_mmd, latent_independence_label, distribution_fidelity_label, and optionally latent_independence_dcor.

  • feature_names (sequence of str, optional) – Feature names for the latent dCor matrix when displayed.

  • ax (matplotlib.axes.Axes, optional) – Existing axes for the scalar diagnostics bar plot. When omitted and a dCor matrix is available, a two-panel figure is created.

  • show (bool, default=True) – Whether to display the figure via plt.show().

  • savepath (str, optional) – Path where the figure should be saved.

  • **kwargs – Styling options.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax_or_axes (matplotlib.axes.Axes or numpy.ndarray) – The axes object(s).

Examples

>>> diagnostics_plot(explainer.diagnostics, show=False)

confidence_interval_plot accepts dictionaries returned by conf_int(), including feature-level and grouped outputs. diagnostics_plot accepts the shared diagnostics dictionaries exposed by OTExplainer, EOTExplainer, and FlowExplainer.