"""
Plotting utilities for DFI.
This module provides visualization functions for feature importance,
similar to SHAP's plotting capabilities.
"""
import numpy as np
from typing import Optional, Union, Any
[docs]
def summary_plot(
shap_values: np.ndarray,
features: Optional[np.ndarray] = None,
feature_names: Optional[list] = None,
max_display: int = 20,
**kwargs: Any
) -> None:
"""
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.
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)
"""
raise NotImplementedError(
"summary_plot is not yet implemented. "
"Please refer to the documentation for upcoming features."
)
[docs]
def waterfall_plot(
shap_values: np.ndarray,
features: Optional[np.ndarray] = None,
feature_names: Optional[list] = None,
max_display: int = 10,
**kwargs: Any
) -> None:
"""
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.
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)
"""
raise NotImplementedError(
"waterfall_plot is not yet implemented. "
"Please refer to the documentation for upcoming features."
)
[docs]
def force_plot(
base_value: float,
shap_values: np.ndarray,
features: Optional[np.ndarray] = None,
feature_names: Optional[list] = None,
**kwargs: Any
) -> None:
"""
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.
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)
"""
raise NotImplementedError(
"force_plot is not yet implemented. "
"Please refer to the documentation for upcoming features."
)
[docs]
def dependence_plot(
feature_idx: Union[int, str],
shap_values: np.ndarray,
features: np.ndarray,
feature_names: Optional[list] = None,
interaction_index: Optional[Union[int, str]] = None,
**kwargs: Any
) -> None:
"""
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.
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)
"""
raise NotImplementedError(
"dependence_plot is not yet implemented. "
"Please refer to the documentation for upcoming features."
)