Plotting Functions

Overview

The fdfi.plots module provides visualization functions for feature importance, similar to SHAP’s plotting capabilities. These functions help you understand and communicate model explanations.

Note

Plotting functions require the plots extra dependency:

pip install -e ".[plots]"

Summary Plot

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

Create a summary plot of feature importance.

This function creates a visualization showing the distribution of feature importance values across samples.

Parameters:

  • shap_values (numpy.ndarray) – Feature importance values from an explainer. Shape (n_samples, n_features).

  • features (numpy.ndarray, optional) – Feature values. Shape (n_samples, n_features).

  • feature_names (list, optional) – Names of features.

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

  • **kwargs (dict) – Additional plotting parameters.

Return type:

None

Examples

>>> import numpy as np
>>> from fdfi.plots import summary_plot
>>>
>>> # Create dummy data
>>> shap_values = np.random.randn(100, 10)
>>> feature_names = [f"Feature {i}" for i in range(10)]
>>>
>>> # Create plot (when implemented)
>>> # summary_plot(shap_values, feature_names=feature_names)

The summary plot shows the distribution of feature importance values across all samples, with features ordered by their overall importance.

Example:

from fdfi.plots import summary_plot

# After computing explanations
results = explainer(X_test)

# Create summary visualization
summary_plot(results["phi_X"], features=X_test, feature_names=feature_names)

Waterfall Plot

fdfi.plots.waterfall_plot(shap_values, features=None, feature_names=None, max_display=10, **kwargs)[source]

Create a waterfall plot for a single prediction.

This function shows how each feature contributes to pushing the prediction from the base value.

Parameters:

  • shap_values (numpy.ndarray) – Feature importance values for a single sample. Shape (n_features,).

  • features (numpy.ndarray, optional) – Feature values for the sample. Shape (n_features,).

  • feature_names (list, optional) – Names of features.

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

  • **kwargs (dict) – Additional plotting parameters.

Return type:

None

Examples

>>> import numpy as np
>>> from fdfi.plots import waterfall_plot
>>>
>>> # Create dummy data for one sample
>>> shap_values = np.random.randn(10)
>>> feature_names = [f"Feature {i}" for i in range(10)]
>>>
>>> # Create plot (when implemented)
>>> # waterfall_plot(shap_values, feature_names=feature_names)

The waterfall plot shows how each feature contributes to pushing the prediction from the base value for a single sample.

Example:

from fdfi.plots import waterfall_plot

# Explain a single prediction
waterfall_plot(
    results["phi_X"][0],  # First sample
    feature_names=feature_names,
    max_display=10
)

Force Plot

fdfi.plots.force_plot(base_value, shap_values, features=None, feature_names=None, **kwargs)[source]

Create a force plot visualization.

This function creates an interactive force plot showing how features contribute to the prediction.

Parameters:

  • base_value (float) – The base value (expected value of the model output).

  • shap_values (numpy.ndarray) – Feature importance values. Can be 1D for a single sample or 2D for multiple samples.

  • features (numpy.ndarray, optional) – Feature values.

  • feature_names (list, optional) – Names of features.

  • **kwargs (dict) – Additional plotting parameters.

Return type:

None

Examples

>>> import numpy as np
>>> from fdfi.plots import force_plot
>>>
>>> # Create dummy data
>>> base_value = 0.5
>>> shap_values = np.random.randn(10)
>>> feature_names = [f"Feature {i}" for i in range(10)]
>>>
>>> # Create plot (when implemented)
>>> # force_plot(base_value, shap_values, feature_names=feature_names)

The force plot is an interactive visualization showing feature contributions as forces pushing the prediction higher or lower.

Example:

from fdfi.plots import force_plot

force_plot(
    base_value=0.5,
    shap_values=results["phi_X"][0],
    feature_names=feature_names
)

Dependence Plot

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

Create a dependence plot for a feature.

This function shows the relationship between a feature’s value and its impact on the model’s prediction.

Parameters:

  • feature_idx (int or str) – Index or name of the feature to plot.

  • shap_values (numpy.ndarray) – Feature importance values. Shape (n_samples, n_features).

  • features (numpy.ndarray) – Feature values. Shape (n_samples, n_features).

  • feature_names (list, optional) – Names of features.

  • interaction_index (int or str, optional) – Feature to use for coloring points (interaction effects).

  • **kwargs (dict) – Additional plotting parameters.

Return type:

None

Examples

>>> import numpy as np
>>> from fdfi.plots import dependence_plot
>>>
>>> # Create dummy data
>>> shap_values = np.random.randn(100, 10)
>>> features = np.random.randn(100, 10)
>>> feature_names = [f"Feature {i}" for i in range(10)]
>>>
>>> # Create plot (when implemented)
>>> # dependence_plot(0, shap_values, features, feature_names=feature_names)

The dependence plot shows the relationship between a feature’s value and its contribution to the model output, optionally colored by another feature to show interaction effects.

Example:

from fdfi.plots import dependence_plot

# Show dependence for feature 0
dependence_plot(
    feature_idx=0,
    shap_values=results["phi_X"],
    features=X_test,
    feature_names=feature_names
)