shap API Reference
Full documentation for shap (0.52.0)
shap.ActionOptimizer
Python Library Documentation: class ActionOptimizer in module shap.actions._optimizer class ActionOptimizer(builtins.object) | ActionOptimizer(model, actions: 'list[Action | list[Action]]') | | Methods defined here: | | __call__(self, *args, max_evals=10000) | Call self as a function. | | __init__(self, model, actions: 'list[Action | list[Action]]') | Initialize self. See help(type(self)) for accurate signature. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
shap.AdditiveExplainer
Python Library Documentation: class AdditiveExplainer in module shap.explainers._additive
class AdditiveExplainer(shap.explainers._explainer.Explainer)
| AdditiveExplainer(model: Any, masker: Any, link: Any = None, feature_names: list[str] | None = None, linearize_link: bool = True) -> None
|
| Computes SHAP values for generalized additive models.
|
| This assumes that the model only has first-order effects. Extending this to
| second- and third-order effects is future work (if you apply this to those models right now
| you will get incorrect answers that fail additivity).
|
| Method resolution order:
| AdditiveExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: Any, max_evals: Union[int, Literal['auto']] = 'auto', main_effects: bool = False, error_bounds: bool = False, batch_size: Union[int, Literal['auto']] = 'auto', outputs: Any = None, silent: bool = False, **kwargs: Any) -> Any
| Explains the output of model(*args), where args represents one or more parallel iterable args.
|
| __init__(self, model: Any, masker: Any, link: Any = None, feature_names: list[str] | None = None, linearize_link: bool = True) -> None
| Build an Additive explainer for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form ``masker(mask, *fargs)``.
| It takes a single a binary mask and an input sample and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking used by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a ``shap.maskers.Tabular(data, hclustering="correlation")`` object, but
| note that this structure information has no effect on the explanations of additive models.
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: Any, masker: Any) -> bool
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_expected_value': float | numpy.ndarray[typing.Any...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.Any
Python Library Documentation: class Any in module typing class Any(builtins.object) | Any(*args, **kwargs) | | Special type indicating an unconstrained type. | | - Any is compatible with every type. | - Any assumed to have all methods. | - All values assumed to be instances of Any. | | Note that all the above statements are true from the point of view of | static type checkers. At runtime, Any should not be used with instance | checks. | | Static methods defined here: | | __new__(cls, *args, **kwargs) | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
shap.CoalitionExplainer
Python Library Documentation: class CoalitionExplainer in module shap.explainers._coalition
class CoalitionExplainer(shap.explainers._explainer.Explainer)
| CoalitionExplainer(model: 'Any', masker: 'Any', *, output_names: 'list[str] | None' = None, link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'list[str] | None' = None, partition_tree: 'dict[str, Any] | None' = None) -> 'None'
|
| A coalition-based explainer that uses Winter values, also called recursive Owen values, to explain model predictions.
|
| This explainer implements a coalition-based approach to compute feature attributions
| using Winter values, which extend Shapley values to handle hierarchical feature groupings.
| Essentially the attributions are computed using the marginals respecting the partition tree, reducing the complexity of computation.
|
| It is particularly useful when features can be grouped into coalitions or
| hierarchies, in the case of temporal, multimodal data (e.g., demographic features, financial features, etc.).
| Textual and image data is not yet implemented.
|
| The explainer supports both single and multi-output models, and can handle various
| types of input data through the provided masker.
|
| Example usage
| --------
| >>> import shap
| >>> import numpy as np
| >>> import pandas as pd
| >>> from sklearn.ensemble import RandomForestClassifier
| >>> from sklearn.datasets import load_iris
| >>>
| >>> # Load data and train model
| >>> X, y = load_iris(return_X_y=True)
| >>> model = RandomForestClassifier().fit(X, y)
| >>>
| >>> # Define feature groups
| >>> coalition_tree = {
| ... "Sepal": ["sepal length (cm)", "sepal width (cm)"],
| ... "Petal": ["petal length (cm)", "petal width (cm)"]
| ... }
| >>> # Define feature names, or you can pass X as a DataFrame
| >>> feature_names = ["sepal length (cm)", "sepal width (cm)",
| "petal length (cm)", "petal width (cm)"]
| >>> masker = shap.maskers.Partition(X)
| >>> masker.feature_names = feature_names
| >>>
| >>> # Create explainer
| >>> explainer = shap.CoalitionExplainer(
| ... model.predict,
| ... masker,
| ... partition_tree=coalition_tree
| ... )
| >>>
| >>> # Compute SHAP values
| >>> shap_values = explainer(X[:5]
|
| Method resolution order:
| CoalitionExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: 'int' = 500, fixed_context: 'int | None' = None, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: 'int | str' = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Any'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: 'Any', masker: 'Any', *, output_names: 'list[str] | None' = None, link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'list[str] | None' = None, partition_tree: 'dict[str, Any] | None' = None) -> 'None'
| Initialize the coalition explainer with a model and masker.
|
| Parameters
| ----------
| model : callable or shap.models.Model
| A callable that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # outputs).
|
| masker : shap.maskers.Masker
| A masker object that defines how to mask features and compute background
| values. This should be compatible with the input data format.
|
| output_names : list of str, optional
| Names for each of the model outputs. If None, the output names will be
| determined from the model if possible.
|
| link : callable, optional
| The link function used to map between the output units of the model and the
| SHAP value units. By default, the identity function is used.
|
| linearize_link : bool, optional
| If True, the link function is linearized around the expected value to
| improve the accuracy of the SHAP values. Default is True.
|
| feature_names : list of str, required
| Names for each of the input features. If None, feature names will be
| determined from the masker if possible.
|
| partition_tree : dict, required
| A dictionary defining a custom hierarchical grouping of features. This is for users who want to
| define partitions based on domain knowledge. For automatic binary clustering, please use the
| `PartitionExplainer`. Each key represents a group name, and its value is either a list of
| feature names or another dictionary defining subgroups. Note all input features must be included
| in the leaf nodes.
| For example:
| {
| "Demographics": ["Age", "Gender", "Education"],
| "Financial": {
| "Income": ["Salary", "Bonus"],
| "Assets": ["Savings", "Investments"]
| }
| }
|
| Notes
| -----
| - The explainer supports both single and multi-output models.
| - The partition_tree parameter is used to define feature coalitions for
| computing Owen values, which can provide more meaningful explanations
| when features are naturally grouped.
| - The masker should be compatible with the input data format and provide
| appropriate background values for computing SHAP values.
|
| __str__(self) -> 'str'
| Return str(self).
|
| explain_row(self, *row_args: 'Any', max_evals: 'int' = 100, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: 'int | str' = 'auto', outputs: 'Any' = None, silent: 'bool' = False, fixed_context: 'int | str | None' = 'auto') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_clustering': 'Any', '_curr_base_value': 'npt.NDAr...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.Cohorts
Python Library Documentation: class Cohorts in module shap._explanation
class Cohorts(builtins.object)
| Cohorts(**kwargs: 'Explanation') -> 'None'
|
| A collection of :class:`.Explanation` objects, typically each explaining a cluster of similar samples.
|
| Examples
| --------
| A ``Cohorts`` object can be initialized in a variety of ways.
|
| By explicitly specifying the cohorts:
|
| >>> exp = Explanation(
| ... values=np.random.uniform(low=-1, high=1, size=(500, 5)),
| ... data=np.random.normal(loc=1, scale=3, size=(500, 5)),
| ... feature_names=list("abcde"),
| ... )
| >>> cohorts = Cohorts(
| ... col_a_neg=exp[exp[:, "a"].data < 0],
| ... col_a_pos=exp[exp[:, "a"].data >= 0],
| ... )
| >>> cohorts
| <shap._explanation.Cohorts object with 2 cohorts of sizes: [(198, 5), (302, 5)]>
|
| Or using the :meth:`.Explanation.cohorts` method:
|
| >>> cohorts2 = exp.cohorts(3)
| >>> cohorts2
| <shap._explanation.Cohorts object with 3 cohorts of sizes: [(182, 5), (12, 5), (306, 5)]>
|
| Most of the :class:`.Explanation` interface is also exposed in ``Cohorts``. For example, to retrieve the
| SHAP values corresponding to column 'a' across all cohorts, you can use:
|
| >>> cohorts[..., 'a'].values
| <shap._explanation.Cohorts object with 2 cohorts of sizes: [(198,), (302,)]>
|
| To actually retrieve the values of a particular :class:`.Explanation`, you'll need to access it via the
| :meth:`.Cohorts.cohorts` property:
|
| >>> cohorts.cohorts["col_a_neg"][..., 'a'].values
| array([...]) # truncated
|
| Methods defined here:
|
| __call__(self, *args: 'Any', **kwargs: 'Any') -> 'Cohorts'
| Call the bound methods on the Explanation objects retrieved during attribute access.
|
| For example,
| ``Cohorts(...).mean(axis=0)`` would first run ``__getattr__("mean")`` and return a bound method
| ``Explanation.mean`` for all the :class:`Explanation` objects inside the ``Cohorts``, returned as a
| new ``Cohorts`` object. Then the ``(axis=0)`` call would be executed on that returned ``Cohorts``
| object, which is why we need ``__call__`` defined.
|
| __getattr__(self, name: 'str') -> 'Cohorts'
|
| __getitem__(self, item) -> 'Cohorts'
|
| __init__(self, **kwargs: 'Explanation') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| cohorts
| Internal collection of cohorts, stored as a dictionary.
shap.DeepExplainer
Python Library Documentation: class DeepExplainer in module shap.explainers._deep
class DeepExplainer(shap.explainers._explainer.Explainer)
| DeepExplainer(model, data, session=None, learning_phase_flags=None)
|
| Meant to approximate SHAP values for deep learning models.
|
| This is an enhanced version of the DeepLIFT algorithm (Deep SHAP) where, similar to Kernel SHAP, we
| approximate the conditional expectations of SHAP values using a selection of background samples.
| Lundberg and Lee, NIPS 2017 showed that the per node attribution rules in DeepLIFT (Shrikumar,
| Greenside, and Kundaje, arXiv 2017) can be chosen to approximate Shapley values. By integrating
| over many background samples, Deep estimates approximate SHAP values such that they sum
| up to the difference between the expected model output on the passed background samples and the
| current model output (f(x) - E[f(x)]).
|
| Examples
| --------
| See :ref:`Deep Explainer Examples <deep_explainer_examples>`
|
| Method resolution order:
| DeepExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: 'list | np.ndarray | pd.DataFrame | torch.tensor') -> 'Explanation'
| Return an explanation object for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': numpy.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| Returns
| -------
| shap.Explanation:
|
| __init__(self, model, data, session=None, learning_phase_flags=None)
| An explainer object for a differentiable model using a given background dataset.
|
| Note that the complexity of the method scales linearly with the number of background data
| samples. Passing the entire training dataset as `data` will give very accurate expected
| values, but will be unreasonably expensive. The variance of the expectation estimates scales by
| roughly 1/sqrt(N) for N background data samples. So 100 samples will give a good estimate,
| and 1000 samples a very good estimate of the expected values.
|
| Parameters
| ----------
| model :
| if framework == 'tensorflow', (input : [tf.Tensor], output : tf.Tensor)
| A pair of TensorFlow tensors (or a list and a tensor) that specifies the input and
| output of the model to be explained. Note that SHAP values are specific to a single
| output value, so the output tf.Tensor should be a single dimensional output (,1).
|
| if framework == 'pytorch', an nn.Module object (model), or a tuple (model, layer),
| where both are nn.Module objects.
| The model is an nn.Module object which takes as input a tensor (or list of tensors) of
| shape data, and returns a single dimensional output.
| If the input is a tuple, the returned shap values will be for the input of the
| layer argument. layer must be a layer in the model, i.e. model.conv2
|
| data :
| if framework == 'tensorflow': [np.array] or [pandas.DataFrame]
| if framework == 'pytorch': [torch.tensor]
|
| The background dataset to use for integrating out features. Deep integrates
| over these samples. The data passed here must match the input tensors given in the
| first argument. Note that, since these samples are integrated over for each sample, you
| should only use something like 100 or 1000 random background samples, not the whole
| training dataset.
|
| session : None or tensorflow.Session
| The TensorFlow session that has the model we are explaining. If None is passed then
| we do our best to find the right session, first looking for a keras session, then
| falling back to the default TensorFlow session.
|
| learning_phase_flags : None or list of tensors
| If you have your own custom learning phase flags, pass them here. When explaining a prediction
| we need to ensure we are not in training mode, since this changes the behavior of ops like
| batch norm or dropout. If None is passed then we look for tensors in the graph that look like
| learning phase flags (this works for Keras models). Note that we assume all the flags should
| have a value of False during predictions (and hence explanations).
|
| shap_values(self, X, ranked_outputs=None, output_rank_order='max', check_additivity=True)
| Return approximate SHAP values for the model applied to the data given by X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| ranked_outputs : None or int
| If ranked_outputs is None then we explain all the outputs in a multi-output model. If
| ranked_outputs is a positive integer then we only explain that many of the top model
| outputs (where "top" is determined by output_rank_order). Note that this causes a pair
| of values to be returned (shap_values, indexes), where shap_values is a list of numpy
| arrays for each of the output ranks, and indexes is a matrix that indicates for each sample
| which output indexes were choses as "top".
|
| output_rank_order : "max", "min", or "max_abs"
| How to order the model outputs when using ranked_outputs, either by maximum, minimum, or
| maximum absolute value.
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one input, one output: matrix of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: matrix of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs, one or more outputs: list of matrices, with shapes of one of the above.
|
| If ranked_outputs is ``None`` then this list of tensors matches
| the number of model outputs. If ranked_outputs is a positive integer a pair is returned
| (shap_values, indexes), where shap_values is a list of tensors with a length of
| ranked_outputs, and indexes is a matrix that indicates for each sample which output indexes
| were chosen as "top".
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.ExactExplainer
Python Library Documentation: class ExactExplainer in module shap.explainers._exact
class ExactExplainer(shap.explainers._explainer.Explainer)
| ExactExplainer(model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'Any' = None) -> 'None'
|
| Computes SHAP values via an optimized exact enumeration.
|
| This works well for standard Shapley value maskers for models with less than ~15 features that vary
| from the background per sample. It also works well for Owen values from hclustering structured
| maskers when there are less than ~100 features that vary from the background per sample. This
| explainer minimizes the number of function evaluations needed by ordering the masking sets to
| minimize sequential differences. This is done using gray codes for standard Shapley values
| and a greedy sorting method for hclustering structured maskers.
|
| Examples
| --------
| See `Exact explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/Exact.html>`_
|
| Method resolution order:
| ExactExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 100000, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', interactions: 'bool | int' = 1, silent: 'bool' = False) -> 'Any'
| Explains the output of model(*args), where args represents one or more parallel iterators.
|
| __init__(self, model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'Any' = None) -> 'None'
| Build an explainers.Exact object for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form `masker(mask, *fargs)`.
| It takes a single a binary mask and an input sample and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking used by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a shap.maskers.TabularPartitions(data) object.
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| linearize_link : bool
| If we use a non-linear link function to take expectations then models that are additive with respect to that
| link function for a single background sample will no longer be additive when using a background masker with
| many samples. This for example means that a linear logistic regression model would have interaction effects
| that arise from the non-linear changes in expectation averaging. To retain the additively of the model with
| still respecting the link function we linearize the link function by default.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', batch_size: "int | Literal['auto']", outputs: 'Any', interactions: 'bool | int', silent: 'bool') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_gray_code_cache': 'dict[int, npt.NDArray[np.intp]...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.Explainer
Python Library Documentation: class Explainer in module shap.explainers._explainer
class Explainer(shap._serializable.Serializable)
| Explainer(model: 'Any', masker: 'Any' = None, link: 'Callable[..., Any]' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), algorithm: "Literal['auto', 'permutation', 'partition', 'tree', 'linear', 'deep', 'exact', 'additive']" = 'auto', output_names: 'list[str] | None' = None, feature_names: 'list[str] | list[list[str]] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **kwargs: 'Any') -> 'None'
|
| Uses Shapley values to explain any machine learning model or python function.
|
| This is the primary explainer interface for the SHAP library. It takes any combination
| of a model and masker and returns a callable subclass object that implements
| the particular estimation algorithm that was chosen.
|
| Method resolution order:
| Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: 'Any', masker: 'Any' = None, link: 'Callable[..., Any]' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), algorithm: "Literal['auto', 'permutation', 'partition', 'tree', 'linear', 'deep', 'exact', 'additive']" = 'auto', output_names: 'list[str] | None' = None, feature_names: 'list[str] | list[list[str]] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **kwargs: 'Any') -> 'None'
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'feature_names': 'list[str] | list[list[str]] | Non...
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.Explanation
Python Library Documentation: class Explanation in module shap._explanation class Explanation(builtins.object) | Explanation(values: 'npt.NDArray[Any] | list[Any] | Explanation', base_values: 'npt.NDArray[Any] | list[Any] | float | None' = None, data: 'npt.NDArray[Any] | pd.DataFrame | list[Any] | None' = None, display_data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, instance_names: 'Sequence[str] | npt.NDArray[Any] | None' = None, feature_names: 'Sequence[str] | npt.NDArray[Any] | Alias | None' = None, output_names: 'Sequence[str] | npt.NDArray[Any] | str | Alias | None' = None, output_indexes: 'npt.NDArray[Any] | None' = None, lower_bounds: 'npt.NDArray[Any] | None' = None, upper_bounds: 'npt.NDArray[Any] | None' = None, error_std: 'npt.NDArray[Any] | None' = None, main_effects: 'npt.NDArray[Any] | None' = None, hierarchical_values: 'npt.NDArray[Any] | list[Any] | None' = None, clustering: 'npt.NDArray[Any] | list[Any] | None' = None, compute_time: 'float | None' = None) -> 'None' | | A sliceable set of parallel arrays representing a SHAP explanation. | | Notes | ----- | The *instance* methods such as `.max()` return new Explanation objects with the | operation applied. | | The *class* methods such as `Explanation.max` return OpChain objects that represent | a set of dot chained operations without actually running them. | | Methods defined here: | | __add__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __copy__(self) -> 'Explanation' | | __getitem__(self, item) -> 'Explanation' | This adds support for OpChain indexing. | | __init__(self, values: 'npt.NDArray[Any] | list[Any] | Explanation', base_values: 'npt.NDArray[Any] | list[Any] | float | None' = None, data: 'npt.NDArray[Any] | pd.DataFrame | list[Any] | None' = None, display_data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, instance_names: 'Sequence[str] | npt.NDArray[Any] | None' = None, feature_names: 'Sequence[str] | npt.NDArray[Any] | Alias | None' = None, output_names: 'Sequence[str] | npt.NDArray[Any] | str | Alias | None' = None, output_indexes: 'npt.NDArray[Any] | None' = None, lower_bounds: 'npt.NDArray[Any] | None' = None, upper_bounds: 'npt.NDArray[Any] | None' = None, error_std: 'npt.NDArray[Any] | None' = None, main_effects: 'npt.NDArray[Any] | None' = None, hierarchical_values: 'npt.NDArray[Any] | list[Any] | None' = None, clustering: 'npt.NDArray[Any] | list[Any] | None' = None, compute_time: 'float | None' = None) -> 'None' | Initialize self. See help(type(self)) for accurate signature. | | __len__(self) -> 'int' | | __mul__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __radd__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __repr__(self) -> 'str' | Display some basic printable info, but not everything. | | __rmul__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __rsub__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __sub__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | __truediv__(self, other: 'Explanation | npt.NDArray[Any] | float | int') -> 'Explanation' | | cohorts(self, cohorts: 'int | list[int] | tuple[int] | np.ndarray') -> 'Cohorts' | Split this explanation into several cohorts. | | Parameters | ---------- | cohorts : int or array | If this is an integer then we auto build that many cohorts using a decision tree. If this is | an array then we treat that as an array of cohort names/ids for each instance. | | Returns | ------- | Cohorts object | | hstack(self, other: 'Explanation') -> 'Explanation' | Stack two explanations column-wise. | | Parameters | ---------- | other : shap.Explanation | The other Explanation object to stack with. | | Returns | ------- | exp : shap.Explanation | A new Explanation object representing the stacked explanations. | | percentile(self, q: 'float', axis: 'int | None' = None) -> 'Explanation' | | ---------------------------------------------------------------------- | Readonly properties defined here: | | abs | | argsort | | error_std | Pass-through from the underlying slicer object. | | flip | | identity | | instance_names | Pass-through from the underlying slicer object. | | lower_bounds | Pass-through from the underlying slicer object. | | output_indexes | Pass-through from the underlying slicer object. | | shape | Compute the shape over potentially complex data nesting. | | upper_bounds | Pass-through from the underlying slicer object. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object | | base_values | Pass-through from the underlying slicer object. | | clustering | Pass-through from the underlying slicer object. | | data | Pass-through from the underlying slicer object. | | display_data | Pass-through from the underlying slicer object. | | feature_names | Pass-through from the underlying slicer object. | | hierarchical_values | Pass-through from the underlying slicer object. | | main_effects | Pass-through from the underlying slicer object. | | output_names | Pass-through from the underlying slicer object. | | values | Pass-through from the underlying slicer object. | | ---------------------------------------------------------------------- | Data and other attributes defined here: | | hclust = shap.Explanation.hclust | | max = shap.Explanation.max | | mean = shap.Explanation.mean | | min = shap.Explanation.min | | sample = shap.Explanation.sample | | sum = shap.Explanation.sum
shap.GPUTreeExplainer
Python Library Documentation: class GPUTreeExplainer in module shap.explainers._gpu_tree
class GPUTreeExplainer(shap.explainers._tree.TreeExplainer)
| GPUTreeExplainer(model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
|
| Experimental GPU accelerated version of TreeExplainer. Currently requires source build with
| cuda available and 'CUDA_PATH' environment variable defined.
|
| Examples
| --------
| See `GPUTree explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/GPUTree.html>`_
|
| Method resolution order:
| GPUTreeExplainer
| shap.explainers._tree.TreeExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| shap_interaction_values(self, X, y=None, tree_limit=None)
| Estimate the SHAP interaction values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions (not
| yet supported).
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default None means no use the limit
| of the
| original model, and -1 means no limit.
|
| Returns
| -------
| array or list
| For models with a single output this returns a tensor of SHAP values
| (# samples x # features x # features). The matrix (# features x # features) for each
| sample sums
| to the difference between the model output for that sample and the expected value of
| the model output
| (which is stored in the expected_value attribute of the explainer). Each row of this
| matrix sums to the
| SHAP value for that feature for that sample. The diagonal entries of the matrix
| represent the
| "main effect" of that feature on the prediction and the symmetric off-diagonal
| entries represent the
| interaction effects between all pairs of features for that sample. For models with
| vector outputs
| this returns a list of tensors, one for each output.
|
| shap_values(self, X, y=None, tree_limit=None, approximate=False, check_additivity=True, from_call=False)
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions.
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default None means no use the limit
| of the
| original model, and -1 means no limit.
|
| approximate : bool
| Not supported.
|
| check_additivity : bool
| Run a validation check that the sum of the SHAP values equals the output of the
| model. This
| check takes only a small amount of time, and will catch potential unforeseen errors.
| Note that this check only runs right now when explaining the margin of the model.
|
| Returns
| -------
| array or list
| For models with a single output this returns a matrix of SHAP values
| (# samples x # features). Each row sums to the difference between the model output
| for that
| sample and the expected value of the model output (which is stored in the expected_value
| attribute of the explainer when it is constant). For models with vector outputs this
| returns
| a list of such matrices, one for each output.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._tree.TreeExplainer:
|
| __call__(self, X: 'Any', y: 'np.ndarray | pd.Series | None' = None, interactions: 'bool' = False, check_additivity: 'bool' = True, approximate: 'bool' = False) -> 'Explanation'
| Calculate the SHAP values for the model applied to the data.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array, optional
| An array of label values for each sample. Used when explaining loss functions.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| interactions: bool
| Whether to compute the SHAP interaction values.
|
| check_additivity: bool
| Check if the sum of the SHAP values equals the output of the model.
|
| Returns
| -------
| shap.Explanation object containing the given data and the SHAP values.
|
| __init__(self, model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
| Build a new Tree explainer for the passed model.
|
| Parameters
| ----------
| model : model object
| The tree based machine learning model that we want to explain.
| XGBoost, LightGBM, CatBoost, Pyspark and most tree-based
| scikit-learn models are supported.
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features.
|
| This argument is optional when
| ``feature_perturbation="tree_path_dependent"``, since in that case
| we can use the number of training samples that went down each tree
| path as our background dataset (this is recorded in the ``model``
| object).
|
| feature_perturbation : "auto" (default), "interventional" or "tree_path_dependent"
| Since SHAP values rely on conditional expectations, we need to
| decide how to handle correlated (or otherwise dependent) input
| features.
|
| - if ``"interventional"``, a background dataset ``data`` is required. The
| dependencies between features are handled according to the rules dictated
| by causal inference [1]_. The runtime scales linearly with the size of the
| background dataset you use: anywhere from 100 to 1000 random background
| samples are good sizes to use.
| - if ``"tree_path_dependent"``, no background dataset is required and the
| approach is to just follow the trees and use the number of training
| examples that went down each leaf to represent the background
| distribution.
| - if ``"auto"``, the "interventional" approach will be used when a
| background is provided, otherwise the "tree_path_dependent" approach will
| be used.
|
| .. versionadded:: 0.47
| The `"auto"` option was added.
|
| .. versionchanged:: 0.47
| The default behaviour will change from `"interventional"` to `"auto"` in 0.47.
| In the future, passing `feature_pertubation="interventional"` without providing
| a background dataset will raise an error.
|
|
| model_output : "raw", "probability", "log_loss", or model method name
| What output of the model should be explained.
|
| * If "raw", then we explain the raw output of the trees, which
| varies by model. For regression models, "raw" is the standard
| output. For binary classification in XGBoost, this is the log odds
| ratio.
| * If "probability", then we explain the output of the model
| transformed into probability space (note that this means the SHAP
| values now sum to the probability output of the model).
| * If "log_loss", then we explain the natural logarithm of the model
| loss function, so that the SHAP values sum up to the log loss of
| the model for each sample. This is helpful for breaking down model
| performance by feature.
| * If ``model_output`` is the name of a supported prediction method
| on the ``model`` object, then we explain the output of that model
| method name. For example, ``model_output="predict_proba"``
| explains the result of calling ``model.predict_proba``.
|
| Currently the "probability" and "log_loss" options are only
| supported when ``feature_perturbation="interventional"``.
|
| approximate : bool
| Deprecated, will be deprecated in v0.47.0 and removed in version v0.49.0.
| Please use the ``approximate`` argument in the :meth:`.shap_values` or ``__call__`` methods instead.
|
| References
| ----------
| .. [1] Janzing, Dominik, Lenon Minorics, and Patrick Blöbaum.
| "Feature relevance quantification in explainable AI: A causal problem."
| International Conference on artificial intelligence and statistics. PMLR, 2020.
|
| assert_additivity(self, phi: 'npt.NDArray[Any] | list[npt.NDArray[Any]]', model_output: 'npt.NDArray[Any]') -> 'None'
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._tree.TreeExplainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.GradientExplainer
Python Library Documentation: class GradientExplainer in module shap.explainers._gradient
class GradientExplainer(shap.explainers._explainer.Explainer)
| GradientExplainer(model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | list[typing.Any], session: Any = None, batch_size: int = 50, local_smoothing: float = 0) -> None
|
| Explains a model using expected gradients (an extension of integrated gradients).
|
| Expected gradients an extension of the integrated gradients method (Sundararajan et al. 2017), a
| feature attribution method designed for differentiable models based on an extension of Shapley
| values to infinite player games (Aumann-Shapley values). Integrated gradients values are a bit
| different from SHAP values, and require a single reference value to integrate from. As an adaptation
| to make them approximate SHAP values, expected gradients reformulates the integral as an expectation
| and combines that expectation with sampling reference values from the background dataset. This leads
| to a single combined expectation of gradients that converges to attributions that sum to the
| difference between the expected model output and the current output.
|
| Examples
| --------
| See :ref:`Gradient Explainer Examples <gradient_explainer_examples>`
|
| Method resolution order:
| GradientExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: Any, nsamples: int = 200) -> shap._explanation.Explanation
| Return an explanation object for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
| nsamples : int
| number of background samples
|
| Returns
| -------
| shap.Explanation:
|
| __init__(self, model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | list[typing.Any], session: Any = None, batch_size: int = 50, local_smoothing: float = 0) -> None
| An explainer object for a differentiable model using a given background dataset.
|
| Parameters
| ----------
| model : tf.keras.Model, (input : [tf.Tensor], output : tf.Tensor), torch.nn.Module, or a tuple
| (model, layer), where both are torch.nn.Module objects
|
| For TensorFlow this can be a model object, or a pair of TensorFlow tensors (or a list and
| a tensor) that specifies the input and output of the model to be explained. Note that for
| TensowFlow 2 you must pass a tensorflow function, not a tuple of input/output tensors).
|
| For PyTorch this can be a nn.Module object (model), or a tuple (model, layer), where both
| are nn.Module objects. The model is an nn.Module object which takes as input a tensor
| (or list of tensors) of shape data, and returns a single dimensional output. If the input
| is a tuple, the returned shap values will be for the input of the layer argument. layer must
| be a layer in the model, i.e. model.conv2.
|
| data : [np.array] or [pandas.DataFrame] or [torch.tensor]
| The background dataset to use for integrating out features. Gradient explainer integrates
| over these samples. The data passed here must match the input tensors given in the
| first argument. Single element lists can be passed unwrapped.
|
| shap_values(self, X: Any, nsamples: int = 200, ranked_outputs: int | list[int] | None = None, output_rank_order: Literal['max', 'min', 'max_abs', 'custom'] = 'max', rseed: int | None = None, return_variances: bool = False) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | list[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]] | tuple[typing.Any, ...]
| Return the values for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| ranked_outputs : None or int
| If ranked_outputs is None then we explain all the outputs in a multi-output model. If
| ranked_outputs is a positive integer then we only explain that many of the top model
| outputs (where "top" is determined by output_rank_order). Note that this causes a pair
| of values to be returned (shap_values, indexes), where shap_values is a list of numpy arrays
| for each of the output ranks, and indexes is a matrix that tells for each sample which output
| indexes were chosen as "top".
|
| output_rank_order : "max", "min", "max_abs", or "custom"
| How to order the model outputs when using ranked_outputs, either by maximum, minimum, or
| maximum absolute value. If "custom" Then "ranked_outputs" contains a list of output nodes.
|
| rseed : None or int
| Seeding the randomness in shap value computation (background example choice,
| interpolation between current and background example, smoothing).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays with corresponding shape above.
|
| If ranked_outputs is ``None`` then this list of tensors matches the
| number of model outputs. If ranked_outputs is a positive integer a
| pair is returned ``(shap_values, indexes)``, where shap_values is a
| list of tensors with a length of ranked_outputs, and indexes is a
| matrix that tells for each sample which output indexes were chosen
| as "top".
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed
| from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'explainer': '_TFGradient | _PyTorchGradient', 'fea...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.KernelExplainer
Python Library Documentation: class KernelExplainer in module shap.explainers._kernel
class KernelExplainer(shap.explainers._explainer.Explainer)
| KernelExplainer(model: Any, data: Any, feature_names: list[str] | None = None, link: Union[Literal['identity', 'logit'], Any] = 'identity', **kwargs: Any) -> None
|
| Uses the Kernel SHAP method to explain the output of any function.
|
| Kernel SHAP is a method that uses a special weighted linear regression
| to compute the importance of each feature. The computed importance values
| are Shapley values from game theory and also coefficients from a local linear
| regression.
|
| Parameters
| ----------
| model : function or iml.Model
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array or pandas.DataFrame or shap.common.DenseData or any scipy.sparse matrix
| The background dataset to use for integrating out features. To determine the impact
| of a feature, that feature is set to "missing" and the change in the model output
| is observed. Since most models aren't designed to handle arbitrary missing data at test
| time, we simulate "missing" by replacing the feature with the values it takes in the
| background dataset. So if the background dataset is a simple sample of all zeros, then
| we would approximate a feature being missing by setting it to zero. For small problems,
| this background dataset can be the whole training set, but for larger problems consider
| using a single reference value or using the ``kmeans`` function to summarize the dataset.
| Note: for the sparse case, we accept any sparse matrix but convert to lil format for
| performance.
|
| feature_names : list
| The names of the features in the background dataset. If the background dataset is
| supplied as a pandas.DataFrame, then ``feature_names`` can be set to ``None`` (default),
| and the feature names will be taken as the column names of the dataframe.
|
| link : "identity" or "logit"
| A generalized linear model link to connect the feature importance values to the model
| output. Since the feature importance values, phi, sum up to the model output, it often makes
| sense to connect them to the output with a link function where link(output) = sum(phi).
| Default is "identity" (a no-op).
| If the model output is a probability, then "logit" can be used to transform the SHAP values
| into log-odds units.
|
| Examples
| --------
| See :ref:`Kernel Explainer Examples <kernel_explainer_examples>`.
|
| Method resolution order:
| KernelExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | scipy.sparse._matrix.spmatrix, l1_reg: str | float | bool = 'num_features(10)', silent: bool = False) -> shap._explanation.Explanation
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: Any, data: Any, feature_names: list[str] | None = None, link: Union[Literal['identity', 'logit'], Any] = 'identity', **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| addsample(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix, m: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], w: float) -> None
|
| allocate(self) -> None
|
| explain(self, incoming_instance: Any, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
|
| run(self) -> None
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | pandas.core.series.Series | scipy.sparse._matrix.spmatrix, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| nsamples : "auto" or int
| Number of times to re-evaluate the model when explaining each prediction. More samples
| lead to lower variance estimates of the SHAP values. The "auto" setting uses
| `nsamples = 2 * X.shape[1] + 2048`.
|
| l1_reg : "num_features(int)", "aic", "bic", or float
| The l1 regularization to use for feature selection. The estimation
| procedure is based on a debiased lasso.
|
| * "num_features(int)" selects a fixed number of top features.
| * "aic" and "bic" options use the AIC and BIC rules for regularization.
| * Passing a float directly sets the "alpha" parameter of the
| ``sklearn.linear_model.Lasso`` model used for feature selection.
| * "auto" (deprecated): uses "aic" when less than
| 20% of the possible sample space is enumerated, otherwise it uses
| no regularization.
|
| .. versionchanged:: 0.47.0
| The default value changed from ``"auto"`` to ``"num_features(10)"``.
|
| silent: bool
| If True, hide tqdm progress bar. Default False.
|
| gc_collect : bool
| Run garbage collection after each explanation round. Sometime needed for memory intensive explanations (default False).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as the ``expected_value``
| attribute of the explainer).
|
| The type and shape of the return value depends on the number of model inputs and outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays of corresponding shape above.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| solve(self, fraction_evaluated: float, dim: int) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
|
| varying_groups(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| not_equal(i: Any, j: Any) -> int
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'D': <class 'int'>, 'M': <class 'int'>, 'N': <class...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.LinearExplainer
Python Library Documentation: class LinearExplainer in module shap.explainers._linear
class LinearExplainer(shap.explainers._explainer.Explainer)
| LinearExplainer(model: Any, masker: Any, link: collections.abc.Callable[[typing.Any], typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), nsamples: int = 1000, feature_perturbation: Optional[Literal['interventional', 'correlation_dependent']] = None, **kwargs: Any) -> None
|
| Computes SHAP values for a linear model, optionally accounting for inter-feature correlations.
|
| This computes the SHAP values for a linear model and can account for the
| correlations among the input features. Assuming features are independent
| leads to interventional SHAP values which for a linear model are ``coef[i] *
| (x[i] - X.mean(0)[i])`` for the ith feature. If instead we account for
| correlations, then we prevent any problems arising from collinearity and
| share credit among correlated features. Accounting for correlations can be
| computationally challenging, but ``LinearExplainer`` uses sampling to
| estimate a transform that can then be applied to explain any prediction of
| the model.
|
| Parameters
| ----------
| model : (coef, intercept) or sklearn.linear_model.*
| User supplied linear model either as either a parameter pair or sklearn object.
|
| masker : function, numpy.array, pandas.DataFrame, tuple of (mean, cov), shap.maskers.Masker
| A callable Python object used to "mask" out hidden features of the form
| ``masker(binary_mask, x)``. It takes a single input sample and a binary
| mask and returns a matrix of masked samples. These masked samples are
| evaluated using the model function and the outputs are then averaged.
|
| As a shortcut for the standard masking using by SHAP you can pass a
| background data matrix instead of a function and that matrix will be
| used for masking.
|
| You can also provide a tuple of ``(mean, covariance)``, or pass in a
| masker meant for tabular data (i.e., :class:`.maskers.Independent`,
| :class:`.maskers.Impute`, or :class:`.maskers.Partition`) directly.
|
| data : (mean, cov), numpy.array, pandas.DataFrame, iml.DenseData or scipy.csr_matrix
| The background dataset to use for computing conditional expectations.
| Note that only the mean and covariance of the dataset are used. This
| means passing a raw data matrix is just a convenient alternative to
| passing the mean and covariance directly.
|
| nsamples : int
| Number of samples to use when estimating the transformation matrix used
| to account for feature correlations.
|
| feature_perturbation : None (default), "interventional" or "correlation_dependent"
|
| DEPRECATED: this option is now deprecated in favor of using the appropriate
| tabular masker and will be removed in a future release.
|
| There are two ways we might want to compute SHAP values, either the full
| conditional SHAP values or the interventional SHAP values.
|
| - For interventional SHAP values we break any dependence structure between
| features in the model and so uncover how the model would behave if we
| intervened and changed some of the inputs. This approach is used by the
| Independent and Partition maskers.
| - For the full conditional SHAP values we respect the correlations among the
| input features, so if the model depends on one input but that input is
| correlated with another input, then both get some credit for the model's
| behavior. This approach is used by the Impute masker.
|
| The interventional option stays "true to the model" meaning it will only
| give credit to features that are actually used by the model, while the
| correlation option stays "true to the data" in the sense that it only
| considers how the model would behave when respecting the correlations in
| the input data. For sparse case only interventional option is supported.
|
|
| Examples
| --------
| See `Linear explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/LinearExplainer.html>`_
|
| Method resolution order:
| LinearExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model: Any, masker: Any, link: collections.abc.Callable[[typing.Any], typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), nsamples: int = 1000, feature_perturbation: Optional[Literal['interventional', 'correlation_dependent']] = None, **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]] | pandas.core.frame.DataFrame | pandas.core.series.Series) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or scipy.csr_matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| Returns
| -------
| np.array
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored
| as the ``expected_value`` attribute of the explainer).
|
| The shape of the returned array depends on the number of model outputs:
|
| * one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * multiple outputs: array of shape ``(#num_samples, *X.shape[1:],
| #num_outputs)``.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: Any, masker: Any) -> bool
| Determines if we can parse the given model.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'M': <class 'int'>, 'avg_proj': numpy.ndarray[typin...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.NoReturn
Python Library Documentation: _SpecialForm in module typing
NoReturn = typing.NoReturn
Special type indicating functions that never return.
Example::
from typing import NoReturn
def stop() -> NoReturn:
raise Exception('no way')
NoReturn can also be used as a bottom type, a type that
has no values. Starting in Python 3.11, the Never type should
be used for this concept instead. Type checkers should treat the two
equivalently.
shap.PartitionExplainer
Python Library Documentation: class PartitionExplainer in module shap.explainers._partition
class PartitionExplainer(shap.explainers._explainer.Explainer)
| PartitionExplainer(model: Any, masker: Any, *, output_names: list[str] | None = None, link: collections.abc.Callable[..., typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: bool = True, feature_names: list[str] | None = None, **call_args: Any) -> None
|
| Uses the Partition SHAP method to explain the output of any function.
|
| Partition SHAP computes Shapley values recursively through a hierarchy of features, this
| hierarchy defines feature coalitions and results in the Owen values from game theory.
|
| The PartitionExplainer has two particularly nice properties:
|
| 1) PartitionExplainer is model-agnostic but when using a balanced partition tree only has
| quadratic exact runtime (in term of the number of input features). This is in contrast to the
| exponential exact runtime of KernelExplainer or SamplingExplainer.
| 2) PartitionExplainer always assigns to groups of correlated features the credit that set of features
| would have had if treated as a group. This means if the hierarchical clustering given to
| PartitionExplainer groups correlated features together, then feature correlations are
| "accounted for" in the sense that the total credit assigned to a group of tightly dependent features
| does not depend on how they behave if their correlation structure was broken during the explanation's
| perturbation process.
|
| Note that for linear models the Owen values that PartitionExplainer returns are the same as the standard
| non-hierarchical Shapley values.
|
| Method resolution order:
| PartitionExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: Any, max_evals: Union[int, Literal['auto']] = 500, fixed_context: Optional[Literal[0, 1]] = None, main_effects: bool = False, error_bounds: bool = False, batch_size: Union[int, Literal['auto']] = 'auto', outputs: Any = None, silent: bool = False, **kwargs: Any) -> shap._explanation.Explanation | list[shap._explanation.Explanation]
| Explain the output of the model on the given arguments.
|
| __init__(self, model: Any, masker: Any, *, output_names: list[str] | None = None, link: collections.abc.Callable[..., typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: bool = True, feature_names: list[str] | None = None, **call_args: Any) -> None
| Build a PartitionExplainer for the given model with the given masker.
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples.
|
| masker : function or numpy.array or pandas.DataFrame or tokenizer
| The function used to "mask" out hidden features of the form `masker(mask, x)`. It takes a
| single input sample and a binary mask and returns a matrix of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.maksers.Image for images and shap.maskers.Text
| for text.
|
| partition_tree : None or function or numpy.array
| A hierarchical clustering of the input features represented by a matrix that follows the format
| used by scipy.cluster.hierarchy (see the notebooks_html/partition_explainer directory an example).
| If this is a function then the function produces a clustering matrix when given a single input
| example. If you are using a standard SHAP masker object then you can pass masker.clustering
| to use that masker's built-in clustering of the features, or if partition_tree is None then
| masker.clustering will be used by default.
|
| Examples
| --------
| See `Partition explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/PartitionExplainer.html>`_
|
| __str__(self) -> str
| Return str(self).
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, batch_size: Union[int, Literal['auto']] = 'auto', fixed_context: Optional[Literal[0, 1, 'auto']] = 'auto', **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| owen(self, fm: shap.utils._masked_model.MaskedModel, f00: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], f11: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], max_evals: int, output_indexes: Any, fixed_context: Optional[Literal[0, 1]], batch_size: Union[int, Literal['auto']], silent: bool) -> tuple[typing.Any, numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
| Compute a nested set of recursive Owen values based on an ordering recursion.
|
| owen3(self, fm: shap.utils._masked_model.MaskedModel, f00: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], f11: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], max_evals: int, output_indexes: Any, fixed_context: Optional[Literal[0, 1]], batch_size: Union[int, Literal['auto']], silent: bool) -> tuple[typing.Any, numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
| Compute a nested set of recursive Owen values based on an ordering recursion.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_clustering': numpy.ndarray[typing.Any, numpy.dtyp...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.PermutationExplainer
Python Library Documentation: class PermutationExplainer in module shap.explainers._permutation
class PermutationExplainer(shap.explainers._explainer.Explainer)
| PermutationExplainer(model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **call_args: 'Any') -> 'None'
|
| This method approximates the Shapley values by iterating through permutations of the inputs.
|
| This is a model agnostic explainer that guarantees local accuracy (additivity) by iterating completely
| through an entire permutation of the features in both forward and reverse directions (antithetic sampling).
| If we do this once, then we get the exact SHAP values for models with up to second order interaction effects.
| We can iterate this many times over many random permutations to get better SHAP value estimates for models
| with higher order interactions. This sequential ordering formulation also allows for easy reuse of
| model evaluations and the ability to efficiently avoid evaluating the model when the background values
| for a feature are the same as the current input value. We can also account for hierarchical data
| structures with partition trees, something not currently implemented for KernalExplainer or SamplingExplainer.
|
| Examples
| --------
| See `Permutation explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/Permutation.html>`_
|
| Method resolution order:
| PermutationExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 500, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explain the output of the model on the given arguments.
|
| __init__(self, model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **call_args: 'Any') -> 'None'
| Build an explainers.Permutation object for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form ``masker(binary_mask, x)``.
| It takes a single input sample and a binary mask and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a ``shap.maskers.Tabular(data, clustering="correlation")`` object.
|
| seed: None or int
| Seed for reproducibility
|
| **call_args : valid argument to the __call__ method
| These arguments are saved and passed to the __call__ method as the new default values for these arguments.
|
| __str__(self) -> 'str'
| Return str(self).
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', batch_size: "int | Literal['auto']", outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| shap_values(self, X: 'Any', npermutations: 'int' = 10, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_evals: 'bool' = True, silent: 'bool' = False) -> 'Any'
| Legacy interface to estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| npermutations : int
| Number of times to cycle through all the features, re-evaluating the model at each step.
| Each cycle evaluates the model function 2 * (# features + 1) times on a data matrix of
| (# background data samples) rows. An exception to this is when PermutationExplainer can
| avoid evaluating the model because a feature's value is the same in X and the background
| dataset (which is common for example with sparse features).
|
| Returns
| -------
| array or list
| For models with a single output this returns a matrix of SHAP values
| (# samples x # features). Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as expected_value
| attribute of the explainer). For models with vector outputs this returns a list
| of such matrices, one for each output.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.SamplingExplainer
Python Library Documentation: class SamplingExplainer in module shap.explainers._sampling
class SamplingExplainer(shap.explainers._kernel.KernelExplainer)
| SamplingExplainer(model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, **kwargs: Any) -> None
|
| Computes SHAP values using an extension of the Shapley sampling values explanation method
| (also known as IME).
|
| SamplingExplainer computes SHAP values under the assumption of feature independence and is an
| extension of the algorithm proposed in "An Efficient Explanation of Individual Classifications
| using Game Theory", Erik Strumbelj, Igor Kononenko, JMLR 2010. It is a good alternative to
| KernelExplainer when you want to use a large background set (as opposed to a single reference
| value for example).
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features. To determine the impact
| of a feature, that feature is set to "missing" and the change in the model output
| is observed. Since most models aren't designed to handle arbitrary missing data at test
| time, we simulate "missing" by replacing the feature with the values it takes in the
| background dataset. So if the background dataset is a simple sample of all zeros, then
| we would approximate a feature being missing by setting it to zero. Unlike the
| KernelExplainer, this data can be the whole training set, even if that is a large set. This
| is because SamplingExplainer only samples from this background dataset.
|
| Method resolution order:
| SamplingExplainer
| shap.explainers._kernel.KernelExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, y: Any = None, nsamples: int = 2000) -> shap._explanation.Explanation
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain(self, incoming_instance: Any, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]
|
| sampling_estimate(self, j: int, f: Any, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], nsamples: int = 10) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]], numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]]
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._kernel.KernelExplainer:
|
| addsample(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix, m: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], w: float) -> None
|
| allocate(self) -> None
|
| run(self) -> None
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | pandas.core.series.Series | scipy.sparse._matrix.spmatrix, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| nsamples : "auto" or int
| Number of times to re-evaluate the model when explaining each prediction. More samples
| lead to lower variance estimates of the SHAP values. The "auto" setting uses
| `nsamples = 2 * X.shape[1] + 2048`.
|
| l1_reg : "num_features(int)", "aic", "bic", or float
| The l1 regularization to use for feature selection. The estimation
| procedure is based on a debiased lasso.
|
| * "num_features(int)" selects a fixed number of top features.
| * "aic" and "bic" options use the AIC and BIC rules for regularization.
| * Passing a float directly sets the "alpha" parameter of the
| ``sklearn.linear_model.Lasso`` model used for feature selection.
| * "auto" (deprecated): uses "aic" when less than
| 20% of the possible sample space is enumerated, otherwise it uses
| no regularization.
|
| .. versionchanged:: 0.47.0
| The default value changed from ``"auto"`` to ``"num_features(10)"``.
|
| silent: bool
| If True, hide tqdm progress bar. Default False.
|
| gc_collect : bool
| Run garbage collection after each explanation round. Sometime needed for memory intensive explanations (default False).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as the ``expected_value``
| attribute of the explainer).
|
| The type and shape of the return value depends on the number of model inputs and outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays of corresponding shape above.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| solve(self, fraction_evaluated: float, dim: int) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
|
| varying_groups(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._kernel.KernelExplainer:
|
| not_equal(i: Any, j: Any) -> int
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.TreeExplainer
Python Library Documentation: class TreeExplainer in module shap.explainers._tree
class TreeExplainer(shap.explainers._explainer.Explainer)
| TreeExplainer(model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
|
| Uses Tree SHAP algorithms to explain the output of ensemble tree models.
|
| Tree SHAP is a fast and exact method to estimate SHAP values for tree models
| and ensembles of trees, under several different possible assumptions about
| feature dependence. It depends on fast C++ implementations either inside an
| external model package or in the local compiled C extension.
|
| Examples
| --------
| See `Tree explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/Tree.html>`_
|
| Method resolution order:
| TreeExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: 'Any', y: 'np.ndarray | pd.Series | None' = None, interactions: 'bool' = False, check_additivity: 'bool' = True, approximate: 'bool' = False) -> 'Explanation'
| Calculate the SHAP values for the model applied to the data.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array, optional
| An array of label values for each sample. Used when explaining loss functions.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| interactions: bool
| Whether to compute the SHAP interaction values.
|
| check_additivity: bool
| Check if the sum of the SHAP values equals the output of the model.
|
| Returns
| -------
| shap.Explanation object containing the given data and the SHAP values.
|
| __init__(self, model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
| Build a new Tree explainer for the passed model.
|
| Parameters
| ----------
| model : model object
| The tree based machine learning model that we want to explain.
| XGBoost, LightGBM, CatBoost, Pyspark and most tree-based
| scikit-learn models are supported.
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features.
|
| This argument is optional when
| ``feature_perturbation="tree_path_dependent"``, since in that case
| we can use the number of training samples that went down each tree
| path as our background dataset (this is recorded in the ``model``
| object).
|
| feature_perturbation : "auto" (default), "interventional" or "tree_path_dependent"
| Since SHAP values rely on conditional expectations, we need to
| decide how to handle correlated (or otherwise dependent) input
| features.
|
| - if ``"interventional"``, a background dataset ``data`` is required. The
| dependencies between features are handled according to the rules dictated
| by causal inference [1]_. The runtime scales linearly with the size of the
| background dataset you use: anywhere from 100 to 1000 random background
| samples are good sizes to use.
| - if ``"tree_path_dependent"``, no background dataset is required and the
| approach is to just follow the trees and use the number of training
| examples that went down each leaf to represent the background
| distribution.
| - if ``"auto"``, the "interventional" approach will be used when a
| background is provided, otherwise the "tree_path_dependent" approach will
| be used.
|
| .. versionadded:: 0.47
| The `"auto"` option was added.
|
| .. versionchanged:: 0.47
| The default behaviour will change from `"interventional"` to `"auto"` in 0.47.
| In the future, passing `feature_pertubation="interventional"` without providing
| a background dataset will raise an error.
|
|
| model_output : "raw", "probability", "log_loss", or model method name
| What output of the model should be explained.
|
| * If "raw", then we explain the raw output of the trees, which
| varies by model. For regression models, "raw" is the standard
| output. For binary classification in XGBoost, this is the log odds
| ratio.
| * If "probability", then we explain the output of the model
| transformed into probability space (note that this means the SHAP
| values now sum to the probability output of the model).
| * If "log_loss", then we explain the natural logarithm of the model
| loss function, so that the SHAP values sum up to the log loss of
| the model for each sample. This is helpful for breaking down model
| performance by feature.
| * If ``model_output`` is the name of a supported prediction method
| on the ``model`` object, then we explain the output of that model
| method name. For example, ``model_output="predict_proba"``
| explains the result of calling ``model.predict_proba``.
|
| Currently the "probability" and "log_loss" options are only
| supported when ``feature_perturbation="interventional"``.
|
| approximate : bool
| Deprecated, will be deprecated in v0.47.0 and removed in version v0.49.0.
| Please use the ``approximate`` argument in the :meth:`.shap_values` or ``__call__`` methods instead.
|
| References
| ----------
| .. [1] Janzing, Dominik, Lenon Minorics, and Patrick Blöbaum.
| "Feature relevance quantification in explainable AI: A causal problem."
| International Conference on artificial intelligence and statistics. PMLR, 2020.
|
| assert_additivity(self, phi: 'npt.NDArray[Any] | list[npt.NDArray[Any]]', model_output: 'npt.NDArray[Any]') -> 'None'
|
| shap_interaction_values(self, X: 'npt.NDArray[Any] | pd.DataFrame | Any', y: 'npt.NDArray[Any] | pd.Series | None' = None, tree_limit: 'int | None' = None) -> 'npt.NDArray[Any]'
| Estimate the SHAP interaction values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions (not yet supported).
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default, the limit of the original model
| is used (``None``). ``-1`` means no limit.
|
| Returns
| -------
| np.array
| Returns a matrix. The shape depends on the number of model outputs:
|
| * one output: matrix of shape (#num_samples, #features, #features).
| * multiple outputs: matrix of shape (#num_samples, #features, #features, #num_outputs).
|
| The matrix (#num_samples, # features, # features) for each sample sums
| to the difference between the model output for that sample and the expected value of the model output
| (which is stored in the ``expected_value`` attribute of the explainer). Each row of this matrix sums to the
| SHAP value for that feature for that sample. The diagonal entries of the matrix represent the
| "main effect" of that feature on the prediction. The symmetric off-diagonal entries represent the
| interaction effects between all pairs of features for that sample.
| For models with vector outputs, this returns a list of tensors, one for each output.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| shap_values(self, X: 'Any', y: 'npt.NDArray[Any] | pd.Series | None' = None, tree_limit: 'int | None' = None, approximate: 'bool' = False, check_additivity: 'bool' = True, from_call: 'bool' = False) -> 'npt.NDArray[Any]'
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object, e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions.
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default, the limit of the original model
| is used (``None``). ``-1`` means no limit.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| check_additivity : bool
| Run a validation check that the sum of the SHAP values equals the output of the model. This
| check takes only a small amount of time, and will catch potential unforeseen errors.
| Note that this check only runs right now when explaining the margin of the model.
|
| Returns
| -------
| np.array
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| For each output, the sum of the SHAP values plus the ``expected_value``
| equals the model's output (in the specified output space):
|
| * Single output: ``shap_values[i, :].sum() + expected_value = f(x)[i]``
| * Multiple outputs: ``shap_values[i, :, j].sum() + expected_value[j] = f(x)[i, j]``
|
| .. note::
| The ``f(x)`` value is NOT necessarily what ``model.predict()``
| or ``model.predict_proba()`` returns. For example, for an XGBoost Classifier with the default
| ``model_output="raw"``, the explainer returns log-odds (margins).
| To compare this mathematically against ``predict_proba()`` probabilities,
| a logistic inverse-transform (e.g., ``scipy.special.expit``) must be applied
| to the sum.
|
| Furthermore, the additivity formula requires SHAP values and model
| predictions to be computed on the same samples in the same order.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * multiple outputs: array of shape ``(#num_samples, *X.shape[1:],
| #num_outputs)``.
|
| **Examples:**
|
| * **Regression:** A ``RandomForestRegressor`` returns SHAP values of shape
| ``(#num_samples, #num_features)`` with a scalar ``expected_value``.
|
| * **Binary classification:** Output behavior varies by model:
|
| - **Scikit-learn models** (e.g., ``RandomForestClassifier``) output
| probabilities for both classes, resulting in SHAP values of shape
| ``(#num_samples, #num_features, 2)`` and ``expected_value`` as an
| array of length 2.
|
| - **XGBoost and LightGBM** (with default ``model_output="raw"``) output
| a single value (raw margin/log-odds), resulting in SHAP values of shape
| ``(#num_samples, #num_features)`` and ``expected_value`` as a scalar.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'data': 'npt.NDArray[Any] | None', 'data_feature_na...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
shap.UnsupportedModule
Python Library Documentation: class UnsupportedModule in module shap class UnsupportedModule(builtins.object) | Methods defined here: | | __getattribute__(self, item: str) -> NoReturn | Return getattr(self, name). | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
shap.actions
Python Library Documentation: package shap.actions in shap
NAME
shap.actions
PACKAGE CONTENTS
_action
_optimizer
CLASSES
builtins.object
shap.actions._action.Action
class Action(builtins.object)
| Action(cost)
|
| Abstract action class.
|
| Methods defined here:
|
| __call__(self, *args)
| Call self as a function.
|
| __init__(self, cost)
| Initialize self. See help(type(self)) for accurate signature.
|
| __lt__(self, other_action)
| Return self<value.
|
| __repr__(self)
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['Action']
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\actions\__init__.py
shap.approximate_interactions
Python Library Documentation: function approximate_interactions in module shap.utils._general
approximate_interactions(index: 'str | int', shap_values: 'npt.NDArray[Any]', X: 'npt.NDArray[Any] | pd.DataFrame', feature_names: 'list[str] | npt.NDArray[Any] | pd.Index | None' = None) -> 'npt.NDArray[Any]'
Order other features by how much interaction they seem to have with the feature at the given index.
This just bins the SHAP values for a feature along that feature's value. For true Shapley interaction
index values for SHAP see the interaction_contribs option implemented in XGBoost.
shap.bar_plot
Python Library Documentation: function bar_legacy in module shap.plots._bar bar_legacy(shap_values, features=None, feature_names=None, max_display=None, show=True)
shap.datasets
Python Library Documentation: module shap.datasets in shap
NAME
shap.datasets
FUNCTIONS
a1a(n_points: 'int | None' = None) -> 'tuple[ssp.csr_matrix, np.ndarray]'
Return a sparse dataset in scipy csr matrix format.
Data Source: :external+scikit-learn:func:`sklearn.datasets.load_svmlight_file`
Parameters
----------
n_points : int, optional
Number of data points to sample. If None, returns the entire dataset. Default is None.
Returns
-------
X : scipy.sparse.csr_matrix
Sparse feature matrix.
y : np.ndarray
Target labels.
Examples
--------
.. code-block:: python
data, target = shap.datasets.a1a()
adult(display: 'bool' = False, n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray]'
Return the Adult census data in a structured format.
Used in binary classification tasks.
Parameters
----------
display : bool, optional
If True, return the raw data without target and redundant columns.
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : pd.DataFrame
If ``display`` is True, ``X`` contains the raw data without the 'Education', 'Target', and 'fnlwgt' columns.
Otherwise, ``X`` contains the processed data without the 'Target' and 'fnlwgt' columns.
y : np.ndarray
The 'Target' column returned as an array.
Notes
-----
- The original data includes the following columns:
- ``Age`` (float) : Age in years.
- ``Workclass`` (category) : Type of employment.
- ``fnlwgt`` (float) : Final weight; the number of units in the target population that the record represents.
- ``Education`` (category) : Highest level of education achieved.
- ``Education-Num`` (float) : Numeric representation of education level.
- ``Marital Status`` (category) : Marital status of the individual.
- ``Occupation`` (category) : Type of occupation.
- ``Relationship`` (category) : Relationship status.
- ``Race`` (category) : Ethnicity of the individual.
- ``Sex`` (category) : Gender of the individual.
- ``Capital Gain`` (float) : Capital gains recorded.
- ``Capital Loss`` (float) : Capital losses recorded.
- ``Hours per week`` (float) : Number of hours worked per week.
- ``Country`` (category) : Country of origin.
- ``Target`` (category) : Binary target variable indicating whether the individual earns more than 50K.
- The Education' column is redundant with 'Education-Num' and is dropped for simplicity.
- The 'Target' column is converted to binary (True/False) where '>50K' is True and '<=50K' is False.
- Certain categorical columns are encoded for numerical representation.
Examples
--------
To get the processed data and target labels::
data, target = shap.datasets.adult()
To get the raw data for display::
raw_data, target = shap.datasets.adult(display=True)
cache(url: 'str', file_name: 'str | None' = None) -> 'str'
Loads a file from the URL and caches it locally.
california(n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray]'
Return the California housing data in a tabular format.
Used in predictive regression tasks.
Parameters
----------
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : pd.DataFrame
The feature data.
y : np.ndarray
The target variable.
Notes
-----
The returned feature matrix ``X`` includes the following features:
- ``MedInc`` (float): Median income in block
- ``HouseAge`` (float): Median house age in block
- ``AveRooms`` (float): Average rooms in dwelling
- ``AveBedrms`` (float): Average bedrooms in dwelling
- ``Population`` (float): Block population
- ``AveOccup`` (float): Average house occupancy
- ``Latitude`` (float): House block latitude
- ``Longitude`` (float): House block longitude
The target column represents the median house value for California districts.
References
----------
California housing dataset: :external+scikit-learn:func:`sklearn.datasets.fetch_california_housing`
Examples
--------
To get the processed data and target labels::
data, target = shap.datasets.california()
communitiesandcrime(n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray]'
Predict the total number of violent crimes per 100K population.
This dataset is from the classic UCI Machine Learning repository:
https://archive.ics.uci.edu/ml/datasets/Communities+and+Crime+Unnormalized
Used in predictive regression tasks.
Parameters
----------
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : pd.DataFrame
The feature data.
y : np.ndarray
The target variable.
Examples
--------
To get the processed data and target labels::
data, target = shap.datasets.communitiesandcrime()
corrgroups60(n_points: 'int' = 1000) -> 'tuple[pd.DataFrame, np.ndarray]'
Correlated Groups (60 features)
A synthetic dataset consisting of 60 features with tight correlations among distinct groups of features.
Parameters
----------
n_points : int, optional
Number of data points to generate. Default is 1,000.
Returns
-------
X : pd.DataFrame
The feature data matrix
y : np.ndarray
The target variables
Notes
-----
- The dataset is generated with known correlations among distinct groups of features.
- Each feature is a unit variance Gaussian random variable centred around 0.
- The labels are generated based on a linear function of the features with added random noise.
Examples
--------
.. code-block:: python
data, target = shap.datasets.corrgroups60()
diabetes(n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray]'
Return the diabetes data in a nice package.
Used in predictive regression tasks.
Parameters
----------
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : pd.DataFrame
The feature data.
y : np.ndarray
The target variable.
Notes
-----
Feature Columns in ``X``:
- ``age`` (float): Age in years
- ``sex`` (float): Sex
- ``bmi`` (float): Body mass index
- ``bp`` (float): Average blood pressure
- ``s1`` (float): Total serum cholesterol
- ``s2`` (float): Low-density lipoproteins (LDL cholesterol)
- ``s3`` (float): High-density lipoproteins (HDL cholesterol)
- ``s4`` (float): Total cholesterol / HDL cholesterol ratio
- ``s5`` (float): Log of serum triglycerides level
- ``s6`` (float): Blood sugar level
Target ``y``:
- Progression of diabetes one year after baseline (float)
The diabetes dataset is a subset of the larger diabetes dataset from scikit-learn.
More details: :external+scikit-learn:func:`sklearn.datasets.load_diabetes`
Examples
--------
To get the processed data and target labels::
data, target = shap.datasets.diabetes()
imagenet50(resolution: 'int' = 224, n_points: 'int | None' = None) -> 'tuple[np.ndarray, np.ndarray]'
Return a set of 50 images representative of ImageNet images.
Parameters
----------
resolution : int
The resolution of the images. At present, the only supported value is 224.
n_points : int, optional
Number of data points to sample. If None, the entire dataset is used.
Returns
-------
X : np.ndarray
Represents images from ImageNet of a certain resolution.
y : np.ndarray
The target variables, that is, the ImageNet classes.
Notes
-----
This dataset was collected by randomly finding a working ImageNet link and then pasting the
original ImageNet image into Google image search restricted to images licensed for reuse. A
similar image (now with rights to reuse) was downloaded as a rough replacement for the original
ImageNet image. The point is to have a random sample of ImageNet for use as a background
distribution for explaining models trained on ImageNet data.
Note that because the images are only rough replacements, the labels might no longer be correct.
Examples
--------
To get the processed images and labels::
images, labels = shap.datasets.imagenet50()
imdb(n_points: 'int | None' = None) -> 'tuple[list[str], np.ndarray]'
Return the classic IMDB sentiment analysis training data in a nice package.
Used in binary text classification tasks.
Parameters
----------
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : list of strings
Text data, where each string is a movie review.
y : np.ndarray
The target variable. Contains booleans, where True indicates a positive sentiment and False
indicates a negative sentiment.
Notes
-----
Full data is at: http://ai.stanford.edu/~amaas/data/sentiment/aclImdb_v1.tar.gz
Paper to cite when using the data is: http://www.aclweb.org/anthology/P11-1015
Examples
--------
To get the processed text data and labels::
text_data, labels = shap.datasets.imdb()
independentlinear60(n_points: 'int' = 1000) -> 'tuple[pd.DataFrame, np.ndarray]'
Independent Linear (60 features)
A synthetic dataset consisting of 60 features.
Parameters
----------
n_points : int, optional
Number of data points to generate. Default is 1,000.
Returns
-------
X : pd.DataFrame
The feature data matrix
y : np.ndarray
The target variables
Notes
-----
- Each feature is a unit variance Gaussian random variable centred around 0.
- The labels are generated based on a linear function of the features with added random noise.
Examples
--------
.. code-block:: python
features, labels = shap.datasets.independentlinear60()
iris(display: 'bool' = False, n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray | list[str]]'
Return the classic Iris dataset in a convenient package.
Parameters
----------
display : bool
If True, return the original feature matrix along with class labels (as strings). Default is False.
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number of points.
Returns
-------
X : pd.DataFrame
The feature matrix.
y : np.ndarray or a list of strings
If ``display`` is False, a numpy array representing the class labels encoded as integers is returned.
If ``display`` is True, then a list of class labels is returned.
Notes
-----
- The dataset includes measurements of sepal length, sepal width, petal length, and petal width for three
species of iris flowers.
- Class labels are encoded as integers (0, 1, 2) representing the species (setosa, versicolor, virginica).
- If ``display`` is True, class labels are returned as strings.
Examples
--------
To get the feature matrix and class labels::
features, labels = shap.datasets.iris()
To get the feature matrix and class labels as strings::
features, class_labels = shap.datasets.iris(display=True)
linnerud(n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, pd.DataFrame]'
Return the Linnerud dataset in a convenient package for multi-target regression.
Parameters
----------
n_points : int, optional
Number of data points to sample. If provided, randomly samples the specified number
of points.
Returns
-------
X : pd.DataFrame
The feature data.
y : pd.DataFrame
The multiclass target variables.
Notes
-----
- The Linnerud dataset contains physiological and exercise data for 20 individuals.
- The feature matrix ``X`` includes three exercise variables: ``Chins``, ``Situps``, ``Jumps``.
- The target variables ``y`` include three physiological measurements: ``Weight``, ``Waist``, ``Pulse``.
More details: :external+scikit-learn:func:`sklearn.datasets.load_linnerud`
Examples
--------
To get the feature matrix and target variables::
features, targets = shap.datasets.linnerud()
To get a subset of the data::
subset_features, subset_targets = shap.datasets.linnerud(n_points=100)
nhanesi(display: 'bool' = False, n_points: 'int | None' = None) -> 'tuple[pd.DataFrame, np.ndarray]'
Return a nicely packaged version of NHANES I data with survival times as labels.
Used in survival analysis tasks.
Parameters
----------
display : bool, optional
If True, returns the features with a modified display. Default is False.
n_points : int, optional
Number of data points to sample. Default is None (returns the entire dataset).
Returns
-------
X : pd.DataFrame
The feature data matrix. If ``display`` is True, a modified version of the features for display
is returned as ``X`` instead.
y : np.ndarray
The target variables representing survival times.
Examples
--------
Usage example::
features, survival_times = shap.datasets.nhanesi(display=True, n_points=100)
rank() -> 'tuple[ssp.csr_matrix, np.ndarray, ssp.csr_matrix, np.ndarray, np.ndarray, np.ndarray]'
Return ranking datasets from the LightGBM repository.
Used in ranking tasks.
Returns
-------
x_train : scipy.sparse.csr_matrix
Training feature matrix.
y_train : numpy.ndarray
Training labels.
x_test : scipy.sparse.csr_matrix
Testing feature matrix.
y_test : numpy.ndarray
Testing labels.
q_train : numpy.ndarray
Training query information.
q_test : numpy.ndarray
Testing query information.
Notes
-----
Data Source: LightGBM repository https://github.com/lightgbm-org/LightGBM/tree/master/examples/lambdarank
Examples
--------
.. code-block:: python
x_train, y_train, x_test, y_test, q_train, q_test = shap.datasets.rank()
DATA
Final = typing.Final
Special typing construct to indicate final names to type checkers.
A final name cannot be re-assigned or overridden in a subclass.
For example::
MAX_SIZE: Final = 9000
MAX_SIZE += 1 # Error reported by type checker
class Connection:
TIMEOUT: Final[int] = 10
class FastConnector(Connection):
TIMEOUT = 1 # Error reported by type checker
There is no runtime checking of these properties.
Literal = typing.Literal
Special typing form to define literal types (a.k.a. value types).
This form can be used to indicate to type checkers that the corresponding
variable or function parameter has a value equivalent to the provided
literal (or one of several literals)::
def validate_simple(data: Any) -> Literal[True]: # always returns True
...
MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
...
open_helper('/some/path', 'r') # Passes type check
open_helper('/other/path', 'typo') # Error in type checker
Literal[...] cannot be subclassed. At runtime, an arbitrary value
is allowed as type argument to Literal[...], but type checkers may
impose restrictions.
TYPE_CHECKING = False
__annotations__ = {'github_data_url': 'Final[str]'}
github_data_url = 'https://github.com/shap/shap/raw/master/data/'
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\datasets.py
shap.decision_plot
Python Library Documentation: function decision in module shap.plots._decision
decision(base_value: 'float | np.ndarray', shap_values: 'np.ndarray', features: 'np.ndarray | pd.Series | pd.DataFrame | list | None' = None, feature_names=None, feature_order='importance', feature_display_range=None, highlight=None, link='identity', plot_color=None, axis_color='#333333', y_demarc_color='#333333', alpha=None, color_bar=True, auto_size_plot=True, title=None, xlim=None, show=True, return_objects=False, ignore_warnings=False, new_base_value=None, legend_labels=None, legend_location='best') -> 'DecisionPlotResult | None'
Visualize model decisions using cumulative SHAP values.
Each plotted line explains a single model prediction. If a single prediction is plotted, feature values will be
printed in the plot (if supplied). If multiple predictions are plotted together, feature values will not be printed.
Plotting too many predictions together will make the plot unintelligible.
Parameters
----------
base_value : float or numpy.ndarray
This is the reference value that the feature contributions start from. Usually, this is
``explainer.expected_value``.
shap_values : numpy.ndarray
Matrix of SHAP values (# features) or (# samples x # features) from
``explainer.shap_values()``. Or cube of SHAP interaction values (# samples x
# features x # features) from ``explainer.shap_interaction_values()``.
features : numpy.array or pandas.Series or pandas.DataFrame or numpy.ndarray or list
Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
features and, optionally, the feature names.
feature_names : list or numpy.ndarray
List of feature names (# features). If ``None``, names may be derived from the
``features`` argument if a Pandas object is provided. Otherwise, numeric feature
names will be generated.
feature_order : str or None or list or numpy.ndarray
Any of "importance" (the default), "hclust" (hierarchical clustering), ``None``,
or a list/array of indices.
feature_display_range: slice or range
The slice or range of features to plot after ordering features by ``feature_order``. A step of 1 or ``None``
will display the features in ascending order. A step of -1 will display the features in descending order. If
``feature_display_range=None``, ``slice(-1, -21, -1)`` is used (i.e. show the last 20 features in descending order).
If ``shap_values`` contains interaction values, the number of features is automatically expanded to include all
possible interactions: N(N + 1)/2 where N = ``shap_values.shape[1]``.
highlight : Any
Specify which observations to draw in a different line style. All numpy indexing methods are supported. For
example, list of integer indices, or a bool array.
link : str
Use "identity" or "logit" to specify the transformation used for the x-axis. The "logit" link transforms
log-odds into probabilities.
plot_color : str or matplotlib.colors.ColorMap
Color spectrum used to draw the plot lines. If ``str``, a registered matplotlib color name is assumed.
axis_color : str or int
Color used to draw plot axes.
y_demarc_color : str or int
Color used to draw feature demarcation lines on the y-axis.
alpha : float
Alpha blending value in [0, 1] used to draw plot lines.
color_bar : bool
Whether to draw the color bar (legend).
auto_size_plot : bool
Whether to automatically size the matplotlib plot to fit the number of features
displayed. If ``False``, specify the plot size using matplotlib before calling
this function.
title : str
Title of the plot.
xlim: tuple[float, float]
The extents of the x-axis (e.g. ``(-1.0, 1.0)``). If not specified, the limits
are determined by the maximum/minimum predictions centered around base_value
when ``link="identity"``. When ``link="logit"``, the x-axis extents are ``(0,
1)`` centered at 0.5. ``xlim`` values are not transformed by the ``link``
function. This argument is provided to simplify producing multiple plots on the
same scale for comparison.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
return_objects : bool
Whether to return a :obj:`DecisionPlotResult` object containing various plotting
features. This can be used to generate multiple decision plots using the same
feature ordering and scale.
ignore_warnings : bool
Plotting many data points or too many features at a time may be slow, or may create very large plots. Set
this argument to ``True`` to override hard-coded limits that prevent plotting large amounts of data.
new_base_value : float
SHAP values are relative to a base value. By default, this base value is the
expected value of the model's raw predictions. Use ``new_base_value`` to shift
the base value to an arbitrary value (e.g. the cutoff point for a binary
classification task).
legend_labels : list of str
List of legend labels. If ``None``, legend will not be shown.
legend_location : str
Legend location. Any of "best", "upper right", "upper left", "lower left", "lower right", "right",
"center left", "center right", "lower center", "upper center", "center".
Returns
-------
DecisionPlotResult or None
Returns a :obj:`DecisionPlotResult` object if ``return_objects=True``. Returns ``None`` otherwise (the default).
Examples
--------
Plot two decision plots using the same feature order and x-axis.
>>> range1, range2 = range(20), range(20, 40)
>>> r = decision_plot(base, shap_values[range1], features[range1], return_objects=True)
>>> decision_plot(base, shap_values[range2], features[range2], feature_order=r.feature_idx, xlim=r.xlim)
See more `decision plot examples here <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/decision_plot.html>`_.
shap.dependence_plot
Python Library Documentation: function dependence_legacy in module shap.plots._scatter
dependence_legacy(ind, shap_values=None, features=None, feature_names=None, display_features=None, interaction_index='auto', color='#1E88E5', axis_color='#333333', cmap=None, dot_size=16, x_jitter=0, alpha=1, title=None, xmin=None, xmax=None, ax=None, show=True, ymin=None, ymax=None)
Create a SHAP dependence plot, colored by an interaction feature.
Plots the value of the feature on the x-axis and the SHAP value of the same feature
on the y-axis. This shows how the model depends on the given feature, and is like a
richer extension of the classical partial dependence plots. Vertical dispersion of the
data points represents interaction effects. Grey ticks along the y-axis are data
points where the feature's value was NaN.
Parameters
----------
ind : int or string
If this is an int it is the index of the feature to plot. If this is a string it is
either the name of the feature to plot, or it can have the form "rank(int)" to specify
the feature with that rank (ordered by mean absolute SHAP value over all the samples).
shap_values : numpy.array
Matrix of SHAP values (# samples x # features).
features : numpy.array or pandas.DataFrame
Matrix of feature values (# samples x # features).
feature_names : list
Names of the features (length # features).
display_features : numpy.array or pandas.DataFrame
Matrix of feature values for visual display (such as strings instead of coded values).
interaction_index : "auto", None, int, or string
The index of the feature used to color the plot. The name of a feature can also be passed
as a string. If "auto" then shap.common.approximate_interactions is used to pick what
seems to be the strongest interaction (note that to find to true strongest interaction you
need to compute the SHAP interaction values).
x_jitter : float (0 - 1)
Adds random jitter to feature values. May increase plot readability when feature
is discrete.
alpha : float
The transparency of the data points (between 0 and 1). This can be useful to the
show density of the data points when using a large dataset.
xmin : float or string
Represents the lower bound of the plot's x-axis. It can be a string of the format
"percentile(float)" to denote that percentile of the feature's value used on the x-axis.
xmax : float or string
Represents the upper bound of the plot's x-axis. It can be a string of the format
"percentile(float)" to denote that percentile of the feature's value used on the x-axis.
ax : matplotlib Axes object
Optionally specify an existing matplotlib Axes object, into which the plot will be placed.
In this case we do not create a Figure, otherwise we do.
ymin : float
Represents the lower bound of the plot's y-axis.
ymax : float
Represents the upper bound of the plot's y-axis.
shap.embedding_plot
Python Library Documentation: function embedding in module shap.plots._embedding
embedding(ind, shap_values, feature_names=None, method='pca', alpha=1.0, show=True)
Use the SHAP values as an embedding which we project to 2D for visualization.
Parameters
----------
ind : int or string
If this is an int it is the index of the feature to use to color the embedding.
If this is a string it is either the name of the feature, or it can have the
form "rank(int)" to specify the feature with that rank (ordered by mean absolute
SHAP value over all the samples), or "sum()" to mean the sum of all the SHAP values,
which is the model's output (minus its expected value).
shap_values : numpy.array
Matrix of SHAP values (# samples x # features).
feature_names : None or list
The names of the features in the shap_values array.
method : "pca" or numpy.array
How to reduce the dimensions of the shap_values to 2D. If "pca" then the 2D
PCA projection of shap_values is used. If a numpy array then is should be
(# samples x 2) and represent the embedding of that values.
alpha : float
The transparency of the data points (between 0 and 1). This can be useful to
show the density of the data points when using a large dataset.
shap.explainers
Python Library Documentation: package shap.explainers in shap
NAME
shap.explainers
PACKAGE CONTENTS
_additive
_coalition
_deep (package)
_exact
_explainer
_gpu_tree
_gradient
_kernel
_linear
_partition
_permutation
_sampling
_tree
other (package)
pytree
tf_utils
CLASSES
shap.explainers._explainer.Explainer(shap._serializable.Serializable)
shap.explainers._additive.AdditiveExplainer
shap.explainers._coalition.CoalitionExplainer
shap.explainers._deep.DeepExplainer
shap.explainers._exact.ExactExplainer
shap.explainers._gradient.GradientExplainer
shap.explainers._kernel.KernelExplainer
shap.explainers._sampling.SamplingExplainer
shap.explainers._linear.LinearExplainer
shap.explainers._partition.PartitionExplainer
shap.explainers._permutation.PermutationExplainer
shap.explainers._tree.TreeExplainer
shap.explainers._gpu_tree.GPUTreeExplainer
class AdditiveExplainer(shap.explainers._explainer.Explainer)
| AdditiveExplainer(model: Any, masker: Any, link: Any = None, feature_names: list[str] | None = None, linearize_link: bool = True) -> None
|
| Computes SHAP values for generalized additive models.
|
| This assumes that the model only has first-order effects. Extending this to
| second- and third-order effects is future work (if you apply this to those models right now
| you will get incorrect answers that fail additivity).
|
| Method resolution order:
| AdditiveExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: Any, max_evals: Union[int, Literal['auto']] = 'auto', main_effects: bool = False, error_bounds: bool = False, batch_size: Union[int, Literal['auto']] = 'auto', outputs: Any = None, silent: bool = False, **kwargs: Any) -> Any
| Explains the output of model(*args), where args represents one or more parallel iterable args.
|
| __init__(self, model: Any, masker: Any, link: Any = None, feature_names: list[str] | None = None, linearize_link: bool = True) -> None
| Build an Additive explainer for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form ``masker(mask, *fargs)``.
| It takes a single a binary mask and an input sample and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking used by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a ``shap.maskers.Tabular(data, hclustering="correlation")`` object, but
| note that this structure information has no effect on the explanations of additive models.
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: Any, masker: Any) -> bool
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_expected_value': float | numpy.ndarray[typing.Any...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class CoalitionExplainer(shap.explainers._explainer.Explainer)
| CoalitionExplainer(model: 'Any', masker: 'Any', *, output_names: 'list[str] | None' = None, link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'list[str] | None' = None, partition_tree: 'dict[str, Any] | None' = None) -> 'None'
|
| A coalition-based explainer that uses Winter values, also called recursive Owen values, to explain model predictions.
|
| This explainer implements a coalition-based approach to compute feature attributions
| using Winter values, which extend Shapley values to handle hierarchical feature groupings.
| Essentially the attributions are computed using the marginals respecting the partition tree, reducing the complexity of computation.
|
| It is particularly useful when features can be grouped into coalitions or
| hierarchies, in the case of temporal, multimodal data (e.g., demographic features, financial features, etc.).
| Textual and image data is not yet implemented.
|
| The explainer supports both single and multi-output models, and can handle various
| types of input data through the provided masker.
|
| Example usage
| --------
| >>> import shap
| >>> import numpy as np
| >>> import pandas as pd
| >>> from sklearn.ensemble import RandomForestClassifier
| >>> from sklearn.datasets import load_iris
| >>>
| >>> # Load data and train model
| >>> X, y = load_iris(return_X_y=True)
| >>> model = RandomForestClassifier().fit(X, y)
| >>>
| >>> # Define feature groups
| >>> coalition_tree = {
| ... "Sepal": ["sepal length (cm)", "sepal width (cm)"],
| ... "Petal": ["petal length (cm)", "petal width (cm)"]
| ... }
| >>> # Define feature names, or you can pass X as a DataFrame
| >>> feature_names = ["sepal length (cm)", "sepal width (cm)",
| "petal length (cm)", "petal width (cm)"]
| >>> masker = shap.maskers.Partition(X)
| >>> masker.feature_names = feature_names
| >>>
| >>> # Create explainer
| >>> explainer = shap.CoalitionExplainer(
| ... model.predict,
| ... masker,
| ... partition_tree=coalition_tree
| ... )
| >>>
| >>> # Compute SHAP values
| >>> shap_values = explainer(X[:5]
|
| Method resolution order:
| CoalitionExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: 'int' = 500, fixed_context: 'int | None' = None, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: 'int | str' = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Any'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: 'Any', masker: 'Any', *, output_names: 'list[str] | None' = None, link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'list[str] | None' = None, partition_tree: 'dict[str, Any] | None' = None) -> 'None'
| Initialize the coalition explainer with a model and masker.
|
| Parameters
| ----------
| model : callable or shap.models.Model
| A callable that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # outputs).
|
| masker : shap.maskers.Masker
| A masker object that defines how to mask features and compute background
| values. This should be compatible with the input data format.
|
| output_names : list of str, optional
| Names for each of the model outputs. If None, the output names will be
| determined from the model if possible.
|
| link : callable, optional
| The link function used to map between the output units of the model and the
| SHAP value units. By default, the identity function is used.
|
| linearize_link : bool, optional
| If True, the link function is linearized around the expected value to
| improve the accuracy of the SHAP values. Default is True.
|
| feature_names : list of str, required
| Names for each of the input features. If None, feature names will be
| determined from the masker if possible.
|
| partition_tree : dict, required
| A dictionary defining a custom hierarchical grouping of features. This is for users who want to
| define partitions based on domain knowledge. For automatic binary clustering, please use the
| `PartitionExplainer`. Each key represents a group name, and its value is either a list of
| feature names or another dictionary defining subgroups. Note all input features must be included
| in the leaf nodes.
| For example:
| {
| "Demographics": ["Age", "Gender", "Education"],
| "Financial": {
| "Income": ["Salary", "Bonus"],
| "Assets": ["Savings", "Investments"]
| }
| }
|
| Notes
| -----
| - The explainer supports both single and multi-output models.
| - The partition_tree parameter is used to define feature coalitions for
| computing Owen values, which can provide more meaningful explanations
| when features are naturally grouped.
| - The masker should be compatible with the input data format and provide
| appropriate background values for computing SHAP values.
|
| __str__(self) -> 'str'
| Return str(self).
|
| explain_row(self, *row_args: 'Any', max_evals: 'int' = 100, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: 'int | str' = 'auto', outputs: 'Any' = None, silent: 'bool' = False, fixed_context: 'int | str | None' = 'auto') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_clustering': 'Any', '_curr_base_value': 'npt.NDAr...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class DeepExplainer(shap.explainers._explainer.Explainer)
| DeepExplainer(model, data, session=None, learning_phase_flags=None)
|
| Meant to approximate SHAP values for deep learning models.
|
| This is an enhanced version of the DeepLIFT algorithm (Deep SHAP) where, similar to Kernel SHAP, we
| approximate the conditional expectations of SHAP values using a selection of background samples.
| Lundberg and Lee, NIPS 2017 showed that the per node attribution rules in DeepLIFT (Shrikumar,
| Greenside, and Kundaje, arXiv 2017) can be chosen to approximate Shapley values. By integrating
| over many background samples, Deep estimates approximate SHAP values such that they sum
| up to the difference between the expected model output on the passed background samples and the
| current model output (f(x) - E[f(x)]).
|
| Examples
| --------
| See :ref:`Deep Explainer Examples <deep_explainer_examples>`
|
| Method resolution order:
| DeepExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: 'list | np.ndarray | pd.DataFrame | torch.tensor') -> 'Explanation'
| Return an explanation object for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': numpy.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| Returns
| -------
| shap.Explanation:
|
| __init__(self, model, data, session=None, learning_phase_flags=None)
| An explainer object for a differentiable model using a given background dataset.
|
| Note that the complexity of the method scales linearly with the number of background data
| samples. Passing the entire training dataset as `data` will give very accurate expected
| values, but will be unreasonably expensive. The variance of the expectation estimates scales by
| roughly 1/sqrt(N) for N background data samples. So 100 samples will give a good estimate,
| and 1000 samples a very good estimate of the expected values.
|
| Parameters
| ----------
| model :
| if framework == 'tensorflow', (input : [tf.Tensor], output : tf.Tensor)
| A pair of TensorFlow tensors (or a list and a tensor) that specifies the input and
| output of the model to be explained. Note that SHAP values are specific to a single
| output value, so the output tf.Tensor should be a single dimensional output (,1).
|
| if framework == 'pytorch', an nn.Module object (model), or a tuple (model, layer),
| where both are nn.Module objects.
| The model is an nn.Module object which takes as input a tensor (or list of tensors) of
| shape data, and returns a single dimensional output.
| If the input is a tuple, the returned shap values will be for the input of the
| layer argument. layer must be a layer in the model, i.e. model.conv2
|
| data :
| if framework == 'tensorflow': [np.array] or [pandas.DataFrame]
| if framework == 'pytorch': [torch.tensor]
|
| The background dataset to use for integrating out features. Deep integrates
| over these samples. The data passed here must match the input tensors given in the
| first argument. Note that, since these samples are integrated over for each sample, you
| should only use something like 100 or 1000 random background samples, not the whole
| training dataset.
|
| session : None or tensorflow.Session
| The TensorFlow session that has the model we are explaining. If None is passed then
| we do our best to find the right session, first looking for a keras session, then
| falling back to the default TensorFlow session.
|
| learning_phase_flags : None or list of tensors
| If you have your own custom learning phase flags, pass them here. When explaining a prediction
| we need to ensure we are not in training mode, since this changes the behavior of ops like
| batch norm or dropout. If None is passed then we look for tensors in the graph that look like
| learning phase flags (this works for Keras models). Note that we assume all the flags should
| have a value of False during predictions (and hence explanations).
|
| shap_values(self, X, ranked_outputs=None, output_rank_order='max', check_additivity=True)
| Return approximate SHAP values for the model applied to the data given by X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| ranked_outputs : None or int
| If ranked_outputs is None then we explain all the outputs in a multi-output model. If
| ranked_outputs is a positive integer then we only explain that many of the top model
| outputs (where "top" is determined by output_rank_order). Note that this causes a pair
| of values to be returned (shap_values, indexes), where shap_values is a list of numpy
| arrays for each of the output ranks, and indexes is a matrix that indicates for each sample
| which output indexes were choses as "top".
|
| output_rank_order : "max", "min", or "max_abs"
| How to order the model outputs when using ranked_outputs, either by maximum, minimum, or
| maximum absolute value.
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one input, one output: matrix of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: matrix of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs, one or more outputs: list of matrices, with shapes of one of the above.
|
| If ranked_outputs is ``None`` then this list of tensors matches
| the number of model outputs. If ranked_outputs is a positive integer a pair is returned
| (shap_values, indexes), where shap_values is a list of tensors with a length of
| ranked_outputs, and indexes is a matrix that indicates for each sample which output indexes
| were chosen as "top".
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class ExactExplainer(shap.explainers._explainer.Explainer)
| ExactExplainer(model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'Any' = None) -> 'None'
|
| Computes SHAP values via an optimized exact enumeration.
|
| This works well for standard Shapley value maskers for models with less than ~15 features that vary
| from the background per sample. It also works well for Owen values from hclustering structured
| maskers when there are less than ~100 features that vary from the background per sample. This
| explainer minimizes the number of function evaluations needed by ordering the masking sets to
| minimize sequential differences. This is done using gray codes for standard Shapley values
| and a greedy sorting method for hclustering structured maskers.
|
| Examples
| --------
| See `Exact explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/Exact.html>`_
|
| Method resolution order:
| ExactExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 100000, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', interactions: 'bool | int' = 1, silent: 'bool' = False) -> 'Any'
| Explains the output of model(*args), where args represents one or more parallel iterators.
|
| __init__(self, model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: 'bool' = True, feature_names: 'Any' = None) -> 'None'
| Build an explainers.Exact object for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form `masker(mask, *fargs)`.
| It takes a single a binary mask and an input sample and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking used by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a shap.maskers.TabularPartitions(data) object.
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| linearize_link : bool
| If we use a non-linear link function to take expectations then models that are additive with respect to that
| link function for a single background sample will no longer be additive when using a background masker with
| many samples. This for example means that a linear logistic regression model would have interaction effects
| that arise from the non-linear changes in expectation averaging. To retain the additively of the model with
| still respecting the link function we linearize the link function by default.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', batch_size: "int | Literal['auto']", outputs: 'Any', interactions: 'bool | int', silent: 'bool') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_gray_code_cache': 'dict[int, npt.NDArray[np.intp]...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class GPUTreeExplainer(shap.explainers._tree.TreeExplainer)
| GPUTreeExplainer(model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
|
| Experimental GPU accelerated version of TreeExplainer. Currently requires source build with
| cuda available and 'CUDA_PATH' environment variable defined.
|
| Examples
| --------
| See `GPUTree explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/GPUTree.html>`_
|
| Method resolution order:
| GPUTreeExplainer
| shap.explainers._tree.TreeExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| shap_interaction_values(self, X, y=None, tree_limit=None)
| Estimate the SHAP interaction values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions (not
| yet supported).
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default None means no use the limit
| of the
| original model, and -1 means no limit.
|
| Returns
| -------
| array or list
| For models with a single output this returns a tensor of SHAP values
| (# samples x # features x # features). The matrix (# features x # features) for each
| sample sums
| to the difference between the model output for that sample and the expected value of
| the model output
| (which is stored in the expected_value attribute of the explainer). Each row of this
| matrix sums to the
| SHAP value for that feature for that sample. The diagonal entries of the matrix
| represent the
| "main effect" of that feature on the prediction and the symmetric off-diagonal
| entries represent the
| interaction effects between all pairs of features for that sample. For models with
| vector outputs
| this returns a list of tensors, one for each output.
|
| shap_values(self, X, y=None, tree_limit=None, approximate=False, check_additivity=True, from_call=False)
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions.
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default None means no use the limit
| of the
| original model, and -1 means no limit.
|
| approximate : bool
| Not supported.
|
| check_additivity : bool
| Run a validation check that the sum of the SHAP values equals the output of the
| model. This
| check takes only a small amount of time, and will catch potential unforeseen errors.
| Note that this check only runs right now when explaining the margin of the model.
|
| Returns
| -------
| array or list
| For models with a single output this returns a matrix of SHAP values
| (# samples x # features). Each row sums to the difference between the model output
| for that
| sample and the expected value of the model output (which is stored in the expected_value
| attribute of the explainer when it is constant). For models with vector outputs this
| returns
| a list of such matrices, one for each output.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._tree.TreeExplainer:
|
| __call__(self, X: 'Any', y: 'np.ndarray | pd.Series | None' = None, interactions: 'bool' = False, check_additivity: 'bool' = True, approximate: 'bool' = False) -> 'Explanation'
| Calculate the SHAP values for the model applied to the data.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array, optional
| An array of label values for each sample. Used when explaining loss functions.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| interactions: bool
| Whether to compute the SHAP interaction values.
|
| check_additivity: bool
| Check if the sum of the SHAP values equals the output of the model.
|
| Returns
| -------
| shap.Explanation object containing the given data and the SHAP values.
|
| __init__(self, model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
| Build a new Tree explainer for the passed model.
|
| Parameters
| ----------
| model : model object
| The tree based machine learning model that we want to explain.
| XGBoost, LightGBM, CatBoost, Pyspark and most tree-based
| scikit-learn models are supported.
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features.
|
| This argument is optional when
| ``feature_perturbation="tree_path_dependent"``, since in that case
| we can use the number of training samples that went down each tree
| path as our background dataset (this is recorded in the ``model``
| object).
|
| feature_perturbation : "auto" (default), "interventional" or "tree_path_dependent"
| Since SHAP values rely on conditional expectations, we need to
| decide how to handle correlated (or otherwise dependent) input
| features.
|
| - if ``"interventional"``, a background dataset ``data`` is required. The
| dependencies between features are handled according to the rules dictated
| by causal inference [1]_. The runtime scales linearly with the size of the
| background dataset you use: anywhere from 100 to 1000 random background
| samples are good sizes to use.
| - if ``"tree_path_dependent"``, no background dataset is required and the
| approach is to just follow the trees and use the number of training
| examples that went down each leaf to represent the background
| distribution.
| - if ``"auto"``, the "interventional" approach will be used when a
| background is provided, otherwise the "tree_path_dependent" approach will
| be used.
|
| .. versionadded:: 0.47
| The `"auto"` option was added.
|
| .. versionchanged:: 0.47
| The default behaviour will change from `"interventional"` to `"auto"` in 0.47.
| In the future, passing `feature_pertubation="interventional"` without providing
| a background dataset will raise an error.
|
|
| model_output : "raw", "probability", "log_loss", or model method name
| What output of the model should be explained.
|
| * If "raw", then we explain the raw output of the trees, which
| varies by model. For regression models, "raw" is the standard
| output. For binary classification in XGBoost, this is the log odds
| ratio.
| * If "probability", then we explain the output of the model
| transformed into probability space (note that this means the SHAP
| values now sum to the probability output of the model).
| * If "log_loss", then we explain the natural logarithm of the model
| loss function, so that the SHAP values sum up to the log loss of
| the model for each sample. This is helpful for breaking down model
| performance by feature.
| * If ``model_output`` is the name of a supported prediction method
| on the ``model`` object, then we explain the output of that model
| method name. For example, ``model_output="predict_proba"``
| explains the result of calling ``model.predict_proba``.
|
| Currently the "probability" and "log_loss" options are only
| supported when ``feature_perturbation="interventional"``.
|
| approximate : bool
| Deprecated, will be deprecated in v0.47.0 and removed in version v0.49.0.
| Please use the ``approximate`` argument in the :meth:`.shap_values` or ``__call__`` methods instead.
|
| References
| ----------
| .. [1] Janzing, Dominik, Lenon Minorics, and Patrick Blöbaum.
| "Feature relevance quantification in explainable AI: A causal problem."
| International Conference on artificial intelligence and statistics. PMLR, 2020.
|
| assert_additivity(self, phi: 'npt.NDArray[Any] | list[npt.NDArray[Any]]', model_output: 'npt.NDArray[Any]') -> 'None'
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._tree.TreeExplainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class GradientExplainer(shap.explainers._explainer.Explainer)
| GradientExplainer(model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | list[typing.Any], session: Any = None, batch_size: int = 50, local_smoothing: float = 0) -> None
|
| Explains a model using expected gradients (an extension of integrated gradients).
|
| Expected gradients an extension of the integrated gradients method (Sundararajan et al. 2017), a
| feature attribution method designed for differentiable models based on an extension of Shapley
| values to infinite player games (Aumann-Shapley values). Integrated gradients values are a bit
| different from SHAP values, and require a single reference value to integrate from. As an adaptation
| to make them approximate SHAP values, expected gradients reformulates the integral as an expectation
| and combines that expectation with sampling reference values from the background dataset. This leads
| to a single combined expectation of gradients that converges to attributions that sum to the
| difference between the expected model output and the current output.
|
| Examples
| --------
| See :ref:`Gradient Explainer Examples <gradient_explainer_examples>`
|
| Method resolution order:
| GradientExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: Any, nsamples: int = 200) -> shap._explanation.Explanation
| Return an explanation object for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
| nsamples : int
| number of background samples
|
| Returns
| -------
| shap.Explanation:
|
| __init__(self, model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | list[typing.Any], session: Any = None, batch_size: int = 50, local_smoothing: float = 0) -> None
| An explainer object for a differentiable model using a given background dataset.
|
| Parameters
| ----------
| model : tf.keras.Model, (input : [tf.Tensor], output : tf.Tensor), torch.nn.Module, or a tuple
| (model, layer), where both are torch.nn.Module objects
|
| For TensorFlow this can be a model object, or a pair of TensorFlow tensors (or a list and
| a tensor) that specifies the input and output of the model to be explained. Note that for
| TensowFlow 2 you must pass a tensorflow function, not a tuple of input/output tensors).
|
| For PyTorch this can be a nn.Module object (model), or a tuple (model, layer), where both
| are nn.Module objects. The model is an nn.Module object which takes as input a tensor
| (or list of tensors) of shape data, and returns a single dimensional output. If the input
| is a tuple, the returned shap values will be for the input of the layer argument. layer must
| be a layer in the model, i.e. model.conv2.
|
| data : [np.array] or [pandas.DataFrame] or [torch.tensor]
| The background dataset to use for integrating out features. Gradient explainer integrates
| over these samples. The data passed here must match the input tensors given in the
| first argument. Single element lists can be passed unwrapped.
|
| shap_values(self, X: Any, nsamples: int = 200, ranked_outputs: int | list[int] | None = None, output_rank_order: Literal['max', 'min', 'max_abs', 'custom'] = 'max', rseed: int | None = None, return_variances: bool = False) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | list[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]] | tuple[typing.Any, ...]
| Return the values for the model applied to X.
|
| Parameters
| ----------
| X : list,
| if framework == 'tensorflow': np.array, or pandas.DataFrame
| if framework == 'pytorch': torch.tensor
| A tensor (or list of tensors) of samples (where X.shape[0] == # samples) on which to
| explain the model's output.
|
| ranked_outputs : None or int
| If ranked_outputs is None then we explain all the outputs in a multi-output model. If
| ranked_outputs is a positive integer then we only explain that many of the top model
| outputs (where "top" is determined by output_rank_order). Note that this causes a pair
| of values to be returned (shap_values, indexes), where shap_values is a list of numpy arrays
| for each of the output ranks, and indexes is a matrix that tells for each sample which output
| indexes were chosen as "top".
|
| output_rank_order : "max", "min", "max_abs", or "custom"
| How to order the model outputs when using ranked_outputs, either by maximum, minimum, or
| maximum absolute value. If "custom" Then "ranked_outputs" contains a list of output nodes.
|
| rseed : None or int
| Seeding the randomness in shap value computation (background example choice,
| interpolation between current and background example, smoothing).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays with corresponding shape above.
|
| If ranked_outputs is ``None`` then this list of tensors matches the
| number of model outputs. If ranked_outputs is a positive integer a
| pair is returned ``(shap_values, indexes)``, where shap_values is a
| list of tensors with a length of ranked_outputs, and indexes is a
| matrix that tells for each sample which output indexes were chosen
| as "top".
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed
| from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'explainer': '_TFGradient | _PyTorchGradient', 'fea...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class KernelExplainer(shap.explainers._explainer.Explainer)
| KernelExplainer(model: Any, data: Any, feature_names: list[str] | None = None, link: Union[Literal['identity', 'logit'], Any] = 'identity', **kwargs: Any) -> None
|
| Uses the Kernel SHAP method to explain the output of any function.
|
| Kernel SHAP is a method that uses a special weighted linear regression
| to compute the importance of each feature. The computed importance values
| are Shapley values from game theory and also coefficients from a local linear
| regression.
|
| Parameters
| ----------
| model : function or iml.Model
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array or pandas.DataFrame or shap.common.DenseData or any scipy.sparse matrix
| The background dataset to use for integrating out features. To determine the impact
| of a feature, that feature is set to "missing" and the change in the model output
| is observed. Since most models aren't designed to handle arbitrary missing data at test
| time, we simulate "missing" by replacing the feature with the values it takes in the
| background dataset. So if the background dataset is a simple sample of all zeros, then
| we would approximate a feature being missing by setting it to zero. For small problems,
| this background dataset can be the whole training set, but for larger problems consider
| using a single reference value or using the ``kmeans`` function to summarize the dataset.
| Note: for the sparse case, we accept any sparse matrix but convert to lil format for
| performance.
|
| feature_names : list
| The names of the features in the background dataset. If the background dataset is
| supplied as a pandas.DataFrame, then ``feature_names`` can be set to ``None`` (default),
| and the feature names will be taken as the column names of the dataframe.
|
| link : "identity" or "logit"
| A generalized linear model link to connect the feature importance values to the model
| output. Since the feature importance values, phi, sum up to the model output, it often makes
| sense to connect them to the output with a link function where link(output) = sum(phi).
| Default is "identity" (a no-op).
| If the model output is a probability, then "logit" can be used to transform the SHAP values
| into log-odds units.
|
| Examples
| --------
| See :ref:`Kernel Explainer Examples <kernel_explainer_examples>`.
|
| Method resolution order:
| KernelExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | scipy.sparse._matrix.spmatrix, l1_reg: str | float | bool = 'num_features(10)', silent: bool = False) -> shap._explanation.Explanation
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: Any, data: Any, feature_names: list[str] | None = None, link: Union[Literal['identity', 'logit'], Any] = 'identity', **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| addsample(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix, m: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], w: float) -> None
|
| allocate(self) -> None
|
| explain(self, incoming_instance: Any, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
|
| run(self) -> None
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | pandas.core.series.Series | scipy.sparse._matrix.spmatrix, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| nsamples : "auto" or int
| Number of times to re-evaluate the model when explaining each prediction. More samples
| lead to lower variance estimates of the SHAP values. The "auto" setting uses
| `nsamples = 2 * X.shape[1] + 2048`.
|
| l1_reg : "num_features(int)", "aic", "bic", or float
| The l1 regularization to use for feature selection. The estimation
| procedure is based on a debiased lasso.
|
| * "num_features(int)" selects a fixed number of top features.
| * "aic" and "bic" options use the AIC and BIC rules for regularization.
| * Passing a float directly sets the "alpha" parameter of the
| ``sklearn.linear_model.Lasso`` model used for feature selection.
| * "auto" (deprecated): uses "aic" when less than
| 20% of the possible sample space is enumerated, otherwise it uses
| no regularization.
|
| .. versionchanged:: 0.47.0
| The default value changed from ``"auto"`` to ``"num_features(10)"``.
|
| silent: bool
| If True, hide tqdm progress bar. Default False.
|
| gc_collect : bool
| Run garbage collection after each explanation round. Sometime needed for memory intensive explanations (default False).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as the ``expected_value``
| attribute of the explainer).
|
| The type and shape of the return value depends on the number of model inputs and outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays of corresponding shape above.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| solve(self, fraction_evaluated: float, dim: int) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
|
| varying_groups(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| not_equal(i: Any, j: Any) -> int
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'D': <class 'int'>, 'M': <class 'int'>, 'N': <class...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class LinearExplainer(shap.explainers._explainer.Explainer)
| LinearExplainer(model: Any, masker: Any, link: collections.abc.Callable[[typing.Any], typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), nsamples: int = 1000, feature_perturbation: Optional[Literal['interventional', 'correlation_dependent']] = None, **kwargs: Any) -> None
|
| Computes SHAP values for a linear model, optionally accounting for inter-feature correlations.
|
| This computes the SHAP values for a linear model and can account for the
| correlations among the input features. Assuming features are independent
| leads to interventional SHAP values which for a linear model are ``coef[i] *
| (x[i] - X.mean(0)[i])`` for the ith feature. If instead we account for
| correlations, then we prevent any problems arising from collinearity and
| share credit among correlated features. Accounting for correlations can be
| computationally challenging, but ``LinearExplainer`` uses sampling to
| estimate a transform that can then be applied to explain any prediction of
| the model.
|
| Parameters
| ----------
| model : (coef, intercept) or sklearn.linear_model.*
| User supplied linear model either as either a parameter pair or sklearn object.
|
| masker : function, numpy.array, pandas.DataFrame, tuple of (mean, cov), shap.maskers.Masker
| A callable Python object used to "mask" out hidden features of the form
| ``masker(binary_mask, x)``. It takes a single input sample and a binary
| mask and returns a matrix of masked samples. These masked samples are
| evaluated using the model function and the outputs are then averaged.
|
| As a shortcut for the standard masking using by SHAP you can pass a
| background data matrix instead of a function and that matrix will be
| used for masking.
|
| You can also provide a tuple of ``(mean, covariance)``, or pass in a
| masker meant for tabular data (i.e., :class:`.maskers.Independent`,
| :class:`.maskers.Impute`, or :class:`.maskers.Partition`) directly.
|
| data : (mean, cov), numpy.array, pandas.DataFrame, iml.DenseData or scipy.csr_matrix
| The background dataset to use for computing conditional expectations.
| Note that only the mean and covariance of the dataset are used. This
| means passing a raw data matrix is just a convenient alternative to
| passing the mean and covariance directly.
|
| nsamples : int
| Number of samples to use when estimating the transformation matrix used
| to account for feature correlations.
|
| feature_perturbation : None (default), "interventional" or "correlation_dependent"
|
| DEPRECATED: this option is now deprecated in favor of using the appropriate
| tabular masker and will be removed in a future release.
|
| There are two ways we might want to compute SHAP values, either the full
| conditional SHAP values or the interventional SHAP values.
|
| - For interventional SHAP values we break any dependence structure between
| features in the model and so uncover how the model would behave if we
| intervened and changed some of the inputs. This approach is used by the
| Independent and Partition maskers.
| - For the full conditional SHAP values we respect the correlations among the
| input features, so if the model depends on one input but that input is
| correlated with another input, then both get some credit for the model's
| behavior. This approach is used by the Impute masker.
|
| The interventional option stays "true to the model" meaning it will only
| give credit to features that are actually used by the model, while the
| correlation option stays "true to the data" in the sense that it only
| considers how the model would behave when respecting the correlations in
| the input data. For sparse case only interventional option is supported.
|
|
| Examples
| --------
| See `Linear explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/LinearExplainer.html>`_
|
| Method resolution order:
| LinearExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model: Any, masker: Any, link: collections.abc.Callable[[typing.Any], typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), nsamples: int = 1000, feature_perturbation: Optional[Literal['interventional', 'correlation_dependent']] = None, **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]] | pandas.core.frame.DataFrame | pandas.core.series.Series) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or scipy.csr_matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| Returns
| -------
| np.array
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored
| as the ``expected_value`` attribute of the explainer).
|
| The shape of the returned array depends on the number of model outputs:
|
| * one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * multiple outputs: array of shape ``(#num_samples, *X.shape[1:],
| #num_outputs)``.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: Any, masker: Any) -> bool
| Determines if we can parse the given model.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'M': <class 'int'>, 'avg_proj': numpy.ndarray[typin...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PartitionExplainer(shap.explainers._explainer.Explainer)
| PartitionExplainer(model: Any, masker: Any, *, output_names: list[str] | None = None, link: collections.abc.Callable[..., typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: bool = True, feature_names: list[str] | None = None, **call_args: Any) -> None
|
| Uses the Partition SHAP method to explain the output of any function.
|
| Partition SHAP computes Shapley values recursively through a hierarchy of features, this
| hierarchy defines feature coalitions and results in the Owen values from game theory.
|
| The PartitionExplainer has two particularly nice properties:
|
| 1) PartitionExplainer is model-agnostic but when using a balanced partition tree only has
| quadratic exact runtime (in term of the number of input features). This is in contrast to the
| exponential exact runtime of KernelExplainer or SamplingExplainer.
| 2) PartitionExplainer always assigns to groups of correlated features the credit that set of features
| would have had if treated as a group. This means if the hierarchical clustering given to
| PartitionExplainer groups correlated features together, then feature correlations are
| "accounted for" in the sense that the total credit assigned to a group of tightly dependent features
| does not depend on how they behave if their correlation structure was broken during the explanation's
| perturbation process.
|
| Note that for linear models the Owen values that PartitionExplainer returns are the same as the standard
| non-hierarchical Shapley values.
|
| Method resolution order:
| PartitionExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: Any, max_evals: Union[int, Literal['auto']] = 500, fixed_context: Optional[Literal[0, 1]] = None, main_effects: bool = False, error_bounds: bool = False, batch_size: Union[int, Literal['auto']] = 'auto', outputs: Any = None, silent: bool = False, **kwargs: Any) -> shap._explanation.Explanation | list[shap._explanation.Explanation]
| Explain the output of the model on the given arguments.
|
| __init__(self, model: Any, masker: Any, *, output_names: list[str] | None = None, link: collections.abc.Callable[..., typing.Any] = CPUDispatcher(<function identity at 0x00000213EC6080E0>), linearize_link: bool = True, feature_names: list[str] | None = None, **call_args: Any) -> None
| Build a PartitionExplainer for the given model with the given masker.
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples.
|
| masker : function or numpy.array or pandas.DataFrame or tokenizer
| The function used to "mask" out hidden features of the form `masker(mask, x)`. It takes a
| single input sample and a binary mask and returns a matrix of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.maksers.Image for images and shap.maskers.Text
| for text.
|
| partition_tree : None or function or numpy.array
| A hierarchical clustering of the input features represented by a matrix that follows the format
| used by scipy.cluster.hierarchy (see the notebooks_html/partition_explainer directory an example).
| If this is a function then the function produces a clustering matrix when given a single input
| example. If you are using a standard SHAP masker object then you can pass masker.clustering
| to use that masker's built-in clustering of the features, or if partition_tree is None then
| masker.clustering will be used by default.
|
| Examples
| --------
| See `Partition explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/PartitionExplainer.html>`_
|
| __str__(self) -> str
| Return str(self).
|
| explain_row(self, *row_args: Any, max_evals: Union[int, Literal['auto']], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, batch_size: Union[int, Literal['auto']] = 'auto', fixed_context: Optional[Literal[0, 1, 'auto']] = 'auto', **kwargs: Any) -> dict[str, typing.Any]
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| owen(self, fm: shap.utils._masked_model.MaskedModel, f00: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], f11: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], max_evals: int, output_indexes: Any, fixed_context: Optional[Literal[0, 1]], batch_size: Union[int, Literal['auto']], silent: bool) -> tuple[typing.Any, numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
| Compute a nested set of recursive Owen values based on an ordering recursion.
|
| owen3(self, fm: shap.utils._masked_model.MaskedModel, f00: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], f11: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], max_evals: int, output_indexes: Any, fixed_context: Optional[Literal[0, 1]], batch_size: Union[int, Literal['auto']], silent: bool) -> tuple[typing.Any, numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
| Compute a nested set of recursive Owen values based on an ordering recursion.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_clustering': numpy.ndarray[typing.Any, numpy.dtyp...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PermutationExplainer(shap.explainers._explainer.Explainer)
| PermutationExplainer(model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **call_args: 'Any') -> 'None'
|
| This method approximates the Shapley values by iterating through permutations of the inputs.
|
| This is a model agnostic explainer that guarantees local accuracy (additivity) by iterating completely
| through an entire permutation of the features in both forward and reverse directions (antithetic sampling).
| If we do this once, then we get the exact SHAP values for models with up to second order interaction effects.
| We can iterate this many times over many random permutations to get better SHAP value estimates for models
| with higher order interactions. This sequential ordering formulation also allows for easy reuse of
| model evaluations and the ability to efficiently avoid evaluating the model when the background values
| for a feature are the same as the current input value. We can also account for hierarchical data
| structures with partition trees, something not currently implemented for KernalExplainer or SamplingExplainer.
|
| Examples
| --------
| See `Permutation explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/Permutation.html>`_
|
| Method resolution order:
| PermutationExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 500, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explain the output of the model on the given arguments.
|
| __init__(self, model: 'Any', masker: 'Any', link: 'Any' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | None' = None, linearize_link: 'bool' = True, seed: 'int | None' = None, **call_args: 'Any') -> 'None'
| Build an explainers.Permutation object for the given model using the given masker object.
|
| Parameters
| ----------
| model : function
| A callable python object that executes the model given a set of input data samples.
|
| masker : function or numpy.array or pandas.DataFrame
| A callable python object used to "mask" out hidden features of the form ``masker(binary_mask, x)``.
| It takes a single input sample and a binary mask and returns a matrix of masked samples. These
| masked samples are evaluated using the model function and the outputs are then averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. To use a clustering
| game structure you can pass a ``shap.maskers.Tabular(data, clustering="correlation")`` object.
|
| seed: None or int
| Seed for reproducibility
|
| **call_args : valid argument to the __call__ method
| These arguments are saved and passed to the __call__ method as the new default values for these arguments.
|
| __str__(self) -> 'str'
| Return str(self).
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', batch_size: "int | Literal['auto']", outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes).
|
| shap_values(self, X: 'Any', npermutations: 'int' = 10, main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_evals: 'bool' = True, silent: 'bool' = False) -> 'Any'
| Legacy interface to estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| npermutations : int
| Number of times to cycle through all the features, re-evaluating the model at each step.
| Each cycle evaluates the model function 2 * (# features + 1) times on a data matrix of
| (# background data samples) rows. An exception to this is when PermutationExplainer can
| avoid evaluating the model because a feature's value is the same in X and the background
| dataset (which is common for example with sparse features).
|
| Returns
| -------
| array or list
| For models with a single output this returns a matrix of SHAP values
| (# samples x # features). Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as expected_value
| attribute of the explainer). For models with vector outputs this returns a list
| of such matrices, one for each output.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class SamplingExplainer(shap.explainers._kernel.KernelExplainer)
| SamplingExplainer(model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, **kwargs: Any) -> None
|
| Computes SHAP values using an extension of the Shapley sampling values explanation method
| (also known as IME).
|
| SamplingExplainer computes SHAP values under the assumption of feature independence and is an
| extension of the algorithm proposed in "An Efficient Explanation of Individual Classifications
| using Game Theory", Erik Strumbelj, Igor Kononenko, JMLR 2010. It is a good alternative to
| KernelExplainer when you want to use a large background set (as opposed to a single reference
| value for example).
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features. To determine the impact
| of a feature, that feature is set to "missing" and the change in the model output
| is observed. Since most models aren't designed to handle arbitrary missing data at test
| time, we simulate "missing" by replacing the feature with the values it takes in the
| background dataset. So if the background dataset is a simple sample of all zeros, then
| we would approximate a feature being missing by setting it to zero. Unlike the
| KernelExplainer, this data can be the whole training set, even if that is a large set. This
| is because SamplingExplainer only samples from this background dataset.
|
| Method resolution order:
| SamplingExplainer
| shap.explainers._kernel.KernelExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, y: Any = None, nsamples: int = 2000) -> shap._explanation.Explanation
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| __init__(self, model: Any, data: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame, **kwargs: Any) -> None
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain(self, incoming_instance: Any, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]
|
| sampling_estimate(self, j: int, f: Any, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], nsamples: int = 10) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]], numpy.ndarray[typing.Any, numpy.dtype[numpy.floating[typing.Any]]]]
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._kernel.KernelExplainer:
|
| addsample(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix, m: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], w: float) -> None
|
| allocate(self) -> None
|
| run(self) -> None
|
| shap_values(self, X: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | pandas.core.frame.DataFrame | pandas.core.series.Series | scipy.sparse._matrix.spmatrix, **kwargs: Any) -> numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| nsamples : "auto" or int
| Number of times to re-evaluate the model when explaining each prediction. More samples
| lead to lower variance estimates of the SHAP values. The "auto" setting uses
| `nsamples = 2 * X.shape[1] + 2048`.
|
| l1_reg : "num_features(int)", "aic", "bic", or float
| The l1 regularization to use for feature selection. The estimation
| procedure is based on a debiased lasso.
|
| * "num_features(int)" selects a fixed number of top features.
| * "aic" and "bic" options use the AIC and BIC rules for regularization.
| * Passing a float directly sets the "alpha" parameter of the
| ``sklearn.linear_model.Lasso`` model used for feature selection.
| * "auto" (deprecated): uses "aic" when less than
| 20% of the possible sample space is enumerated, otherwise it uses
| no regularization.
|
| .. versionchanged:: 0.47.0
| The default value changed from ``"auto"`` to ``"num_features(10)"``.
|
| silent: bool
| If True, hide tqdm progress bar. Default False.
|
| gc_collect : bool
| Run garbage collection after each explanation round. Sometime needed for memory intensive explanations (default False).
|
| Returns
| -------
| np.array or list
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| Each row sums to the difference between the model output for that
| sample and the expected value of the model output (which is stored as the ``expected_value``
| attribute of the explainer).
|
| The type and shape of the return value depends on the number of model inputs and outputs:
|
| * one input, one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * one input, multiple outputs: array of shape ``(#num_samples, *X.shape[1:], #num_outputs)``
| * multiple inputs: list of arrays of corresponding shape above.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs and one input changed from list to np.ndarray.
|
| solve(self, fraction_evaluated: float, dim: int) -> tuple[numpy.ndarray[typing.Any, numpy.dtype[typing.Any]], numpy.ndarray[typing.Any, numpy.dtype[typing.Any]]]
|
| varying_groups(self, x: numpy.ndarray[typing.Any, numpy.dtype[typing.Any]] | scipy.sparse._matrix.spmatrix) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._kernel.KernelExplainer:
|
| not_equal(i: Any, j: Any) -> int
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TreeExplainer(shap.explainers._explainer.Explainer)
| TreeExplainer(model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
|
| Uses Tree SHAP algorithms to explain the output of ensemble tree models.
|
| Tree SHAP is a fast and exact method to estimate SHAP values for tree models
| and ensembles of trees, under several different possible assumptions about
| feature dependence. It depends on fast C++ implementations either inside an
| external model package or in the local compiled C extension.
|
| Examples
| --------
| See `Tree explainer examples <https://shap.readthedocs.io/en/latest/api_examples/explainers/Tree.html>`_
|
| Method resolution order:
| TreeExplainer
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X: 'Any', y: 'np.ndarray | pd.Series | None' = None, interactions: 'bool' = False, check_additivity: 'bool' = True, approximate: 'bool' = False) -> 'Explanation'
| Calculate the SHAP values for the model applied to the data.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array, optional
| An array of label values for each sample. Used when explaining loss functions.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| interactions: bool
| Whether to compute the SHAP interaction values.
|
| check_additivity: bool
| Check if the sum of the SHAP values equals the output of the model.
|
| Returns
| -------
| shap.Explanation object containing the given data and the SHAP values.
|
| __init__(self, model: 'Any', data: 'npt.NDArray[Any] | pd.DataFrame | None' = None, model_output: 'str' = 'raw', feature_perturbation: "Literal['auto', 'interventional', 'tree_path_dependent']" = 'auto', feature_names: 'list[str] | None' = None, approximate: 'Any' = <object object at 0x00000213ECFD08A0>, link: 'Any' = None, linearize_link: 'Any' = None) -> 'None'
| Build a new Tree explainer for the passed model.
|
| Parameters
| ----------
| model : model object
| The tree based machine learning model that we want to explain.
| XGBoost, LightGBM, CatBoost, Pyspark and most tree-based
| scikit-learn models are supported.
|
| data : numpy.array or pandas.DataFrame
| The background dataset to use for integrating out features.
|
| This argument is optional when
| ``feature_perturbation="tree_path_dependent"``, since in that case
| we can use the number of training samples that went down each tree
| path as our background dataset (this is recorded in the ``model``
| object).
|
| feature_perturbation : "auto" (default), "interventional" or "tree_path_dependent"
| Since SHAP values rely on conditional expectations, we need to
| decide how to handle correlated (or otherwise dependent) input
| features.
|
| - if ``"interventional"``, a background dataset ``data`` is required. The
| dependencies between features are handled according to the rules dictated
| by causal inference [1]_. The runtime scales linearly with the size of the
| background dataset you use: anywhere from 100 to 1000 random background
| samples are good sizes to use.
| - if ``"tree_path_dependent"``, no background dataset is required and the
| approach is to just follow the trees and use the number of training
| examples that went down each leaf to represent the background
| distribution.
| - if ``"auto"``, the "interventional" approach will be used when a
| background is provided, otherwise the "tree_path_dependent" approach will
| be used.
|
| .. versionadded:: 0.47
| The `"auto"` option was added.
|
| .. versionchanged:: 0.47
| The default behaviour will change from `"interventional"` to `"auto"` in 0.47.
| In the future, passing `feature_pertubation="interventional"` without providing
| a background dataset will raise an error.
|
|
| model_output : "raw", "probability", "log_loss", or model method name
| What output of the model should be explained.
|
| * If "raw", then we explain the raw output of the trees, which
| varies by model. For regression models, "raw" is the standard
| output. For binary classification in XGBoost, this is the log odds
| ratio.
| * If "probability", then we explain the output of the model
| transformed into probability space (note that this means the SHAP
| values now sum to the probability output of the model).
| * If "log_loss", then we explain the natural logarithm of the model
| loss function, so that the SHAP values sum up to the log loss of
| the model for each sample. This is helpful for breaking down model
| performance by feature.
| * If ``model_output`` is the name of a supported prediction method
| on the ``model`` object, then we explain the output of that model
| method name. For example, ``model_output="predict_proba"``
| explains the result of calling ``model.predict_proba``.
|
| Currently the "probability" and "log_loss" options are only
| supported when ``feature_perturbation="interventional"``.
|
| approximate : bool
| Deprecated, will be deprecated in v0.47.0 and removed in version v0.49.0.
| Please use the ``approximate`` argument in the :meth:`.shap_values` or ``__call__`` methods instead.
|
| References
| ----------
| .. [1] Janzing, Dominik, Lenon Minorics, and Patrick Blöbaum.
| "Feature relevance quantification in explainable AI: A causal problem."
| International Conference on artificial intelligence and statistics. PMLR, 2020.
|
| assert_additivity(self, phi: 'npt.NDArray[Any] | list[npt.NDArray[Any]]', model_output: 'npt.NDArray[Any]') -> 'None'
|
| shap_interaction_values(self, X: 'npt.NDArray[Any] | pd.DataFrame | Any', y: 'npt.NDArray[Any] | pd.Series | None' = None, tree_limit: 'int | None' = None) -> 'npt.NDArray[Any]'
| Estimate the SHAP interaction values for a set of samples.
|
| Parameters
| ----------
| X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions (not yet supported).
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default, the limit of the original model
| is used (``None``). ``-1`` means no limit.
|
| Returns
| -------
| np.array
| Returns a matrix. The shape depends on the number of model outputs:
|
| * one output: matrix of shape (#num_samples, #features, #features).
| * multiple outputs: matrix of shape (#num_samples, #features, #features, #num_outputs).
|
| The matrix (#num_samples, # features, # features) for each sample sums
| to the difference between the model output for that sample and the expected value of the model output
| (which is stored in the ``expected_value`` attribute of the explainer). Each row of this matrix sums to the
| SHAP value for that feature for that sample. The diagonal entries of the matrix represent the
| "main effect" of that feature on the prediction. The symmetric off-diagonal entries represent the
| interaction effects between all pairs of features for that sample.
| For models with vector outputs, this returns a list of tensors, one for each output.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| shap_values(self, X: 'Any', y: 'npt.NDArray[Any] | pd.Series | None' = None, tree_limit: 'int | None' = None, approximate: 'bool' = False, check_additivity: 'bool' = True, from_call: 'bool' = False) -> 'npt.NDArray[Any]'
| Estimate the SHAP values for a set of samples.
|
| Parameters
| ----------
| X : Any
| Can be a dataframe like object, e.g. numpy.array, pandas.DataFrame or catboost.Pool (for catboost).
| A matrix of samples (# samples x # features) on which to explain the model's output.
|
| y : numpy.array
| An array of label values for each sample. Used when explaining loss functions.
|
| tree_limit : None (default) or int
| Limit the number of trees used by the model. By default, the limit of the original model
| is used (``None``). ``-1`` means no limit.
|
| approximate : bool
| Run fast, but only roughly approximate the Tree SHAP values. This runs a method
| previously proposed by Saabas which only considers a single feature ordering. Take care
| since this does not have the consistency guarantees of Shapley values and places too
| much weight on lower splits in the tree.
|
| check_additivity : bool
| Run a validation check that the sum of the SHAP values equals the output of the model. This
| check takes only a small amount of time, and will catch potential unforeseen errors.
| Note that this check only runs right now when explaining the margin of the model.
|
| Returns
| -------
| np.array
| Estimated SHAP values, usually of shape ``(# samples x # features)``.
|
| For each output, the sum of the SHAP values plus the ``expected_value``
| equals the model's output (in the specified output space):
|
| * Single output: ``shap_values[i, :].sum() + expected_value = f(x)[i]``
| * Multiple outputs: ``shap_values[i, :, j].sum() + expected_value[j] = f(x)[i, j]``
|
| .. note::
| The ``f(x)`` value is NOT necessarily what ``model.predict()``
| or ``model.predict_proba()`` returns. For example, for an XGBoost Classifier with the default
| ``model_output="raw"``, the explainer returns log-odds (margins).
| To compare this mathematically against ``predict_proba()`` probabilities,
| a logistic inverse-transform (e.g., ``scipy.special.expit``) must be applied
| to the sum.
|
| Furthermore, the additivity formula requires SHAP values and model
| predictions to be computed on the same samples in the same order.
|
| The shape of the returned array depends on the number of model outputs:
|
| * one output: array of shape ``(#num_samples, *X.shape[1:])``.
| * multiple outputs: array of shape ``(#num_samples, *X.shape[1:],
| #num_outputs)``.
|
| **Examples:**
|
| * **Regression:** A ``RandomForestRegressor`` returns SHAP values of shape
| ``(#num_samples, #num_features)`` with a scalar ``expected_value``.
|
| * **Binary classification:** Output behavior varies by model:
|
| - **Scikit-learn models** (e.g., ``RandomForestClassifier``) output
| probabilities for both classes, resulting in SHAP values of shape
| ``(#num_samples, #num_features, 2)`` and ``expected_value`` as an
| array of length 2.
|
| - **XGBoost and LightGBM** (with default ``model_output="raw"``) output
| a single value (raw margin/log-odds), resulting in SHAP values of shape
| ``(#num_samples, #num_features)`` and ``expected_value`` as a scalar.
|
| .. versionchanged:: 0.45.0
| Return type for models with multiple outputs changed from list to np.ndarray.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'data': 'npt.NDArray[Any] | None', 'data_feature_na...
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['AdditiveExplainer', 'DeepExplainer', 'ExactExplainer', 'GP...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\explainers\__init__.py
shap.force_plot
Python Library Documentation: function force in module shap.plots._force
force(base_value, shap_values=None, features=None, feature_names=None, out_names=None, link='identity', plot_cmap='RdBu', matplotlib=False, show=True, figsize=(20, 3), ordering_keys=None, ordering_keys_time_format=None, text_rotation=0, contribution_threshold=0.05)
Visualize the given SHAP values with an additive force layout.
Parameters
----------
base_value : float or shap.Explanation
If a float is passed in, this is the reference value that the feature contributions start from.
For SHAP values, it should be the value of ``explainer.expected_value``.
However, it is recommended to pass in a SHAP :class:`.Explanation` object instead (``shap_values``
is not necessary in this case).
shap_values : numpy.array
Matrix of SHAP values (# features) or (# samples x # features). If this is a
1D array, then a single force plot will be drawn. If it is a 2D array, then a
stacked force plot will be drawn.
features : numpy.array
Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
features, and should be the same shape as the ``shap_values`` argument.
feature_names : list
List of feature names (# features).
out_names : str
The name of the output of the model (plural to support multi-output plotting in the future).
link : "identity" or "logit"
The transformation used when drawing the tick mark labels. Using "logit" will change log-odds numbers
into probabilities.
plot_cmap : str or list[str]
Color map to use. It can be a string (defaults to ``RdBu``) or a list of hex color strings.
matplotlib : bool
Whether to use the default Javascript output, or the (less developed) matplotlib output.
Using matplotlib can be helpful in scenarios where rendering Javascript/HTML
is inconvenient. Defaults to False.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
Only applicable when ``matplotlib`` is set to True.
figsize :
Figure size of the matplotlib output.
contribution_threshold : float
Controls the feature names/values that are displayed on force plot.
Only features that the magnitude of their shap value is larger than min_perc * (sum of all abs shap values)
will be displayed.
shap.getjs
Python Library Documentation: function getjs in module shap.plots._force getjs()
shap.group_difference_plot
Python Library Documentation: function group_difference in module shap.plots._group_difference
group_difference(shap_values, group_mask, feature_names=None, xlabel=None, xmin=None, xmax=None, max_display=None, sort=True, show=True, ax=None)
This plots the difference in mean SHAP values between two groups.
It is useful to decompose many group level metrics about the model output among the
input features. Quantitative fairness metrics for machine learning models are
a common example of such group level metrics.
Parameters
----------
shap_values : numpy.array
Matrix of SHAP values (# samples x # features) or a vector of model outputs (# samples).
group_mask : numpy.array
A boolean mask where True represents the first group of samples and False the second.
feature_names : list
A list of feature names.
shap.have_matplotlib
Python Library Documentation: bool object class bool(int) | bool(x) -> bool | | Returns True when the argument x is true, False otherwise. | The builtins True and False are the only two instances of the class bool. | The class bool is a subclass of the class int, and cannot be subclassed. | | Method resolution order: | bool | int | object | | Methods defined here: | | __and__(self, value, /) | Return self&value. | | __invert__(self, /) | ~self | | __or__(self, value, /) | Return self|value. | | __rand__(self, value, /) | Return value&self. | | __repr__(self, /) | Return repr(self). | | __ror__(self, value, /) | Return value|self. | | __rxor__(self, value, /) | Return value^self. | | __xor__(self, value, /) | Return self^value. | | ---------------------------------------------------------------------- | Static methods defined here: | | __new__(*args, **kwargs) | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Methods inherited from int: | | __abs__(self, /) | abs(self) | | __add__(self, value, /) | Return self+value. | | __bool__(self, /) | True if self else False | | __ceil__(...) | Ceiling of an Integral returns itself. | | __divmod__(self, value, /) | Return divmod(self, value). | | __eq__(self, value, /) | Return self==value. | | __float__(self, /) | float(self) | | __floor__(...) | Flooring an Integral returns itself. | | __floordiv__(self, value, /) | Return self//value. | | __format__(self, format_spec, /) | Convert to a string according to format_spec. | | __ge__(self, value, /) | Return self>=value. | | __getattribute__(self, name, /) | Return getattr(self, name). | | __getnewargs__(self, /) | | __gt__(self, value, /) | Return self>value. | | __hash__(self, /) | Return hash(self). | | __index__(self, /) | Return self converted to an integer, if self is suitable for use as an index into a list. | | __int__(self, /) | int(self) | | __le__(self, value, /) | Return self<=value. | | __lshift__(self, value, /) | Return self<<value. | | __lt__(self, value, /) | Return self<value. | | __mod__(self, value, /) | Return self%value. | | __mul__(self, value, /) | Return self*value. | | __ne__(self, value, /) | Return self!=value. | | __neg__(self, /) | -self | | __pos__(self, /) | +self | | __pow__(self, value, mod=None, /) | Return pow(self, value, mod). | | __radd__(self, value, /) | Return value+self. | | __rdivmod__(self, value, /) | Return divmod(value, self). | | __rfloordiv__(self, value, /) | Return value//self. | | __rlshift__(self, value, /) | Return value<<self. | | __rmod__(self, value, /) | Return value%self. | | __rmul__(self, value, /) | Return value*self. | | __round__(...) | Rounding an Integral returns itself. | | Rounding with an ndigits argument also returns an integer. | | __rpow__(self, value, mod=None, /) | Return pow(value, self, mod). | | __rrshift__(self, value, /) | Return value>>self. | | __rshift__(self, value, /) | Return self>>value. | | __rsub__(self, value, /) | Return value-self. | | __rtruediv__(self, value, /) | Return value/self. | | __sizeof__(self, /) | Returns size in memory, in bytes. | | __sub__(self, value, /) | Return self-value. | | __truediv__(self, value, /) | Return self/value. | | __trunc__(...) | Truncating an Integral returns itself. | | as_integer_ratio(self, /) | Return a pair of integers, whose ratio is equal to the original int. | | The ratio is in lowest terms and has a positive denominator. | | >>> (10).as_integer_ratio() | (10, 1) | >>> (-10).as_integer_ratio() | (-10, 1) | >>> (0).as_integer_ratio() | (0, 1) | | bit_count(self, /) | Number of ones in the binary representation of the absolute value of self. | | Also known as the population count. | | >>> bin(13) | '0b1101' | >>> (13).bit_count() | 3 | | bit_length(self, /) | Number of bits necessary to represent self in binary. | | >>> bin(37) | '0b100101' | >>> (37).bit_length() | 6 | | conjugate(...) | Returns self, the complex conjugate of any int. | | is_integer(self, /) | Returns True. Exists for duck type compatibility with float.is_integer. | | to_bytes(self, /, length=1, byteorder='big', *, signed=False) | Return an array of bytes representing an integer. | | length | Length of bytes object to use. An OverflowError is raised if the | integer is not representable with the given number of bytes. Default | is length 1. | byteorder | The byte order used to represent the integer. If byteorder is 'big', | the most significant byte is at the beginning of the byte array. If | byteorder is 'little', the most significant byte is at the end of the | byte array. To request the native byte order of the host system, use | `sys.byteorder' as the byte order value. Default is to use 'big'. | signed | Determines whether two's complement is used to represent the integer. | If signed is False and a negative integer is given, an OverflowError | is raised. | | ---------------------------------------------------------------------- | Class methods inherited from int: | | from_bytes(bytes, byteorder='big', *, signed=False) | Return the integer represented by the given array of bytes. | | bytes | Holds the array of bytes to convert. The argument must either | support the buffer protocol or be an iterable object producing bytes. | Bytes and bytearray are examples of built-in objects that support the | buffer protocol. | byteorder | The byte order used to represent the integer. If byteorder is 'big', | the most significant byte is at the beginning of the byte array. If | byteorder is 'little', the most significant byte is at the end of the | byte array. To request the native byte order of the host system, use | `sys.byteorder' as the byte order value. Default is to use 'big'. | signed | Indicates whether two's complement is used to represent the integer. | | ---------------------------------------------------------------------- | Data descriptors inherited from int: | | denominator | the denominator of a rational number in lowest terms | | imag | the imaginary part of a complex number | | numerator | the numerator of a rational number in lowest terms | | real | the real part of a complex number
shap.heatmap_plot
Python Library Documentation: function heatmap in module shap.plots._heatmap
heatmap(shap_values: shap._explanation.Explanation, instance_order=shap.Explanation.hclust, feature_values=shap.Explanation.abs.mean(0), feature_order=None, max_display=10, cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EED1E810>, show=True, plot_width=8, ax=None)
Create a heatmap plot of a set of SHAP values.
This plot is designed to show the population substructure of a dataset using supervised
clustering and a heatmap.
Supervised clustering involves clustering data points not by their original
feature values but by their explanations.
By default, we cluster using :func:`shap.utils.hclust_ordering`,
but any clustering can be used to order the samples.
Parameters
----------
shap_values : shap.Explanation
A multi-row :class:`.Explanation` object that we want to visualize in a
cluster ordering.
instance_order : OpChain or numpy.ndarray
A function that returns a sort ordering given a matrix of SHAP values and an axis, or
a direct sample ordering given as an ``numpy.ndarray``.
feature_values : OpChain or numpy.ndarray
A function that returns a global summary value for each input feature, or an array of such values.
feature_order : None, OpChain, or numpy.ndarray
A function that returns a sort ordering given a matrix of SHAP values and an axis, or
a direct input feature ordering given as an ``numpy.ndarray``.
If ``None``, then we use ``feature_values.argsort``.
max_display : int
The maximum number of features to display (default is 10).
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
plot_width : int, default 8
The width of the heatmap plot.
ax : matplotlib Axes
Axes object to draw the plot onto, otherwise uses the current Axes.
Returns
-------
ax: matplotlib Axes
Returns the :external+mpl:class:`~matplotlib.axes.Axes` object with the plot drawn onto it.
Examples
--------
See `heatmap plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/heatmap.html>`_.
shap.image_plot
Python Library Documentation: function image in module shap.plots._image
image(shap_values: 'Explanation | np.ndarray | list[np.ndarray]', pixel_values: 'np.ndarray | None' = None, labels: 'list[str] | list[list[str]] | np.ndarray | None' = None, true_labels: 'list | None' = None, width: 'int | None' = 20, aspect: 'float | None' = 0.2, hspace: "float | Literal['auto'] | None" = 0.2, labelpad: 'float | None' = None, cmap: 'str | Colormap | None' = <matplotlib.colors.LinearSegmentedColormap object at 0x00000213EED1E7B0>, vmax: 'float | None' = None, show: 'bool | None' = True)
Plots SHAP values for image inputs.
Parameters
----------
shap_values : [numpy.array]
List of arrays of SHAP values. Each array has the shape
(# samples x width x height x channels), and the
length of the list is equal to the number of model outputs that are being
explained.
pixel_values : numpy.array
Matrix of pixel values (# samples x width x height x channels) for each image.
It should be the same
shape as each array in the ``shap_values`` list of arrays.
labels : list or np.ndarray
List or ``np.ndarray`` (# samples x top_k classes) of names for each of the
model outputs that are being explained.
true_labels: list
List of a true image labels to plot.
width : float
The width of the produced matplotlib plot.
labelpad : float
How much padding to use around the model output labels.
cmap: str or matplotlib.colors.Colormap
Colormap to use when plotting the SHAP values.
vmax: Optional float
Sets the colormap scale for SHAP values from ``-vmax`` to ``+vmax``.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
Examples
--------
See `image plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/image.html>`_.
shap.initjs
Python Library Documentation: function initjs in module shap.plots._force
initjs()
Initialize the necessary javascript libraries for interactive force plots.
Run this only in a notebook environment with IPython installed.
shap.kmeans
Python Library Documentation: function kmeans in module shap.utils._legacy
kmeans(X, k, round_values=True)
Summarize a dataset with k mean samples weighted by the number of data points they
each represent.
Parameters
----------
X : numpy.array or pandas.DataFrame or any scipy.sparse matrix
Matrix of data samples to summarize (# samples x # features)
k : int
Number of means to use for approximation.
round_values : bool
For all i, round the ith dimension of each mean sample to match the nearest value
from X[:,i]. This ensures discrete features always get a valid value.
Returns
-------
DenseData object.
shap.links
Python Library Documentation: module shap.links in shap
NAME
shap.links
FUNCTIONS
identity(x: 'npt.NDArray[Any] | float') -> 'npt.NDArray[Any] | float'
A no-op link function.
logit(x: 'npt.NDArray[Any] | float') -> 'npt.NDArray[Any] | float'
A logit link function useful for going from probability units to log-odds units.
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\links.py
shap.maskers
Python Library Documentation: package shap.maskers in shap
NAME
shap.maskers
PACKAGE CONTENTS
_composite
_fixed
_fixed_composite
_image
_masker
_output_composite
_tabular
_text
CLASSES
shap._serializable.Serializable(builtins.object)
shap.maskers._masker.Masker
shap.maskers._composite.Composite
shap.maskers._fixed.Fixed
shap.maskers._fixed_composite.FixedComposite
shap.maskers._image.Image
shap.maskers._output_composite.OutputComposite
shap.maskers._tabular.Impute
shap.maskers._text.Text
shap.maskers._tabular.Tabular(shap.maskers._masker.Masker)
shap.maskers._tabular.Independent
shap.maskers._tabular.Partition
class Composite(shap.maskers._masker.Masker)
| Composite(*maskers: 'Masker') -> 'None'
|
| This merges several maskers for different inputs together into a single composite masker.
|
| This is not yet implemented.
|
| Method resolution order:
| Composite
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask: 'Any', *args: 'Any') -> 'tuple[Any, ...]'
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| __init__(self, *maskers: 'Masker') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| data_transform(self, *args: 'Any') -> 'list[Any]'
| Transform the argument
|
| mask_shapes(self, *args: 'Any') -> 'list[Any]'
| The shape of the masks we expect.
|
| shape(self, *args: 'Any') -> 'tuple[int | None, int]'
| Compute the shape of this masker as the sum of all the sub masker shapes.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap._serializable.Serializable:
|
| save(self, out_file)
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap._serializable.Serializable:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Fixed(shap.maskers._masker.Masker)
| Fixed() -> 'None'
|
| This leaves the input unchanged during masking, and is used for things like scoring labels.
|
| Sometimes there are inputs to the model that we do not want to explain, but rather we want to
| consider them fixed. The primary example of this is when we explain the loss of the model using
| the labels. These "true" labels are inputs to the function we are explaining, but we don't want
| to attribute credit to them, instead we want to consider them fixed and assign all the credit to
| the model's input features. This is where the Fixed masker can help, since we can apply it to the
| label inputs.
|
| Method resolution order:
| Fixed
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask: 'Any', x: 'Any') -> 'tuple[list[Any], ...]'
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| __init__(self) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| mask_shapes(self, x: 'Any') -> 'list[tuple[int, ...]]'
| The shape of the masks we expect.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'clustering': 'npt.NDArray[Any]', 'shape': 'tuple[N...
|
| ----------------------------------------------------------------------
| Methods inherited from shap._serializable.Serializable:
|
| save(self, out_file)
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap._serializable.Serializable:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class FixedComposite(shap.maskers._masker.Masker)
| FixedComposite(masker)
|
| A masker that outputs both the masked data and the original data as a pair.
|
| Method resolution order:
| FixedComposite
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask, *args)
| Computes mask on the args using the masker data attribute and returns tuple containing masked input with args.
|
| __init__(self, masker)
| Creates a Composite masker from an underlying masker and returns the original args along with the masked output.
|
| Parameters
| ----------
| masker: object
| An object of the shap.maskers.Masker base class (eg. Text/Image masker).
|
| Returns
| -------
| tuple
| A tuple consisting of the masked input using the underlying masker appended with the original args in a list.
|
| save(self, out_file)
| Write a FixedComposite masker to a file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| Load a FixedComposite masker from a file stream.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Image(shap.maskers._masker.Masker)
| Image(mask_value, shape=None)
|
| Masks out image regions with blurring or inpainting.
|
| Method resolution order:
| Image
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask, x)
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| __init__(self, mask_value, shape=None)
| Build a new Image masker with the given masking value.
|
| Parameters
| ----------
| mask_value : np.array, "blur(kernel_xsize, kernel_xsize)", "inpaint_telea", or "inpaint_ns"
| The value used to mask hidden regions of the image.
| shape : None or tuple
| If the mask_value is an auto-generated masker instead of a dataset then the input
| image shape needs to be provided.
|
| build_partition_tree(self)
| This partitions an image into a hierarchical clustering based on axis-aligned splits.
|
| inpaint(self, x, mask, method)
| Fill in the masked parts of the image through inpainting.
|
| save(self, out_file)
| Write a Image masker to a file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| Load a Image masker from a file stream.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Impute(shap.maskers._masker.Masker)
| Impute(data, method='linear')
|
| This imputes the values of missing features using the values of the observed features.
|
| Unlike Independent, Gaussian imputes missing values based on correlations with observed data points.
|
| Method resolution order:
| Impute
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, data, method='linear')
| Build a Partition masker with the given background data and clustering.
|
| Parameters
| ----------
| data : numpy.ndarray, pandas.DataFrame or {"mean: numpy.ndarray, "cov": numpy.ndarray} dictionary
| The background dataset that is used for masking.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.maskers._masker.Masker:
|
| __call__(self, mask: 'bool | npt.NDArray[Any]', *args: 'Any') -> 'Any'
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| ----------------------------------------------------------------------
| Methods inherited from shap._serializable.Serializable:
|
| save(self, out_file)
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap._serializable.Serializable:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Independent(Tabular)
| Independent(data, max_samples=100)
|
| This masks out tabular features by integrating over the given background dataset.
|
| Method resolution order:
| Independent
| Tabular
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, data, max_samples=100)
| Build a Independent masker with the given background data.
|
| Parameters
| ----------
| data : numpy.ndarray, pandas.DataFrame
| The background dataset that is used for masking.
|
| max_samples : int
| The maximum number of samples to use from the passed background data. If data has more
| than max_samples then shap.utils.sample is used to subsample the dataset. The number of
| samples coming out of the masker (to be integrated over) matches the number of samples in
| the background dataset. This means larger background dataset cause longer runtimes. Normally
| about 1, 10, 100, or 1000 background samples are reasonable choices.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from Tabular:
|
| __call__(self, mask, x)
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| invariants(self, x)
| This returns a mask of which features change when we mask them.
|
| This optional masking method allows explainers to avoid re-evaluating the model when
| the features that would have been masked are all invariant.
|
| save(self, out_file)
| Write a Tabular masker to a file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from Tabular:
|
| load(in_file, instantiate=True)
| Load a Tabular masker from a file stream.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Masker(shap._serializable.Serializable)
| This is the superclass of all maskers.
|
| Method resolution order:
| Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask: 'bool | npt.NDArray[Any]', *args: 'Any') -> 'Any'
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'clustering': 'npt.NDArray[Any] | Callable[..., Any...
|
| ----------------------------------------------------------------------
| Methods inherited from shap._serializable.Serializable:
|
| save(self, out_file)
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap._serializable.Serializable:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class OutputComposite(shap.maskers._masker.Masker)
| OutputComposite(masker, model)
|
| A masker that is a combination of a masker and a model and outputs both masked args and the model's output.
|
| Method resolution order:
| OutputComposite
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask, *args)
| Mask the args using the masker and return a tuple containing the masked input and the model output on the args.
|
| __init__(self, masker, model)
| Creates a masker from an underlying masker and and model.
|
| This masker returns the masked input along with the model output for the passed args.
|
| Parameters
| ----------
| masker: object
| An object of the shap.maskers.Masker base class (eg. Text/Image masker).
|
| model: object
| An object shap.models.Model base class used to generate output.
|
| Returns
| -------
| tuple
| A tuple consisting of the masked input using the underlying masker appended with the model output for passed args.
|
| save(self, out_file)
| Write a OutputComposite masker to a file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| Load a OutputComposite masker from a file stream.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Partition(Tabular)
| Partition(data, max_samples=100, clustering='correlation')
|
| This masks out tabular features by integrating over the given background dataset.
|
| Unlike Independent, Partition respects a hierarchical structure of the data.
|
| Method resolution order:
| Partition
| Tabular
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, data, max_samples=100, clustering='correlation')
| Build a Partition masker with the given background data and clustering.
|
| Parameters
| ----------
| data : numpy.ndarray, pandas.DataFrame
| The background dataset that is used for masking.
|
| max_samples : int
| The maximum number of samples to use from the passed background data. If data has more
| than max_samples then shap.utils.sample is used to subsample the dataset. The number of
| samples coming out of the masker (to be integrated over) matches the number of samples in
| the background dataset. This means larger background dataset cause longer runtimes. Normally
| about 1, 10, 100, or 1000 background samples are reasonable choices.
|
| clustering : string or numpy.ndarray
| If a string, then this is the distance metric to use for creating the clustering of
| the features. The distance function can be any valid scipy.spatial.distance.pdist's metric
| argument. However we suggest using 'correlation' in most cases. The full list of options is
| `braycurtis`, `canberra`, `chebyshev`, `cityblock`, `correlation`, `cosine`, `dice`,
| `euclidean`, `hamming`, `jaccard`, `jensenshannon`, `kulsinski`, `mahalanobis`,
| `matching`, `minkowski`, `rogerstanimoto`, `russellrao`, `seuclidean`,
| `sokalmichener`, `sokalsneath`, `sqeuclidean`, `yule`. These are all
| the options from scipy.spatial.distance.pdist's metric argument.
| If an array, then this is assumed to be the clustering of the features.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from Tabular:
|
| __call__(self, mask, x)
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| invariants(self, x)
| This returns a mask of which features change when we mask them.
|
| This optional masking method allows explainers to avoid re-evaluating the model when
| the features that would have been masked are all invariant.
|
| save(self, out_file)
| Write a Tabular masker to a file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from Tabular:
|
| load(in_file, instantiate=True)
| Load a Tabular masker from a file stream.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Text(shap.maskers._masker.Masker)
| Text(tokenizer=None, mask_token=None, collapse_mask_token='auto', output_type='string')
|
| This masks out tokens according to the given tokenizer.
|
| The masked variables are
|
| output_type : "string" (default) or "token_ids"
|
| Method resolution order:
| Text
| shap.maskers._masker.Masker
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, mask, s)
| Maskers are callable objects that accept the same inputs as the model plus a binary mask.
|
| __init__(self, tokenizer=None, mask_token=None, collapse_mask_token='auto', output_type='string')
| Build a new Text masker given an optional passed tokenizer.
|
| Parameters
| ----------
| tokenizer : callable or None
| The tokenizer used to break apart strings during masking. The passed tokenizer must support a minimal
| subset of the HuggingFace Transformers PreTrainedTokenizerBase API. This minimal subset means the
| tokenizer must return a dictionary with 'input_ids' and then either include
| an 'offset_mapping' entry in the same dictionary or provide a .convert_ids_to_tokens or .decode method.
|
| mask_token : string, int, or None
| The sub-string or integer token id used to mask out portions of a string. If None it will use the
| tokenizer's .mask_token attribute, if defined, or "..." if the tokenizer does not have a .mask_token
| attribute.
|
| collapse_mask_token : True, False, or "auto"
| If True, when several consecutive tokens are masked only one mask token is used to replace the entire
| series of original tokens.
|
| clustering(self, s)
| Compute the clustering of tokens for the given string.
|
| data_transform(self, s)
| Called by explainers to allow us to convert data to better match masking (here this means tokenizing).
|
| feature_names(self, s)
| The names of the features for each mask position for the given input string.
|
| invariants(self, s)
| The names of the features for each mask position for the given input string.
|
| mask_shapes(self, s)
| The shape of the masks we expect.
|
| save(self, out_file)
| Save a Text masker to a file stream.
|
| shape(self, s)
| The shape of what we return as a masker.
|
| Note we only return a single sample, so there is no expectation averaging.
|
| token_segments(self, s)
| Returns the substrings associated with each token in the given string.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| Load a Text masker from a file stream.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['Composite', 'Fixed', 'FixedComposite', 'Image', 'Masker', ...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\maskers\__init__.py
shap.matplotlib
Python Library Documentation: package matplotlib
NAME
matplotlib - An object-oriented plotting library.
DESCRIPTION
A procedural interface is provided by the companion pyplot module,
which may be imported directly, e.g.::
import matplotlib.pyplot as plt
or using ipython::
ipython
at your terminal, followed by::
In [1]: %matplotlib
In [2]: import matplotlib.pyplot as plt
at the ipython shell prompt.
For the most part, direct use of the explicit object-oriented library is
encouraged when programming; the implicit pyplot interface is primarily for
working interactively. The exceptions to this suggestion are the pyplot
functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and
`.pyplot.savefig`, which can greatly simplify scripting. See
:ref:`api_interfaces` for an explanation of the tradeoffs between the implicit
and explicit interfaces.
Modules include:
:mod:`matplotlib.axes`
The `~.axes.Axes` class. Most pyplot functions are wrappers for
`~.axes.Axes` methods. The axes module is the highest level of OO
access to the library.
:mod:`matplotlib.figure`
The `.Figure` class.
:mod:`matplotlib.artist`
The `.Artist` base class for all classes that draw things.
:mod:`matplotlib.lines`
The `.Line2D` class for drawing lines and markers.
:mod:`matplotlib.patches`
Classes for drawing polygons.
:mod:`matplotlib.text`
The `.Text` and `.Annotation` classes.
:mod:`matplotlib.image`
The `.AxesImage` and `.FigureImage` classes.
:mod:`matplotlib.collections`
Classes for efficient drawing of groups of lines or polygons.
:mod:`matplotlib.colors`
Color specifications and making colormaps.
:mod:`matplotlib.cm`
Colormaps, and the `.ScalarMappable` mixin class for providing color
mapping functionality to other classes.
:mod:`matplotlib.ticker`
Calculation of tick mark locations and formatting of tick labels.
:mod:`matplotlib.backends`
A subpackage with modules for various GUI libraries and output formats.
The base matplotlib namespace includes:
`~matplotlib.rcParams`
Default configuration settings; their defaults may be overridden using
a :file:`matplotlibrc` file.
`~matplotlib.use`
Setting the Matplotlib backend. This should be called before any
figure is created, because it is not possible to switch between
different GUI backends after that.
The following environment variables can be used to customize the behavior:
:envvar:`MPLBACKEND`
This optional variable can be set to choose the Matplotlib backend. See
:ref:`what-is-a-backend`.
:envvar:`MPLCONFIGDIR`
This is the directory used to store user customizations to
Matplotlib, as well as some caches to improve performance. If
:envvar:`MPLCONFIGDIR` is not defined, :file:`{HOME}/.config/matplotlib`
and :file:`{HOME}/.cache/matplotlib` are used on Linux, and
:file:`{HOME}/.matplotlib` on other platforms, if they are
writable. Otherwise, the Python standard library's `tempfile.gettempdir`
is used to find a base directory in which the :file:`matplotlib`
subdirectory is created.
Matplotlib was initially written by John D. Hunter (1968-2012) and is now
developed and maintained by a host of others.
Occasionally the internal documentation (python docstrings) will refer
to MATLAB®, a registered trademark of The MathWorks, Inc.
PACKAGE CONTENTS
_afm
_animation_data
_api (package)
_blocking_input
_c_internal_utils
_cm
_cm_listed
_color_data
_constrained_layout
_docstring
_enums
_fontconfig_pattern
_image
_internal_utils
_layoutgrid
_mathtext
_mathtext_data
_path
_pylab_helpers
_qhull
_text_helpers
_tight_bbox
_tight_layout
_tri
_ttconv
_type1font
_version
animation
artist
axes (package)
axis
backend_bases
backend_managers
backend_tools
backends (package)
bezier
category
cbook
cm
collections
colorbar
colors
container
contour
dates
dviread
figure
font_manager
ft2font
gridspec
hatch
image
layout_engine
legend
legend_handler
lines
markers
mathtext
mlab
offsetbox
patches
path
patheffects
projections (package)
pylab
pyplot
quiver
rcsetup
sankey
scale
sphinxext (package)
spines
stackplot
streamplot
style (package)
table
testing (package)
tests (package)
texmanager
text
textpath
ticker
transforms
tri (package)
typing
units
widgets
CLASSES
builtins.DeprecationWarning(builtins.Warning)
matplotlib._api.deprecation.MatplotlibDeprecationWarning
builtins.FileNotFoundError(builtins.OSError)
ExecutableNotFoundError
builtins.dict(builtins.object)
RcParams(collections.abc.MutableMapping, builtins.dict)
collections.abc.MutableMapping(collections.abc.Mapping)
RcParams(collections.abc.MutableMapping, builtins.dict)
class ExecutableNotFoundError(builtins.FileNotFoundError)
| Error raised when an executable that Matplotlib optionally
| depends on can't be found.
|
| Method resolution order:
| ExecutableNotFoundError
| builtins.FileNotFoundError
| builtins.OSError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.FileNotFoundError:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.OSError:
|
| __reduce__(...)
| Helper for pickle.
|
| __str__(self, /)
| Return str(self).
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.OSError:
|
| __new__(*args, **kwargs) class method of builtins.OSError
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.OSError:
|
| characters_written
|
| errno
| POSIX exception code
|
| filename
| exception filename
|
| filename2
| second exception filename
|
| strerror
| exception strerror
|
| winerror
| Win32 exception code
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class MatplotlibDeprecationWarning(builtins.DeprecationWarning)
| A class for issuing deprecation warnings for Matplotlib users.
|
| Method resolution order:
| MatplotlibDeprecationWarning
| builtins.DeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.DeprecationWarning:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.DeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.DeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class RcParams(collections.abc.MutableMapping, builtins.dict)
| RcParams(*args, **kwargs)
|
| A dict-like key-value store for config parameters, including validation.
|
| Validating functions are defined and associated with rc parameters in
| :mod:`matplotlib.rcsetup`.
|
| The list of rcParams is:
|
| - _internal.classic_mode
| - agg.path.chunksize
| - animation.bitrate
| - animation.codec
| - animation.convert_args
| - animation.convert_path
| - animation.embed_limit
| - animation.ffmpeg_args
| - animation.ffmpeg_path
| - animation.frame_format
| - animation.html
| - animation.writer
| - axes.autolimit_mode
| - axes.axisbelow
| - axes.edgecolor
| - axes.facecolor
| - axes.formatter.limits
| - axes.formatter.min_exponent
| - axes.formatter.offset_threshold
| - axes.formatter.use_locale
| - axes.formatter.use_mathtext
| - axes.formatter.useoffset
| - axes.grid
| - axes.grid.axis
| - axes.grid.which
| - axes.labelcolor
| - axes.labelpad
| - axes.labelsize
| - axes.labelweight
| - axes.linewidth
| - axes.prop_cycle
| - axes.spines.bottom
| - axes.spines.left
| - axes.spines.right
| - axes.spines.top
| - axes.titlecolor
| - axes.titlelocation
| - axes.titlepad
| - axes.titlesize
| - axes.titleweight
| - axes.titley
| - axes.unicode_minus
| - axes.xmargin
| - axes.ymargin
| - axes.zmargin
| - axes3d.automargin
| - axes3d.grid
| - axes3d.xaxis.panecolor
| - axes3d.yaxis.panecolor
| - axes3d.zaxis.panecolor
| - backend
| - backend_fallback
| - boxplot.bootstrap
| - boxplot.boxprops.color
| - boxplot.boxprops.linestyle
| - boxplot.boxprops.linewidth
| - boxplot.capprops.color
| - boxplot.capprops.linestyle
| - boxplot.capprops.linewidth
| - boxplot.flierprops.color
| - boxplot.flierprops.linestyle
| - boxplot.flierprops.linewidth
| - boxplot.flierprops.marker
| - boxplot.flierprops.markeredgecolor
| - boxplot.flierprops.markeredgewidth
| - boxplot.flierprops.markerfacecolor
| - boxplot.flierprops.markersize
| - boxplot.meanline
| - boxplot.meanprops.color
| - boxplot.meanprops.linestyle
| - boxplot.meanprops.linewidth
| - boxplot.meanprops.marker
| - boxplot.meanprops.markeredgecolor
| - boxplot.meanprops.markerfacecolor
| - boxplot.meanprops.markersize
| - boxplot.medianprops.color
| - boxplot.medianprops.linestyle
| - boxplot.medianprops.linewidth
| - boxplot.notch
| - boxplot.patchartist
| - boxplot.showbox
| - boxplot.showcaps
| - boxplot.showfliers
| - boxplot.showmeans
| - boxplot.vertical
| - boxplot.whiskerprops.color
| - boxplot.whiskerprops.linestyle
| - boxplot.whiskerprops.linewidth
| - boxplot.whiskers
| - contour.algorithm
| - contour.corner_mask
| - contour.linewidth
| - contour.negative_linestyle
| - date.autoformatter.day
| - date.autoformatter.hour
| - date.autoformatter.microsecond
| - date.autoformatter.minute
| - date.autoformatter.month
| - date.autoformatter.second
| - date.autoformatter.year
| - date.converter
| - date.epoch
| - date.interval_multiples
| - docstring.hardcopy
| - errorbar.capsize
| - figure.autolayout
| - figure.constrained_layout.h_pad
| - figure.constrained_layout.hspace
| - figure.constrained_layout.use
| - figure.constrained_layout.w_pad
| - figure.constrained_layout.wspace
| - figure.dpi
| - figure.edgecolor
| - figure.facecolor
| - figure.figsize
| - figure.frameon
| - figure.hooks
| - figure.labelsize
| - figure.labelweight
| - figure.max_open_warning
| - figure.raise_window
| - figure.subplot.bottom
| - figure.subplot.hspace
| - figure.subplot.left
| - figure.subplot.right
| - figure.subplot.top
| - figure.subplot.wspace
| - figure.titlesize
| - figure.titleweight
| - font.cursive
| - font.family
| - font.fantasy
| - font.monospace
| - font.sans-serif
| - font.serif
| - font.size
| - font.stretch
| - font.style
| - font.variant
| - font.weight
| - grid.alpha
| - grid.color
| - grid.linestyle
| - grid.linewidth
| - hatch.color
| - hatch.linewidth
| - hist.bins
| - image.aspect
| - image.cmap
| - image.composite_image
| - image.interpolation
| - image.interpolation_stage
| - image.lut
| - image.origin
| - image.resample
| - interactive
| - keymap.back
| - keymap.copy
| - keymap.forward
| - keymap.fullscreen
| - keymap.grid
| - keymap.grid_minor
| - keymap.help
| - keymap.home
| - keymap.pan
| - keymap.quit
| - keymap.quit_all
| - keymap.save
| - keymap.xscale
| - keymap.yscale
| - keymap.zoom
| - legend.borderaxespad
| - legend.borderpad
| - legend.columnspacing
| - legend.edgecolor
| - legend.facecolor
| - legend.fancybox
| - legend.fontsize
| - legend.framealpha
| - legend.frameon
| - legend.handleheight
| - legend.handlelength
| - legend.handletextpad
| - legend.labelcolor
| - legend.labelspacing
| - legend.loc
| - legend.markerscale
| - legend.numpoints
| - legend.scatterpoints
| - legend.shadow
| - legend.title_fontsize
| - lines.antialiased
| - lines.color
| - lines.dash_capstyle
| - lines.dash_joinstyle
| - lines.dashdot_pattern
| - lines.dashed_pattern
| - lines.dotted_pattern
| - lines.linestyle
| - lines.linewidth
| - lines.marker
| - lines.markeredgecolor
| - lines.markeredgewidth
| - lines.markerfacecolor
| - lines.markersize
| - lines.scale_dashes
| - lines.solid_capstyle
| - lines.solid_joinstyle
| - macosx.window_mode
| - markers.fillstyle
| - mathtext.bf
| - mathtext.bfit
| - mathtext.cal
| - mathtext.default
| - mathtext.fallback
| - mathtext.fontset
| - mathtext.it
| - mathtext.rm
| - mathtext.sf
| - mathtext.tt
| - patch.antialiased
| - patch.edgecolor
| - patch.facecolor
| - patch.force_edgecolor
| - patch.linewidth
| - path.effects
| - path.simplify
| - path.simplify_threshold
| - path.sketch
| - path.snap
| - pcolor.shading
| - pcolormesh.snap
| - pdf.compression
| - pdf.fonttype
| - pdf.inheritcolor
| - pdf.use14corefonts
| - pgf.preamble
| - pgf.rcfonts
| - pgf.texsystem
| - polaraxes.grid
| - ps.distiller.res
| - ps.fonttype
| - ps.papersize
| - ps.useafm
| - ps.usedistiller
| - savefig.bbox
| - savefig.directory
| - savefig.dpi
| - savefig.edgecolor
| - savefig.facecolor
| - savefig.format
| - savefig.orientation
| - savefig.pad_inches
| - savefig.transparent
| - scatter.edgecolors
| - scatter.marker
| - svg.fonttype
| - svg.hashsalt
| - svg.image_inline
| - text.antialiased
| - text.color
| - text.hinting
| - text.hinting_factor
| - text.kerning_factor
| - text.latex.preamble
| - text.parse_math
| - text.usetex
| - timezone
| - tk.window_focus
| - toolbar
| - webagg.address
| - webagg.open_in_browser
| - webagg.port
| - webagg.port_retries
| - xaxis.labellocation
| - xtick.alignment
| - xtick.bottom
| - xtick.color
| - xtick.direction
| - xtick.labelbottom
| - xtick.labelcolor
| - xtick.labelsize
| - xtick.labeltop
| - xtick.major.bottom
| - xtick.major.pad
| - xtick.major.size
| - xtick.major.top
| - xtick.major.width
| - xtick.minor.bottom
| - xtick.minor.ndivs
| - xtick.minor.pad
| - xtick.minor.size
| - xtick.minor.top
| - xtick.minor.visible
| - xtick.minor.width
| - xtick.top
| - yaxis.labellocation
| - ytick.alignment
| - ytick.color
| - ytick.direction
| - ytick.labelcolor
| - ytick.labelleft
| - ytick.labelright
| - ytick.labelsize
| - ytick.left
| - ytick.major.left
| - ytick.major.pad
| - ytick.major.right
| - ytick.major.size
| - ytick.major.width
| - ytick.minor.left
| - ytick.minor.ndivs
| - ytick.minor.pad
| - ytick.minor.right
| - ytick.minor.size
| - ytick.minor.visible
| - ytick.minor.width
| - ytick.right
|
| See Also
| --------
| :ref:`customizing-with-matplotlibrc-files`
|
| Method resolution order:
| RcParams
| collections.abc.MutableMapping
| collections.abc.Mapping
| collections.abc.Collection
| collections.abc.Sized
| collections.abc.Iterable
| collections.abc.Container
| builtins.dict
| builtins.object
|
| Methods defined here:
|
| __getitem__(self, key)
| Return self[key].
|
| __init__(self, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self)
| Yield sorted list of keys.
|
| __len__(self)
| Return len(self).
|
| __repr__(self)
| Return repr(self).
|
| __setitem__(self, key, val)
| Set self[key] to value.
|
| __str__(self)
| Return str(self).
|
| copy(self)
| Copy this RcParams instance.
|
| find_all(self, pattern)
| Return the subset of this RcParams dictionary whose keys match,
| using :func:`re.search`, the given ``pattern``.
|
| .. note::
|
| Changes to the returned dictionary are *not* propagated to
| the parent RcParams dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'__delitem__'})
|
| validate = {'_internal.classic_mode': <function validate_bool>, 'agg.p...
|
| ----------------------------------------------------------------------
| Methods inherited from collections.abc.MutableMapping:
|
| __delitem__(self, key)
|
| clear(self)
| D.clear() -> None. Remove all items from D.
|
| pop(self, key, default=<object object at 0x00000213D62C81F0>)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
| If key is not found, d is returned if given, otherwise KeyError is raised.
|
| popitem(self)
| D.popitem() -> (k, v), remove and return some (key, value) pair
| as a 2-tuple; but raise KeyError if D is empty.
|
| setdefault(self, key, default=None)
| D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D
|
| update(self, other=(), /, **kwds)
| D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.
| If E present and has a .keys() method, does: for k in E: D[k] = E[k]
| If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v
| In either case, this is followed by: for k, v in F.items(): D[k] = v
|
| ----------------------------------------------------------------------
| Methods inherited from collections.abc.Mapping:
|
| __contains__(self, key)
|
| __eq__(self, other)
| Return self==value.
|
| get(self, key, default=None)
| D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.
|
| items(self)
| D.items() -> a set-like object providing a view on D's items
|
| keys(self)
| D.keys() -> a set-like object providing a view on D's keys
|
| values(self)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from collections.abc.Mapping:
|
| __hash__ = None
|
| __reversed__ = None
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Collection:
|
| __subclasshook__(C)
| Abstract classes can override this to customize issubclass().
|
| This is invoked early on by abc.ABCMeta.__subclasscheck__().
| It should return True, False or NotImplemented. If it returns
| NotImplemented, the normal algorithm is used. Otherwise, it
| overrides the normal algorithm (and the outcome is cached).
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Iterable:
|
| __class_getitem__ = GenericAlias(...)
| Represent a PEP 585 generic type
|
| E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __gt__(self, value, /)
| Return self>value.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __le__(self, value, /)
| Return self<=value.
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __ror__(self, value, /)
| Return value|self.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
FUNCTIONS
__getattr__(name)
get_backend()
Return the name of the current backend.
See Also
--------
matplotlib.use
get_cachedir()
Return the string path of the cache directory.
The procedure used to find the directory is the same as for
`get_configdir`, except using ``$XDG_CACHE_HOME``/``$HOME/.cache`` instead.
get_configdir()
Return the string path of the configuration directory.
The directory is chosen as follows:
1. If the MPLCONFIGDIR environment variable is supplied, choose that.
2. On Linux, follow the XDG specification and look first in
``$XDG_CONFIG_HOME``, if defined, or ``$HOME/.config``. On other
platforms, choose ``$HOME/.matplotlib``.
3. If the chosen directory exists and is writable, use that as the
configuration directory.
4. Else, create a temporary directory, and use it as the configuration
directory.
get_data_path()
Return the path to Matplotlib data.
interactive(b)
Set whether to redraw after every plotting command (e.g. `.pyplot.xlabel`).
is_interactive()
Return whether to redraw after every plotting command.
.. note::
This function is only intended for use in backends. End users should
use `.pyplot.isinteractive` instead.
matplotlib_fname()
Get the location of the config file.
The file location is determined in the following order
- ``$PWD/matplotlibrc``
- ``$MATPLOTLIBRC`` if it is not a directory
- ``$MATPLOTLIBRC/matplotlibrc``
- ``$MPLCONFIGDIR/matplotlibrc``
- On Linux,
- ``$XDG_CONFIG_HOME/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME``
is defined)
- or ``$HOME/.config/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME``
is not defined)
- On other platforms,
- ``$HOME/.matplotlib/matplotlibrc`` if ``$HOME`` is defined
- Lastly, it looks in ``$MATPLOTLIBDATA/matplotlibrc``, which should always
exist.
rc(group, **kwargs)
Set the current `.rcParams`. *group* is the grouping for the rc, e.g.,
for ``lines.linewidth`` the group is ``lines``, for
``axes.facecolor``, the group is ``axes``, and so on. Group may
also be a list or tuple of group names, e.g., (*xtick*, *ytick*).
*kwargs* is a dictionary attribute name/value pairs, e.g.,::
rc('lines', linewidth=2, color='r')
sets the current `.rcParams` and is equivalent to::
rcParams['lines.linewidth'] = 2
rcParams['lines.color'] = 'r'
The following aliases are available to save typing for interactive users:
===== =================
Alias Property
===== =================
'lw' 'linewidth'
'ls' 'linestyle'
'c' 'color'
'fc' 'facecolor'
'ec' 'edgecolor'
'mew' 'markeredgewidth'
'aa' 'antialiased'
===== =================
Thus you could abbreviate the above call as::
rc('lines', lw=2, c='r')
Note you can use python's kwargs dictionary facility to store
dictionaries of default parameters. e.g., you can customize the
font rc as follows::
font = {'family' : 'monospace',
'weight' : 'bold',
'size' : 'larger'}
rc('font', **font) # pass in the font dict as kwargs
This enables you to easily switch between several configurations. Use
``matplotlib.style.use('default')`` or :func:`~matplotlib.rcdefaults` to
restore the default `.rcParams` after changes.
Notes
-----
Similar functionality is available by using the normal dict interface, i.e.
``rcParams.update({"lines.linewidth": 2, ...})`` (but ``rcParams.update``
does not support abbreviations or grouping).
rc_context(rc=None, fname=None)
Return a context manager for temporarily changing rcParams.
The :rc:`backend` will not be reset by the context manager.
rcParams changed both through the context manager invocation and
in the body of the context will be reset on context exit.
Parameters
----------
rc : dict
The rcParams to temporarily set.
fname : str or path-like
A file with Matplotlib rc settings. If both *fname* and *rc* are given,
settings from *rc* take precedence.
See Also
--------
:ref:`customizing-with-matplotlibrc-files`
Examples
--------
Passing explicit values via a dict::
with mpl.rc_context({'interactive': False}):
fig, ax = plt.subplots()
ax.plot(range(3), range(3))
fig.savefig('example.png')
plt.close(fig)
Loading settings from a file::
with mpl.rc_context(fname='print.rc'):
plt.plot(x, y) # uses 'print.rc'
Setting in the context body::
with mpl.rc_context():
# will be reset
mpl.rcParams['lines.linewidth'] = 5
plt.plot(x, y)
rc_file(fname, *, use_default_template=True)
Update `.rcParams` from file.
Style-blacklisted `.rcParams` (defined in
``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
Parameters
----------
fname : str or path-like
A file with Matplotlib rc settings.
use_default_template : bool
If True, initialize with default parameters before updating with those
in the given file. If False, the current configuration persists
and only the parameters specified in the file are updated.
rc_file_defaults()
Restore the `.rcParams` from the original rc file loaded by Matplotlib.
Style-blacklisted `.rcParams` (defined in
``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
rc_params(fail_on_error=False)
Construct a `RcParams` instance from the default Matplotlib rc file.
rc_params_from_file(fname, fail_on_error=False, use_default_template=True)
Construct a `RcParams` from file *fname*.
Parameters
----------
fname : str or path-like
A file with Matplotlib rc settings.
fail_on_error : bool
If True, raise an error when the parser fails to convert a parameter.
use_default_template : bool
If True, initialize with default parameters before updating with those
in the given file. If False, the configuration class only contains the
parameters specified in the file. (Useful for updating dicts.)
rcdefaults()
Restore the `.rcParams` from Matplotlib's internal default style.
Style-blacklisted `.rcParams` (defined in
``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
See Also
--------
matplotlib.rc_file_defaults
Restore the `.rcParams` from the rc file originally loaded by
Matplotlib.
matplotlib.style.use
Use a specific style file. Call ``style.use('default')`` to restore
the default style.
set_loglevel(level)
Configure Matplotlib's logging levels.
Matplotlib uses the standard library `logging` framework under the root
logger 'matplotlib'. This is a helper function to:
- set Matplotlib's root logger level
- set the root logger handler's level, creating the handler
if it does not exist yet
Typically, one should call ``set_loglevel("info")`` or
``set_loglevel("debug")`` to get additional debugging information.
Users or applications that are installing their own logging handlers
may want to directly manipulate ``logging.getLogger('matplotlib')`` rather
than use this function.
Parameters
----------
level : {"notset", "debug", "info", "warning", "error", "critical"}
The log level of the handler.
Notes
-----
The first time this function is called, an additional handler is attached
to Matplotlib's root handler; this handler is reused every time and this
function simply manipulates the logger and handler's level.
use(backend, *, force=True)
Select the backend used for rendering and GUI integration.
If pyplot is already imported, `~matplotlib.pyplot.switch_backend` is used
and if the new backend is different than the current backend, all Figures
will be closed.
Parameters
----------
backend : str
The backend to switch to. This can either be one of the standard
backend names, which are case-insensitive:
- interactive backends:
GTK3Agg, GTK3Cairo, GTK4Agg, GTK4Cairo, MacOSX, nbAgg, notebook, QtAgg,
QtCairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo, Qt5Agg, Qt5Cairo
- non-interactive backends:
agg, cairo, pdf, pgf, ps, svg, template
or a string of the form: ``module://my.module.name``.
notebook is a synonym for nbAgg.
Switching to an interactive backend is not possible if an unrelated
event loop has already been started (e.g., switching to GTK3Agg if a
TkAgg window has already been opened). Switching to a non-interactive
backend is always possible.
force : bool, default: True
If True (the default), raise an `ImportError` if the backend cannot be
set up (either because it fails to import, or because an incompatible
GUI interactive framework is already running); if False, silently
ignore the failure.
See Also
--------
:ref:`backends`
matplotlib.get_backend
matplotlib.pyplot.switch_backend
DATA
__all__ = ['__bibtex__', '__version__', '__version_info__', 'set_logle...
__bibtex__ = '@Article{Hunter:2007,\n Author = {Hunter, J. ...ishe...
color_sequences = <matplotlib.colors.ColorSequenceRegistry object>
colormaps = <matplotlib.cm.ColormapRegistry object>
defaultParams = {'_internal.classic_mode': [False, <function validate_...
rcParams = RcParams({'_internal.classic_mode': False,
...nor.widt...
rcParamsDefault = RcParams({'_internal.classic_mode': False,
...n...
rcParamsOrig = RcParams({'_internal.classic_mode': False,
...nor....
VERSION
3.9.2
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\matplotlib\__init__.py
shap.models
Python Library Documentation: package shap.models in shap
NAME
shap.models
PACKAGE CONTENTS
_model
_teacher_forcing
_text_generation
_topk_lm
_transformers_pipeline
CLASSES
shap._serializable.Serializable(builtins.object)
shap.models._model.Model
shap.models._teacher_forcing.TeacherForcing
shap.models._text_generation.TextGeneration
shap.models._topk_lm.TopKLM
shap.models._transformers_pipeline.TransformersPipeline
class Model(shap._serializable.Serializable)
| Model(model: 'Any' = None) -> 'None'
|
| This is the superclass of all models.
|
| Method resolution order:
| Model
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, *args: 'Any') -> 'npt.NDArray[Any]'
| Call self as a function.
|
| __init__(self, model: 'Any' = None) -> 'None'
| Wrap a callable model as a SHAP Model object.
|
| save(self, out_file: 'BinaryIO') -> 'None'
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file: 'BinaryIO', instantiate: 'bool' = True) -> 'Model | dict[str, Any]'
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TeacherForcing(shap.models._model.Model)
| TeacherForcing(model, tokenizer=None, similarity_model=None, similarity_tokenizer=None, batch_size=128, device=None)
|
| Generates scores (log odds) for output text explanation algorithms using Teacher Forcing technique.
|
| This class supports generation of log odds for transformer models as well as functions. In model agnostic
| cases (model is function) it expects a similarity_model and similarity_tokenizer to approximate log odd scores
| for target sentence generated by the model.
|
| Method resolution order:
| TeacherForcing
| shap.models._model.Model
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X, Y)
| Computes log odds scores of generating output(text) for a given batch of input(text/image) .
|
| Parameters
| ----------
| X: numpy.ndarray
| An array containing a list of masked inputs.
|
| Y: numpy.ndarray
| An array containing a list of target sentence/ids.
|
| Returns
| -------
| numpy.ndarray
| A numpy array of log odds scores for every input pair (masked_X, X)
|
| __init__(self, model, tokenizer=None, similarity_model=None, similarity_tokenizer=None, batch_size=128, device=None)
| Build a teacher forcing model from the given text generation model.
|
| Parameters
| ----------
| model: object or function
| A object of any pretrained transformer model or function which is to be explained.
|
| tokenizer: object
| A tokenizer object(PreTrainedTokenizer/PreTrainedTokenizerFast) which is used to tokenize source and target sentence.
|
| similarity_model: object
| A pretrained transformer model object which is used in model agnostic scenario to approximate log odds.
|
| similarity_tokenizer: object
| A tokenizer object(PreTrainedTokenizer/PreTrainedTokenizerFast) which is used to tokenize sentence in model agnostic scenario.
|
| batch_size: int
| Batch size for model inferencing and computing logodds (default=128).
|
| device: str
| By default, it infers if system has a gpu and accordingly sets device. Should be 'cpu' or 'cuda' or pytorch models.
|
| Returns
| -------
| numpy.ndarray
| The scores (log odds) of generating target sentence ids using the model.
|
| get_inputs(self, X, padding_side='right')
| The function tokenizes source sentences.
|
| In model agnostic case, the function calls model(X) which is expected to
| return a batch of output sentences which is tokenized to compute inputs.
|
| Parameters
| ----------
| X: numpy.ndarray
| X could be a batch of text or images(model agnostic case).
|
| Returns
| -------
| dict
| Dictionary of padded source sentence ids and attention mask as tensors("pt" or "tf" based on similarity_model_type).
|
| get_logodds(self, logits)
| Calculates log odds from logits.
|
| This function passes the logits through softmax and then computes log odds for the output(target sentence) ids.
|
| Parameters
| ----------
| logits: numpy.ndarray
| An array of logits generated from the model.
|
| Returns
| -------
| numpy.ndarray
| Computes log odds for corresponding output ids.
|
| get_output_names(self, output)
| Gets the output tokens by computing the output sentence ids and output names using the similarity_tokenizer.
|
| Parameters
| ----------
| output: numpy.ndarray
| Output(sentence/sentence ids) for an explanation row.
|
| Returns
| -------
| list
| A list of output tokens.
|
| get_outputs(self, X)
| The function tokenizes output sentences and returns ids.
|
| Parameters
| ----------
| X: numpy.ndarray
| Output(sentence/sentence ids) for an explanation row.
|
| Returns
| -------
| numpy.ndarray
| An array of output(target sentence) ids.
|
| get_teacher_forced_logits(self, X, Y)
| The function generates logits for transformer models.
|
| It generates logits for encoder-decoder models as well as decoder only models by using the teacher forcing technique.
|
| Parameters
| ----------
| X: numpy.ndarray
| An array containing a list of masked inputs.
|
| Y: numpy.ndarray
| An array containing a list of target sentence/ids.
|
| Returns
| -------
| numpy.ndarray
| Decoder output logits for output(target sentence) ids.
|
| model_inference(self, inputs, output_ids)
| This function performs model inference for tensorflow and pytorch models.
|
| Parameters
| ----------
| inputs: dict
| Dictionary of padded source sentence ids and attention mask as tensors.
|
| output_ids: numpy.ndarray
| An array of decoder output ids.
|
| Returns
| -------
| numpy.ndarray
| Returns output logits from the model.
|
| save(self, out_file)
| Save the model to the given file stream.
|
| update_output_names(self, output: 'np.ndarray')
| The function updates output tokens.
|
| It mimics the caching mechanism to update the output tokens for every
| new row of explanation that are to be explained.
|
| Parameters
| ----------
| output: numpy.ndarray
| Output(sentence/sentence ids) for an explanation row.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TextGeneration(shap.models._model.Model)
| TextGeneration(model=None, tokenizer=None, target_sentences=None, device=None)
|
| Generates target sentence/ids using a base model.
|
| It generates target sentence/ids for a model (a pretrained transformer model or a function).
|
| Method resolution order:
| TextGeneration
| shap.models._model.Model
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, X)
| Generates target sentence/ids from X.
|
| Parameters
| ----------
| X: str or numpy.ndarray
| Input in the form of text or image.
|
| Returns
| -------
| numpy.ndarray
| Array of target sentence/ids.
|
| __init__(self, model=None, tokenizer=None, target_sentences=None, device=None)
| Create a text generator model from a pretrained transformer model or a function.
|
| For a pretrained transformer model, a tokenizer should be passed.
|
| Parameters
| ----------
| model: object or function
| A object of any pretrained transformer model or function for which target sentence/ids are to be generated.
|
| tokenizer: object
| A tokenizer object(PreTrainedTokenizer/PreTrainedTokenizerFast) which is used to tokenize sentence.
|
| target_sentences: list
| A target sentence for every explanation row.
|
| device: str
| By default, it infers if system has a gpu and accordingly sets device. Should be 'cpu' or 'cuda' or pytorch models.
|
| Returns
| -------
| numpy.ndarray
| Array of target sentence/ids.
|
| get_inputs(self, X, padding_side='right')
| The function tokenizes source sentences.
|
| In model agnostic case, the function calls model(X) which is expected to
| return a batch of output sentences which is tokenized to compute inputs.
|
| Parameters
| ----------
| X: numpy.ndarray
| X is a batch of sentences.
|
| Returns
| -------
| dict
| Dictionary of padded source sentence ids and attention mask as tensors("pt" or "tf" based on model_type).
|
| model_generate(self, X)
| This function performs text generation for tensorflow and pytorch models.
|
| Parameters
| ----------
| X: dict
| Dictionary of padded source sentence ids and attention mask as tensors.
|
| Returns
| -------
| numpy.ndarray
| Returns target sentence ids.
|
| parse_prefix_suffix_for_model_generate_output(self, output)
| Calculates if special tokens are present in the beginning/end of the model generated output.
|
| Parameters
| ----------
| output: list
| A list of output token ids.
|
| Returns
| -------
| dict
| Dictionary of prefix and suffix lengths concerning special tokens in output ids.
|
| save(self, out_file)
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TopKLM(shap.models._model.Model)
| TopKLM(model, tokenizer, k=10, generate_topk_token_ids=None, batch_size=128, device=None)
|
| Generates scores (log odds) for the top-k tokens for Causal/Masked LM.
|
| Method resolution order:
| TopKLM
| shap.models._model.Model
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, masked_X, X)
| Computes log odds scores for a given batch of masked inputs for the top-k tokens for Causal/Masked LM.
|
| Parameters
| ----------
| masked_X: numpy.ndarray
| An array containing a list of masked inputs.
|
| X: numpy.ndarray
| An array containing a list of original inputs
|
| Returns
| -------
| numpy.ndarray
| A numpy array of log odds scores for top-k tokens for every input pair (masked_X, X)
|
| __init__(self, model, tokenizer, k=10, generate_topk_token_ids=None, batch_size=128, device=None)
| Take Causal/Masked LM model and tokenizer and build a log odds output model for the top-k tokens.
|
| Parameters
| ----------
| model: object or function
| A object of any pretrained transformer model which is to be explained.
|
| tokenizer: object
| A tokenizer object(PreTrainedTokenizer/PreTrainedTokenizerFast).
|
| generation_function_for_topk_token_ids: function
| A function which is used to generate top-k token ids. Log odds will be generated for these custom token ids.
|
| batch_size: int
| Batch size for model inferencing and computing logodds (default=128).
|
| device: str
| By default, it infers if system has a gpu and accordingly sets device. Should be 'cpu' or 'cuda' or pytorch models.
|
| Returns
| -------
| numpy.ndarray
| The scores (log odds) of generating top-k token ids using the model.
|
| generate_topk_token_ids(self, X) -> numpy.ndarray
| Generates top-k token ids for Causal/Masked LM.
|
| Parameters
| ----------
| X: numpy.ndarray
| X is the original input sentence for an explanation row.
|
| Returns
| -------
| np.ndarray
| An array of top-k token ids.
|
| get_inputs(self, X, padding_side='right')
| The function tokenizes source sentence.
|
| Parameters
| ----------
| X: numpy.ndarray
| X is a batch of text.
|
| Returns
| -------
| dict
| Dictionary of padded source sentence ids and attention mask as tensors("pt" or "tf" based on similarity_model_type).
|
| get_lm_logits(self, X)
| Evaluates a Causal/Masked LM model and returns logits corresponding to next word/masked word.
|
| Parameters
| ----------
| X: numpy.ndarray
| An array containing a list of masked inputs.
|
| Returns
| -------
| numpy.ndarray
| Logits corresponding to next word/masked word.
|
| get_logodds(self, logits)
| Calculates log odds from logits.
|
| This function passes the logits through softmax and then computes log odds for the top-k token ids.
|
| Parameters
| ----------
| logits: numpy.ndarray
| An array of logits generated from the model.
|
| Returns
| -------
| numpy.ndarray
| Computes log odds for corresponding top-k token ids.
|
| get_output_names_and_update_topk_token_ids(self, X)
| Gets the token names for top-k token ids for Causal/Masked LM.
|
| Parameters
| ----------
| X: np.ndarray
| Input(Text) for an explanation row.
|
| Returns
| -------
| list
| A list of output tokens.
|
| save(self, out_file)
| Save the model to the given file stream.
|
| update_cache_X(self, X)
| The function updates original input(X) and top-k token ids for the Causal/Masked LM.
|
| It mimics the caching mechanism to update the original input and topk token ids
| that are to be explained and which updates for every new row of explanation.
|
| Parameters
| ----------
| X: np.ndarray
| Input(Text) for an explanation row.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| load(in_file, instantiate=True)
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TransformersPipeline(shap.models._model.Model)
| TransformersPipeline(pipeline, rescale_to_logits=False)
|
| This wraps a transformers pipeline object for easy explanations.
|
| By default transformers pipeline object output lists of dictionaries, not standard
| tensors as expected by SHAP. This class wraps pipelines to make them output nice
| tensor formats.
|
| Method resolution order:
| TransformersPipeline
| shap.models._model.Model
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __call__(self, strings)
| Call self as a function.
|
| __init__(self, pipeline, rescale_to_logits=False)
| Build a new model by wrapping the given pipeline object.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.models._model.Model:
|
| save(self, out_file: 'BinaryIO') -> 'None'
| Save the model to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.models._model.Model:
|
| load(in_file: 'BinaryIO', instantiate: 'bool' = True) -> 'Model | dict[str, Any]'
| This is meant to be overridden by subclasses and called with super.
|
| We return constructor argument values when not being instantiated. Since there are no
| constructor arguments for the Serializable class we just return an empty dictionary.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['Model', 'TeacherForcing', 'TextGeneration', 'TopKLM', 'Tra...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\models\__init__.py
shap.monitoring_plot
Python Library Documentation: function monitoring in module shap.plots._monitoring
monitoring(ind, shap_values, features, feature_names=None, show=True)
Create a SHAP monitoring plot.
(Note this function is preliminary and subject to change!!)
A SHAP monitoring plot is meant to display the behavior of a model
over time. Often the shap_values given to this plot explain the loss
of a model, so changes in a feature's impact on the model's loss over
time can help in monitoring the model's performance.
Parameters
----------
ind : int
Index of the feature to plot.
shap_values : numpy.array
Matrix of SHAP values (# samples x # features)
features : numpy.array or pandas.DataFrame
Matrix of feature values (# samples x # features)
feature_names : list
Names of the features (length # features)
shap.multioutput_decision_plot
Python Library Documentation: function multioutput_decision in module shap.plots._decision
multioutput_decision(base_values, shap_values, row_index, **kwargs) -> 'DecisionPlotResult | None'
Decision plot for multioutput models.
Plots all outputs for a single observation. By default, the plotted base value will be the mean of base_values
unless new_base_value is specified. Supports both SHAP values and SHAP interaction values.
Parameters
----------
base_values : list of float
This is the reference value that the feature contributions start from. Use explainer.expected_value.
shap_values : list of numpy.ndarray
A multioutput list of SHAP matrices or SHAP cubes from explainer.shap_values() or
explainer.shap_interaction_values(), respectively.
row_index : int
The integer index of the row to plot.
**kwargs : Any
Arguments to be passed on to decision_plot().
Returns
-------
DecisionPlotResult or None
Returns a DecisionPlotResult object if `return_objects=True`. Returns `None` otherwise (the default).
shap.other
Python Library Documentation: package shap.explainers.other in shap.explainers
NAME
shap.explainers.other
PACKAGE CONTENTS
_coefficient
_lime
_maple
_random
_treegain
_ubjson
CLASSES
shap.explainers._explainer.Explainer(shap._serializable.Serializable)
shap.explainers.other._coefficient.Coefficient
shap.explainers.other._lime.LimeTabular
shap.explainers.other._maple.Maple
shap.explainers.other._maple.TreeMaple
shap.explainers.other._random.Random
shap.explainers.other._treegain.TreeGain
class Coefficient(shap.explainers._explainer.Explainer)
| Coefficient(model)
|
| Simply returns the model coefficients as the feature attributions.
|
| This is only for benchmark comparisons and does not approximate SHAP values in a
| meaningful way.
|
| Method resolution order:
| Coefficient
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model)
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| attributions(self, X)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class LimeTabular(shap.explainers._explainer.Explainer)
| LimeTabular(model, data, mode='classification')
|
| Simply wrap of lime.lime_tabular.LimeTabularExplainer into the common shap interface.
|
| Parameters
| ----------
| model : function or iml.Model
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array
| The background dataset.
|
| mode : "classification" or "regression"
| Control the mode of LIME tabular.
|
| Method resolution order:
| LimeTabular
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model, data, mode='classification')
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| attributions(self, X, nsamples=5000, num_features=None)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Maple(shap.explainers._explainer.Explainer)
| Maple(model, data)
|
| Simply wraps MAPLE into the common SHAP interface.
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array
| The background dataset.
|
| Method resolution order:
| Maple
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model, data)
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| attributions(self, X, multiply_by_input=False)
| Compute the MAPLE coef attributions.
|
| Parameters
| ----------
| multiply_by_input : bool
| If true, this multiplies the learned coefficients by the mean-centered input. This makes these
| values roughly comparable to SHAP values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Random(shap.explainers._explainer.Explainer)
| Random(model: 'Any', masker: 'Any', link: 'Callable[..., Any]' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | list[list[str]] | None' = None, linearize_link: 'bool' = True, constant: 'bool' = False, **call_args: 'Any') -> 'None'
|
| Simply returns random (normally distributed) feature attributions.
|
| This is only for benchmark comparisons. It supports both fully random attributions and random
| attributions that are constant across all explanations.
|
| Method resolution order:
| Random
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model: 'Any', masker: 'Any', link: 'Callable[..., Any]' = CPUDispatcher(<function identity at 0x00000213EC6080E0>), feature_names: 'list[str] | list[list[str]] | None' = None, linearize_link: 'bool' = True, constant: 'bool' = False, **call_args: 'Any') -> 'None'
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explain a single row and return feature attributions.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TreeGain(shap.explainers._explainer.Explainer)
| TreeGain(model)
|
| Simply returns the global gain/gini feature importances for tree models.
|
| This is only for benchmark comparisons and is not meant to approximate SHAP values.
|
| Method resolution order:
| TreeGain
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model)
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| attributions(self, X)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TreeMaple(shap.explainers._explainer.Explainer)
| TreeMaple(model, data)
|
| Simply tree MAPLE into the common SHAP interface.
|
| Parameters
| ----------
| model : function
| User supplied function that takes a matrix of samples (# samples x # features) and
| computes the output of the model for those samples. The output can be a vector
| (# samples) or a matrix (# samples x # model outputs).
|
| data : numpy.array
| The background dataset.
|
| Method resolution order:
| TreeMaple
| shap.explainers._explainer.Explainer
| shap._serializable.Serializable
| builtins.object
|
| Methods defined here:
|
| __init__(self, model, data)
| Build a new explainer for the passed model.
|
| Parameters
| ----------
| model : object or function
| User supplied function or model object that takes a dataset of samples and
| computes the output of the model for those samples.
|
| masker : function, numpy.array, pandas.DataFrame, tokenizer, None, or a list of these for each model input
| The function used to "mask" out hidden features of the form `masked_args = masker(*model_args, mask=mask)`.
| It takes input in the same form as the model, but for just a single sample with a binary
| mask, then returns an iterable of masked samples. These
| masked samples will then be evaluated using the model function and the outputs averaged.
| As a shortcut for the standard masking using by SHAP you can pass a background data matrix
| instead of a function and that matrix will be used for masking. Domain specific masking
| functions are available in shap such as shap.ImageMasker for images and shap.TokenMasker
| for text. In addition to determining how to replace hidden features, the masker can also
| constrain the rules of the cooperative game used to explain the model. For example
| shap.TabularMasker(data, hclustering="correlation") will enforce a hierarchical clustering
| of coalitions for the game (in this special case the attributions are known as the Owen values).
|
| link : function
| The link function used to map between the output units of the model and the SHAP value units. By
| default it is shap.links.identity, but shap.links.logit can be useful so that expectations are
| computed in probability units while explanations remain in the (more naturally additive) log-odds
| units. For more details on how link functions work see any overview of link functions for generalized
| linear models.
|
| algorithm : "auto", "permutation", "partition", "tree", or "linear"
| The algorithm used to estimate the Shapley values. There are many different algorithms that
| can be used to estimate the Shapley values (and the related value for constrained games), each
| of these algorithms have various tradeoffs and are preferable in different situations. By
| default the "auto" options attempts to make the best choice given the passed model and masker,
| but this choice can always be overridden by passing the name of a specific algorithm. The type of
| algorithm used will determine what type of subclass object is returned by this constructor, and
| you can also build those subclasses directly if you prefer or need more fine grained control over
| their options.
|
| output_names : None or list of strings
| The names of the model outputs. For example if the model is an image classifier, then output_names would
| be the names of all the output classes. This parameter is optional. When output_names is None then
| the Explanation objects produced by this explainer will not have any output_names, which could effect
| downstream plots.
|
| seed: None or int
| seed for reproducibility
|
| attributions(self, X, multiply_by_input=False)
| Compute the MAPLE coef attributions.
|
| Parameters
| ----------
| multiply_by_input : bool
| If true, this multiplies the learned coefficients by the mean-centered input. This makes these
| values roughly comparable to SHAP values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from shap.explainers._explainer.Explainer:
|
| __call__(self, *args: 'Any', max_evals: "int | Literal['auto']" = 'auto', main_effects: 'bool' = False, error_bounds: 'bool' = False, batch_size: "int | Literal['auto']" = 'auto', outputs: 'Any' = None, silent: 'bool' = False, **kwargs: 'Any') -> 'Explanation | list[Explanation]'
| Explains the output of model(*args), where args is a list of parallel iterable datasets.
|
| Note this default version could be an abstract method that is implemented by each algorithm-specific
| subclass of Explainer. Descriptions of each subclasses' __call__ arguments
| are available in their respective doc-strings.
|
| explain_row(self, *row_args: 'Any', max_evals: "int | Literal['auto']", main_effects: 'bool', error_bounds: 'bool', outputs: 'Any', silent: 'bool', **kwargs: 'Any') -> 'dict[str, Any]'
| Explains a single row and returns the tuple (row_values, row_expected_values, row_mask_shapes, main_effects).
|
| This is an abstract method meant to be implemented by each subclass.
|
| Returns
| -------
| tuple
| A tuple of (row_values, row_expected_values, row_mask_shapes), where row_values is an array of the
| attribution values for each sample, row_expected_values is an array (or single value) representing
| the expected value of the model for each sample (which is the same for all samples unless there
| are fixed inputs present, like labels when explaining the loss), and row_mask_shapes is a list
| of all the input shapes (since the row_values is always flattened),
|
| save(self, out_file: 'Any', model_saver: 'str | Callable[..., Any]' = '.save', masker_saver: 'str | Callable[..., Any]' = '.save') -> 'None'
| Write the explainer to the given file stream.
|
| ----------------------------------------------------------------------
| Class methods inherited from shap.explainers._explainer.Explainer:
|
| load(in_file: 'Any', model_loader: 'Callable[..., Any] | None' = None, masker_loader: 'Callable[..., Any] | None' = None, instantiate: 'bool' = True) -> 'Explainer | dict[str, Any]'
| Load an Explainer from the given file stream.
|
| Parameters
| ----------
| in_file : The file stream to load objects from.
|
| ----------------------------------------------------------------------
| Static methods inherited from shap.explainers._explainer.Explainer:
|
| supports_model_with_masker(model: 'Any', masker: 'Any') -> 'bool'
| Determines if this explainer can handle the given model.
|
| This is an abstract static method meant to be implemented by each subclass.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from shap._serializable.Serializable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['Coefficient', 'LimeTabular', 'Maple', 'TreeMaple', 'Random...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\explainers\other\__init__.py
shap.partial_dependence_plot
Python Library Documentation: function partial_dependence in module shap.plots._partial_dependence
partial_dependence(ind, model, data, xmin='percentile(0)', xmax='percentile(100)', npoints=None, feature_names=None, hist=True, model_expected_value=False, feature_expected_value=False, shap_values=None, ylabel=None, ice=True, ace_opacity=1, pd_opacity=1, pd_linewidth=2, ace_linewidth='auto', ax=None, show=True)
A basic partial dependence plot function.
shap.plots
Python Library Documentation: package shap.plots in shap
NAME
shap.plots
PACKAGE CONTENTS
_bar
_beeswarm
_benchmark
_decision
_embedding
_force
_force_matplotlib
_group_difference
_heatmap
_image
_labels
_monitoring
_partial_dependence
_scatter
_style
_text
_utils
_violin
_waterfall
colors (package)
FUNCTIONS
bar(shap_values, max_display=10, order=shap.Explanation.abs, clustering=None, clustering_cutoff=0.5, show_data='auto', ax=None, show=True)
Create a bar plot of a set of SHAP values.
Parameters
----------
shap_values : shap.Explanation or shap.Cohorts or dictionary of shap.Explanation objects
Passing a multi-row :class:`.Explanation` object creates a global
feature importance plot.
Passing a single row of an explanation (i.e. ``shap_values[0]``) creates
a local feature importance plot.
Passing a dictionary of Explanation objects will create a multiple-bar
plot with one bar type for each of the cohorts represented by the
explanation objects.
max_display : int
How many top features to include in the bar plot (default is 10).
order : OpChain or numpy.ndarray
A function that returns a sort ordering given a matrix of SHAP values
and an axis, or a direct sample ordering given as a ``numpy.ndarray``.
By default, take the absolute value.
clustering: np.ndarray or None
A partition tree, as returned by :func:`shap.utils.hclust`
clustering_cutoff: float
Controls how much of the clustering structure is displayed.
show_data: bool or str
Controls if data values are shown as part of the y tick labels. If
"auto", we show the data only when there are no transforms.
ax: matplotlib Axes
Axes object to draw the plot onto, otherwise uses the current Axes.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
Returns
-------
ax: matplotlib Axes
Returns the :external+mpl:class:`~matplotlib.axes.Axes` object with the plot drawn onto it. Only
returned if ``show=False``.
Examples
--------
See `bar plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/bar.html>`_.
beeswarm(shap_values: 'Explanation', max_display: 'int | None' = 10, order=shap.Explanation.abs.mean(0), clustering=None, cluster_threshold=0.5, color=None, axis_color='#333333', alpha: 'float' = 1.0, ax: 'plt.Axes | None' = None, show: 'bool' = True, log_scale: 'bool' = False, color_bar: 'bool' = True, s: 'float' = 16, plot_size: "Literal['auto'] | float | tuple[float, float] | None" = 'auto', color_bar_label: 'str' = 'Feature value', group_remaining_features: 'bool' = True)
Create a SHAP beeswarm plot, colored by feature values when they are provided.
Parameters
----------
shap_values : Explanation
This is an :class:`.Explanation` object containing a matrix of SHAP values
(# samples x # features).
max_display : int
How many top features to include in the plot (default is 10, or 7 for
interaction plots).
ax: matplotlib Axes
Axes object to draw the plot onto, otherwise uses the current Axes.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further
after it has been created, returning the current axis via
:external+mpl:func:`matplotlib.pyplot.gca()`.
color_bar : bool
Whether to draw the color bar (legend).
s : float
What size to make the markers. For further information, see ``s`` in
:external+mpl:func:`matplotlib.pyplot.scatter`.
plot_size : "auto" (default), float, (float, float), or None
What size to make the plot. By default, the size is auto-scaled based on the
number of features that are being displayed. Passing a single float will cause
each row to be that many inches high. Passing a pair of floats will scale the
plot by that number of inches. If ``None`` is passed, then the size of the
current figure will be left unchanged. If ``ax`` is not ``None``, then passing
``plot_size`` will raise a :exc:`ValueError`.
group_remaining_features: bool
If there are more features than ``max_display``, then plot a row representing
the sum of SHAP values of all remaining features. Default True.
Returns
-------
ax: matplotlib Axes
Returns the :external+mpl:class:`~matplotlib.axes.Axes` object with the plot drawn onto it. Only
returned if ``show=False``.
Examples
--------
See `beeswarm plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/beeswarm.html>`_.
benchmark(benchmark, show=True)
Plot a BenchmarkResult or list of such results.
decision(base_value: 'float | np.ndarray', shap_values: 'np.ndarray', features: 'np.ndarray | pd.Series | pd.DataFrame | list | None' = None, feature_names=None, feature_order='importance', feature_display_range=None, highlight=None, link='identity', plot_color=None, axis_color='#333333', y_demarc_color='#333333', alpha=None, color_bar=True, auto_size_plot=True, title=None, xlim=None, show=True, return_objects=False, ignore_warnings=False, new_base_value=None, legend_labels=None, legend_location='best') -> 'DecisionPlotResult | None'
Visualize model decisions using cumulative SHAP values.
Each plotted line explains a single model prediction. If a single prediction is plotted, feature values will be
printed in the plot (if supplied). If multiple predictions are plotted together, feature values will not be printed.
Plotting too many predictions together will make the plot unintelligible.
Parameters
----------
base_value : float or numpy.ndarray
This is the reference value that the feature contributions start from. Usually, this is
``explainer.expected_value``.
shap_values : numpy.ndarray
Matrix of SHAP values (# features) or (# samples x # features) from
``explainer.shap_values()``. Or cube of SHAP interaction values (# samples x
# features x # features) from ``explainer.shap_interaction_values()``.
features : numpy.array or pandas.Series or pandas.DataFrame or numpy.ndarray or list
Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
features and, optionally, the feature names.
feature_names : list or numpy.ndarray
List of feature names (# features). If ``None``, names may be derived from the
``features`` argument if a Pandas object is provided. Otherwise, numeric feature
names will be generated.
feature_order : str or None or list or numpy.ndarray
Any of "importance" (the default), "hclust" (hierarchical clustering), ``None``,
or a list/array of indices.
feature_display_range: slice or range
The slice or range of features to plot after ordering features by ``feature_order``. A step of 1 or ``None``
will display the features in ascending order. A step of -1 will display the features in descending order. If
``feature_display_range=None``, ``slice(-1, -21, -1)`` is used (i.e. show the last 20 features in descending order).
If ``shap_values`` contains interaction values, the number of features is automatically expanded to include all
possible interactions: N(N + 1)/2 where N = ``shap_values.shape[1]``.
highlight : Any
Specify which observations to draw in a different line style. All numpy indexing methods are supported. For
example, list of integer indices, or a bool array.
link : str
Use "identity" or "logit" to specify the transformation used for the x-axis. The "logit" link transforms
log-odds into probabilities.
plot_color : str or matplotlib.colors.ColorMap
Color spectrum used to draw the plot lines. If ``str``, a registered matplotlib color name is assumed.
axis_color : str or int
Color used to draw plot axes.
y_demarc_color : str or int
Color used to draw feature demarcation lines on the y-axis.
alpha : float
Alpha blending value in [0, 1] used to draw plot lines.
color_bar : bool
Whether to draw the color bar (legend).
auto_size_plot : bool
Whether to automatically size the matplotlib plot to fit the number of features
displayed. If ``False``, specify the plot size using matplotlib before calling
this function.
title : str
Title of the plot.
xlim: tuple[float, float]
The extents of the x-axis (e.g. ``(-1.0, 1.0)``). If not specified, the limits
are determined by the maximum/minimum predictions centered around base_value
when ``link="identity"``. When ``link="logit"``, the x-axis extents are ``(0,
1)`` centered at 0.5. ``xlim`` values are not transformed by the ``link``
function. This argument is provided to simplify producing multiple plots on the
same scale for comparison.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
return_objects : bool
Whether to return a :obj:`DecisionPlotResult` object containing various plotting
features. This can be used to generate multiple decision plots using the same
feature ordering and scale.
ignore_warnings : bool
Plotting many data points or too many features at a time may be slow, or may create very large plots. Set
this argument to ``True`` to override hard-coded limits that prevent plotting large amounts of data.
new_base_value : float
SHAP values are relative to a base value. By default, this base value is the
expected value of the model's raw predictions. Use ``new_base_value`` to shift
the base value to an arbitrary value (e.g. the cutoff point for a binary
classification task).
legend_labels : list of str
List of legend labels. If ``None``, legend will not be shown.
legend_location : str
Legend location. Any of "best", "upper right", "upper left", "lower left", "lower right", "right",
"center left", "center right", "lower center", "upper center", "center".
Returns
-------
DecisionPlotResult or None
Returns a :obj:`DecisionPlotResult` object if ``return_objects=True``. Returns ``None`` otherwise (the default).
Examples
--------
Plot two decision plots using the same feature order and x-axis.
>>> range1, range2 = range(20), range(20, 40)
>>> r = decision_plot(base, shap_values[range1], features[range1], return_objects=True)
>>> decision_plot(base, shap_values[range2], features[range2], feature_order=r.feature_idx, xlim=r.xlim)
See more `decision plot examples here <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/decision_plot.html>`_.
embedding(ind, shap_values, feature_names=None, method='pca', alpha=1.0, show=True)
Use the SHAP values as an embedding which we project to 2D for visualization.
Parameters
----------
ind : int or string
If this is an int it is the index of the feature to use to color the embedding.
If this is a string it is either the name of the feature, or it can have the
form "rank(int)" to specify the feature with that rank (ordered by mean absolute
SHAP value over all the samples), or "sum()" to mean the sum of all the SHAP values,
which is the model's output (minus its expected value).
shap_values : numpy.array
Matrix of SHAP values (# samples x # features).
feature_names : None or list
The names of the features in the shap_values array.
method : "pca" or numpy.array
How to reduce the dimensions of the shap_values to 2D. If "pca" then the 2D
PCA projection of shap_values is used. If a numpy array then is should be
(# samples x 2) and represent the embedding of that values.
alpha : float
The transparency of the data points (between 0 and 1). This can be useful to
show the density of the data points when using a large dataset.
force(base_value, shap_values=None, features=None, feature_names=None, out_names=None, link='identity', plot_cmap='RdBu', matplotlib=False, show=True, figsize=(20, 3), ordering_keys=None, ordering_keys_time_format=None, text_rotation=0, contribution_threshold=0.05)
Visualize the given SHAP values with an additive force layout.
Parameters
----------
base_value : float or shap.Explanation
If a float is passed in, this is the reference value that the feature contributions start from.
For SHAP values, it should be the value of ``explainer.expected_value``.
However, it is recommended to pass in a SHAP :class:`.Explanation` object instead (``shap_values``
is not necessary in this case).
shap_values : numpy.array
Matrix of SHAP values (# features) or (# samples x # features). If this is a
1D array, then a single force plot will be drawn. If it is a 2D array, then a
stacked force plot will be drawn.
features : numpy.array
Matrix of feature values (# features) or (# samples x # features). This provides the values of all the
features, and should be the same shape as the ``shap_values`` argument.
feature_names : list
List of feature names (# features).
out_names : str
The name of the output of the model (plural to support multi-output plotting in the future).
link : "identity" or "logit"
The transformation used when drawing the tick mark labels. Using "logit" will change log-odds numbers
into probabilities.
plot_cmap : str or list[str]
Color map to use. It can be a string (defaults to ``RdBu``) or a list of hex color strings.
matplotlib : bool
Whether to use the default Javascript output, or the (less developed) matplotlib output.
Using matplotlib can be helpful in scenarios where rendering Javascript/HTML
is inconvenient. Defaults to False.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
Only applicable when ``matplotlib`` is set to True.
figsize :
Figure size of the matplotlib output.
contribution_threshold : float
Controls the feature names/values that are displayed on force plot.
Only features that the magnitude of their shap value is larger than min_perc * (sum of all abs shap values)
will be displayed.
group_difference(shap_values, group_mask, feature_names=None, xlabel=None, xmin=None, xmax=None, max_display=None, sort=True, show=True, ax=None)
This plots the difference in mean SHAP values between two groups.
It is useful to decompose many group level metrics about the model output among the
input features. Quantitative fairness metrics for machine learning models are
a common example of such group level metrics.
Parameters
----------
shap_values : numpy.array
Matrix of SHAP values (# samples x # features) or a vector of model outputs (# samples).
group_mask : numpy.array
A boolean mask where True represents the first group of samples and False the second.
feature_names : list
A list of feature names.
heatmap(shap_values: shap._explanation.Explanation, instance_order=shap.Explanation.hclust, feature_values=shap.Explanation.abs.mean(0), feature_order=None, max_display=10, cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EED1E810>, show=True, plot_width=8, ax=None)
Create a heatmap plot of a set of SHAP values.
This plot is designed to show the population substructure of a dataset using supervised
clustering and a heatmap.
Supervised clustering involves clustering data points not by their original
feature values but by their explanations.
By default, we cluster using :func:`shap.utils.hclust_ordering`,
but any clustering can be used to order the samples.
Parameters
----------
shap_values : shap.Explanation
A multi-row :class:`.Explanation` object that we want to visualize in a
cluster ordering.
instance_order : OpChain or numpy.ndarray
A function that returns a sort ordering given a matrix of SHAP values and an axis, or
a direct sample ordering given as an ``numpy.ndarray``.
feature_values : OpChain or numpy.ndarray
A function that returns a global summary value for each input feature, or an array of such values.
feature_order : None, OpChain, or numpy.ndarray
A function that returns a sort ordering given a matrix of SHAP values and an axis, or
a direct input feature ordering given as an ``numpy.ndarray``.
If ``None``, then we use ``feature_values.argsort``.
max_display : int
The maximum number of features to display (default is 10).
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
plot_width : int, default 8
The width of the heatmap plot.
ax : matplotlib Axes
Axes object to draw the plot onto, otherwise uses the current Axes.
Returns
-------
ax: matplotlib Axes
Returns the :external+mpl:class:`~matplotlib.axes.Axes` object with the plot drawn onto it.
Examples
--------
See `heatmap plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/heatmap.html>`_.
image(shap_values: 'Explanation | np.ndarray | list[np.ndarray]', pixel_values: 'np.ndarray | None' = None, labels: 'list[str] | list[list[str]] | np.ndarray | None' = None, true_labels: 'list | None' = None, width: 'int | None' = 20, aspect: 'float | None' = 0.2, hspace: "float | Literal['auto'] | None" = 0.2, labelpad: 'float | None' = None, cmap: 'str | Colormap | None' = <matplotlib.colors.LinearSegmentedColormap object at 0x00000213EED1E7B0>, vmax: 'float | None' = None, show: 'bool | None' = True)
Plots SHAP values for image inputs.
Parameters
----------
shap_values : [numpy.array]
List of arrays of SHAP values. Each array has the shape
(# samples x width x height x channels), and the
length of the list is equal to the number of model outputs that are being
explained.
pixel_values : numpy.array
Matrix of pixel values (# samples x width x height x channels) for each image.
It should be the same
shape as each array in the ``shap_values`` list of arrays.
labels : list or np.ndarray
List or ``np.ndarray`` (# samples x top_k classes) of names for each of the
model outputs that are being explained.
true_labels: list
List of a true image labels to plot.
width : float
The width of the produced matplotlib plot.
labelpad : float
How much padding to use around the model output labels.
cmap: str or matplotlib.colors.Colormap
Colormap to use when plotting the SHAP values.
vmax: Optional float
Sets the colormap scale for SHAP values from ``-vmax`` to ``+vmax``.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot
to be customized further after it has been created.
Examples
--------
See `image plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/image.html>`_.
image_to_text(shap_values)
Plots SHAP values for image inputs with test outputs.
Parameters
----------
shap_values : [numpy.array]
List of arrays of SHAP values. Each array has the shap (# width x height x channels x num output tokens). One array
for each sample
initjs()
Initialize the necessary javascript libraries for interactive force plots.
Run this only in a notebook environment with IPython installed.
monitoring(ind, shap_values, features, feature_names=None, show=True)
Create a SHAP monitoring plot.
(Note this function is preliminary and subject to change!!)
A SHAP monitoring plot is meant to display the behavior of a model
over time. Often the shap_values given to this plot explain the loss
of a model, so changes in a feature's impact on the model's loss over
time can help in monitoring the model's performance.
Parameters
----------
ind : int
Index of the feature to plot.
shap_values : numpy.array
Matrix of SHAP values (# samples x # features)
features : numpy.array or pandas.DataFrame
Matrix of feature values (# samples x # features)
feature_names : list
Names of the features (length # features)
partial_dependence(ind, model, data, xmin='percentile(0)', xmax='percentile(100)', npoints=None, feature_names=None, hist=True, model_expected_value=False, feature_expected_value=False, shap_values=None, ylabel=None, ice=True, ace_opacity=1, pd_opacity=1, pd_linewidth=2, ace_linewidth='auto', ax=None, show=True)
A basic partial dependence plot function.
scatter(shap_values: 'Explanation', color: 'str | Explanation | None' = '#1E88E5', hist: 'bool' = True, axis_color='#333333', cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EEBFD820>, dot_size=16, x_jitter: "float | Literal['auto']" = 'auto', alpha: 'float' = 1.0, title: 'str | None' = None, xmin: 'AxisLimitSpec' = None, xmax: 'AxisLimitSpec' = None, ymin: 'AxisLimitSpec' = None, ymax: 'AxisLimitSpec' = None, overlay: 'dict[str, Any] | None' = None, ax: 'plt.Axes | None' = None, ylabel: 'str' = 'SHAP value', show: 'bool' = True)
Create a SHAP dependence scatter plot, optionally colored by an interaction feature.
Plots the value of the feature on the x-axis and the SHAP value of the same feature
on the y-axis. This shows how the model depends on the given feature, and is like a
richer extension of classical partial dependence plots. Vertical dispersion of the
data points represents interaction effects. Grey ticks along the y-axis are data
points where the feature's value was NaN.
Note that if you want to change the data being displayed, you can update the
``shap_values.display_features`` attribute and it will then be used for plotting instead of
``shap_values.data``.
Parameters
----------
shap_values : shap.Explanation
Typically a single column of an :class:`.Explanation` object
(i.e. ``shap_values[:, "Feature A"]``).
Alternatively, pass multiple columns to create several subplots
(i.e. ``shap_values[:, ["Feature A", "Feature B"]]``).
color : string or shap.Explanation, optional
How to color the scatter plot points. This can be a fixed color string, or an
:class:`.Explanation` object.
If it is an :class:`.Explanation` object, then the scatter plot points are
colored by the feature that seems to have the strongest interaction effect with
the feature given by the ``shap_values`` argument. This is calculated using
:func:`shap.utils.approximate_interactions`.
If only a single column of an :class:`.Explanation` object is passed, then that
feature column will be used to color the data points.
hist : bool
Whether to show a light histogram along the x-axis to show the density of the
data. Note that the histogram is normalized such that if all the points were in
a single bin, then that bin would span the full height of the plot. Defaults to
``True``.
x_jitter : 'auto' or float
Adds random jitter to feature values by specifying a float between 0 to 1. May
increase plot readability when a feature is discrete. By default, ``x_jitter``
is chosen based on auto-detection of categorical features.
title: str, optional
Plot title.
alpha : float
The transparency of the data points (between 0 and 1). This can be useful to
show the density of the data points when using a large dataset.
xmin, xmax, ymin, ymax : float, string, aggregated Explanation or None
Desired axis limits. Can be a float to specify a fixed limit.
It can be a string of the format ``"percentile(float)"`` to denote that
percentile of the feature's value.
It can also be an aggregated column of a single column of an :class:`.Explanation`,
such as ``explanation[:, "feature_name"].percentile(20)``.
overlay: dict, optional
Optional dictionary of up to three additional curves to overlay as line plots.
The dictionary maps a curve name to a list of (xvalues, yvalues) pairs, where
there is one pair for each feature to be plotted.
ax : matplotlib Axes, optional
Optionally specify an existing :external+mpl:class:`matplotlib.axes.Axes` object, into which
the plot will be placed.
Only supported when plotting a single feature.
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further after it
has been created.
Returns
-------
ax : matplotlib Axes object
Returns the :external+mpl:class:`~matplotlib.axes.Axes` object with the plot drawn onto it. Only
returned if ``show=False``.
Examples
--------
See `scatter plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/scatter.html>`_.
text(shap_values, num_starting_labels=0, grouping_threshold=0.01, separator='', xmin=None, xmax=None, cmax=None, display=True)
Plots an explanation of a string of text using coloring and interactive labels.
The output is interactive HTML and you can click on any token to toggle the display of the
SHAP value assigned to that token.
Parameters
----------
shap_values : [numpy.array]
List of arrays of SHAP values. Each array has the shap values for a string (#input_tokens x output_tokens).
num_starting_labels : int
Number of tokens (sorted in descending order by corresponding SHAP values)
that are uncovered in the initial view.
When set to 0, all tokens are covered.
grouping_threshold : float
If the component substring effects are less than a ``grouping_threshold``
fraction of an unlowered interaction effect, then we visualize the entire group
as a single chunk. This is primarily used for explanations that were computed
with fixed_context set to 1 or 0 when using the :class:`.explainers.Partition`
explainer, since this causes interaction effects to be left on internal nodes
rather than lowered.
separator : string
The string separator that joins tokens grouped by interaction effects and
unbroken string spans. Defaults to the empty string ``""``.
xmin : float
Minimum shap value bound.
xmax : float
Maximum shap value bound.
cmax : float
Maximum absolute shap value for sample. Used for scaling colors for input tokens.
display: bool
Whether to display or return html to further manipulate or embed. Default: ``True``
Examples
--------
See `text plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/text.html>`_.
violin(shap_values, features=None, feature_names=None, max_display=None, plot_type='violin', color=None, axis_color='#333333', title=None, alpha=1, show=True, sort=True, color_bar=True, plot_size='auto', layered_violin_max_num_bins=20, class_names=None, class_inds=None, color_bar_label='Feature value', cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EEBFD820>, color_bar_label_size=12, color_bar_tick_size=11, axhline_lw=0.5, use_log_scale=False)
Create a SHAP violin plot, colored by feature values when they are provided.
Parameters
----------
shap_values : Explanation or numpy.ndarray
For single output explanations, this is a matrix of SHAP values (# samples x # features).
features : numpy.ndarray or pandas.DataFrame or list, optional
Matrix of feature values (# samples x # features), or a ``feature_names`` list as shorthand.
feature_names : list, optional
Names of the features (length: # features).
max_display : int, optional
How many top features to include in the plot (default is 20).
plot_type : {"violin", "layered_violin"}, optional
What type of summary plot to produce. A "layered_violin" plot shows the
distribution of the SHAP values of each variable. A "violin" plot is the same,
except with outliers drawn as scatter points.
color : str or None, optional
Color or colormap to use for the plot. If None, a default is chosen.
axis_color : str, optional
Color for the plot axes.
title : str or None, optional
Plot title (currently unused).
alpha : float, optional
Opacity of the plot elements.
show : bool, optional
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further after it has been created.
sort : bool, optional
Whether to sort features by the sum of their effect magnitudes.
color_bar : bool, optional
Whether to draw the color bar (legend).
plot_size : {"auto", float, (float, float), None}, optional
What size to make the plot. By default, the size is auto-scaled based on the number of
features that are being displayed. Passing a single float will cause each row to be that
many inches high. Passing a pair of floats will scale the plot by that
number of inches. If ``None`` is passed, then the size of the current figure will be left
unchanged.
layered_violin_max_num_bins : int, optional
Maximum number of bins for layered violin plots.
color_bar_label : str, optional
Label for the color bar.
cmap : str or Colormap, optional
Colormap to use for coloring points by feature value.
color_bar_label_size : int, optional
Font size for the color bar label. Default is 11.
color_bar_tick_size : int, optional
Font size for the color bar ticks. Default is 11.
axhline_lw : float, optional
Line width for horizontal lines in the plot.
use_log_scale : bool, optional
Whether to use a symmetric log scale for the x-axis.
Examples
--------
See `violin plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/violin.html>`_.
waterfall(shap_values, max_display=10, show=True)
Plots an explanation of a single prediction as a waterfall plot.
The SHAP value of a feature represents the impact of the evidence provided by that feature on the model's
output. The waterfall plot is designed to visually display how the SHAP values (evidence) of each feature
move the model output from our prior expectation under the background data distribution, to the final model
prediction given the evidence of all the features.
Features are sorted by the magnitude of their SHAP values with the smallest
magnitude features grouped together at the bottom of the plot when the number of
features in the models exceeds the ``max_display`` parameter.
Parameters
----------
shap_values : Explanation
A one-dimensional :class:`.Explanation` object that contains the feature values and SHAP values to plot.
max_display : int
The maximum number of features to display (default is 10).
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further after it
has been created, returning the current axis via plt.gca().
Examples
--------
See `waterfall plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/waterfall.html>`_.
DATA
__all__ = ['bar', 'beeswarm', 'benchmark', 'decision', 'embedding', 'f...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\plots\__init__.py
shap.sample
Python Library Documentation: function sample in module shap.utils._general
sample(X: '_ArrayT', nsamples: 'int' = 100, random_state: 'int' = 0) -> '_ArrayT'
Performs sampling without replacement of the input data ``X``.
This is a simple wrapper over scikit-learn's ``shuffle`` function.
It is used mainly to downsample ``X`` for use as a background
dataset in SHAP :class:`.Explainer` and its subclasses.
.. versionchanged :: 0.42
The behaviour of ``sample`` was changed from sampling *with* replacement to sampling
*without* replacement.
Note that reproducibility might be broken when using this function pre- and post-0.42,
even with the specification of ``random_state``.
Parameters
----------
X : array-like
Data to sample from. Input data can be arrays, lists, dataframes
or scipy sparse matrices with a consistent first dimension.
nsamples : int
Number of samples to generate from ``X``.
random_state :
Determines random number generation for shuffling the data. Use this to
ensure reproducibility across multiple function calls.
shap.save_html
Python Library Documentation: function save_html in module shap.plots._force
save_html(out_file, plot, full_html=True)
Save html plots to an output file.
Parameters
----------
out_file : str or file
Location or file to be written to.
plot : BaseVisualizer
Visualizer returned by :func:`shap.plots.force()`.
full_html : boolean (default: True)
If ``True``, writes a complete HTML document starting
with an ``<html>`` tag. If ``False``, only script and div
tags are included.
shap.summary_plot
Python Library Documentation: function summary_legacy in module shap.plots._beeswarm
summary_legacy(shap_values, features=None, feature_names=None, max_display=None, plot_type=None, color=None, axis_color='#333333', title=None, alpha=1, show=True, sort=True, color_bar=True, plot_size='auto', layered_violin_max_num_bins=20, class_names=None, class_inds=None, color_bar_label='Feature value', cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EEBFD820>, show_values_in_legend: 'bool' = False, use_log_scale: 'bool' = False, rng: 'np.random.Generator | None' = None)
Create a SHAP beeswarm plot, colored by feature values when they are provided.
Parameters
----------
shap_values : numpy.array
For single output explanations this is a matrix of SHAP values (# samples x # features).
For multi-output explanations this is a list of such matrices of SHAP values.
features : numpy.array or pandas.DataFrame or list
Matrix of feature values (# samples x # features) or a feature_names list as shorthand
feature_names : list
Names of the features (length # features)
max_display : int
How many top features to include in the plot (default is 20, or 7 for interaction plots)
plot_type : "dot" (default for single output), "bar" (default for multi-output), "violin",
or "compact_dot".
What type of summary plot to produce. Note that "compact_dot" is only used for
SHAP interaction values.
plot_size : "auto" (default), float, (float, float), or None
What size to make the plot. By default the size is auto-scaled based on the number of
features that are being displayed. Passing a single float will cause each row to be that
many inches high. Passing a pair of floats will scale the plot by that
number of inches. If None is passed then the size of the current figure will be left
unchanged.
show_values_in_legend: bool
Flag to print the mean of the SHAP values in the multi-output bar plot. Set to False
by default.
rng : `numpy.random.Generator`, optional
Pseudorandom number generator state. When `rng` is None,
the legacy behavior of using global NumPy random state will be
used. Types other than `numpy.random.Generator` are
passed to `numpy.random.default_rng` to instantiate a ``Generator``.
shap.text_plot
Python Library Documentation: function text in module shap.plots._text
text(shap_values, num_starting_labels=0, grouping_threshold=0.01, separator='', xmin=None, xmax=None, cmax=None, display=True)
Plots an explanation of a string of text using coloring and interactive labels.
The output is interactive HTML and you can click on any token to toggle the display of the
SHAP value assigned to that token.
Parameters
----------
shap_values : [numpy.array]
List of arrays of SHAP values. Each array has the shap values for a string (#input_tokens x output_tokens).
num_starting_labels : int
Number of tokens (sorted in descending order by corresponding SHAP values)
that are uncovered in the initial view.
When set to 0, all tokens are covered.
grouping_threshold : float
If the component substring effects are less than a ``grouping_threshold``
fraction of an unlowered interaction effect, then we visualize the entire group
as a single chunk. This is primarily used for explanations that were computed
with fixed_context set to 1 or 0 when using the :class:`.explainers.Partition`
explainer, since this causes interaction effects to be left on internal nodes
rather than lowered.
separator : string
The string separator that joins tokens grouped by interaction effects and
unbroken string spans. Defaults to the empty string ``""``.
xmin : float
Minimum shap value bound.
xmax : float
Maximum shap value bound.
cmax : float
Maximum absolute shap value for sample. Used for scaling colors for input tokens.
display: bool
Whether to display or return html to further manipulate or embed. Default: ``True``
Examples
--------
See `text plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/text.html>`_.
shap.unsupported
Python Library Documentation: function unsupported in module shap unsupported(*args: Any, **kwargs: Any) -> NoReturn
shap.utils
Python Library Documentation: package shap.utils in shap
NAME
shap.utils
PACKAGE CONTENTS
_clustering
_exceptions
_general
_legacy
_masked_model
_show_progress
_types
_warnings
image
transformers
CLASSES
builtins.object
shap.utils._general.OpChain
shap.utils._masked_model.MaskedModel
class MaskedModel(builtins.object)
| MaskedModel(model, masker, link, linearize_link, *args)
|
| This is a utility class that combines a model, a masker object, and a current input.
|
| The combination of a model, a masker object, and a current input produces a binary set
| function that can be called to mask out any set of inputs. This class attempts to be smart
| about only evaluating the model for background samples when the inputs changed (note this
| requires the masker object to have a .invariants method).
|
| Methods defined here:
|
| __call__(self, masks, zero_index=None, batch_size=None)
| Call self as a function.
|
| __init__(self, model, masker, link, linearize_link, *args)
| Initialize self. See help(type(self)) for accurate signature.
|
| __len__(self)
| How many binary inputs there are to toggle.
|
| By default we just match what the masker tells us. But if the masker doesn't help us
| out by giving a length then we assume is the number of data inputs.
|
| main_effects(self, inds=None, batch_size=None)
| Compute the main effects for this model.
|
| varying_inputs(self)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| mask_shapes
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| delta_mask_noop_value = 2147483647
class OpChain(builtins.object)
| OpChain(root_name: 'str' = '') -> 'None'
|
| A way to represent a set of dot chained operations on an object without actually running them.
|
| Methods defined here:
|
| __call__(self, *args: 'Any', **kwargs: 'Any') -> 'OpChain'
| Update the args for the previous operation.
|
| __getattr__(self, name: 'str') -> 'OpChain'
|
| __getitem__(self, item: 'Any') -> 'OpChain'
|
| __init__(self, root_name: 'str' = '') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| apply(self, obj: 'Any') -> 'Any'
| Applies all our ops to the given object, usually an :class:`.Explanation` instance.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_ops': 'list[list[Any]]', '_root_name': 'str'}
FUNCTIONS
approximate_interactions(index: 'str | int', shap_values: 'npt.NDArray[Any]', X: 'npt.NDArray[Any] | pd.DataFrame', feature_names: 'list[str] | npt.NDArray[Any] | pd.Index | None' = None) -> 'npt.NDArray[Any]'
Order other features by how much interaction they seem to have with the feature at the given index.
This just bins the SHAP values for a feature along that feature's value. For true Shapley interaction
index values for SHAP see the interaction_contribs option implemented in XGBoost.
assert_import(package_name: 'str') -> 'None'
convert_name(ind: 'str | int | None', shap_values: 'npt.NDArray[Any] | None', input_names: 'list[str] | npt.NDArray[Any]') -> 'int | str | None'
delta_minimization_order(all_masks: 'npt.NDArray[Any]', max_swap_size: 'int' = 100, num_passes: 'int' = 2) -> 'npt.NDArray[Any]'
format_value(s: 'Any', format_str: 'str') -> 'str'
Strips trailing zeros and uses a unicode minus sign.
hclust(X: '_ArrayLike', y: '_ArrayLike | None' = None, linkage: "Literal['single', 'complete', 'average']" = 'single', metric: 'str' = 'auto', random_state: 'int | np.random.RandomState' = 0) -> 'npt.NDArray[Any]'
Fit a hierarchical clustering model for features X relative to target variable y.
For more information on clustering methods, see :external+scipy:func:`scipy.cluster.hierarchy.linkage`.
For more information on scipy distance metrics, see :external+scipy:func:`scipy.spatial.distance.pdist`.
Parameters
----------
X: 2d-array-like
Features to cluster
y: array-like or None
Target variable
linkage: str
Defines the method to calculate the distance between clusters. Must be
one of "single", "complete" or "average".
metric: str
Scipy distance metric or "xgboost_distances_r2".
* If ``xgboost_distances_r2``, estimate redundancy distances between
features X with respect to target variable y using
:func:`shap.utils.xgboost_distances_r2`.
* Otherwise, calculate distances between features using the given
distance metric.
* If ``auto`` (default), use ``xgboost_distances_r2`` if target variable
is provided, or else ``cosine`` distance metric.
random_state: int or np.random.RandomState
Numpy random state, defaults to 0.
Returns
-------
clustering: np.array
The hierarchical clustering encoded as a linkage matrix.
hclust_ordering(X: 'npt.NDArray[Any]', metric: 'str' = 'sqeuclidean', anchor_first: 'bool' = False) -> 'npt.NDArray[Any]'
A leaf ordering is under-defined, this picks the ordering that keeps nearby samples similar.
make_masks(cluster_matrix)
Builds a sparse CSR mask matrix from the given clustering.
This function is optimized since trees for images can be very large.
ordinal_str(n: 'int') -> 'str'
Converts a number to and ordinal string.
partition_tree(X: 'pd.DataFrame', metric: 'str' = 'correlation') -> 'npt.NDArray[Any]'
partition_tree_shuffle(indexes: 'npt.NDArray[Any]', index_mask: 'npt.NDArray[np.bool_]', partition_tree: 'npt.NDArray[Any]') -> 'None'
Randomly shuffle the indexes in a way that is consistent with the given partition tree.
Parameters
----------
indexes: np.array
The output location of the indexes we want shuffled. Note that len(indexes) should equal index_mask.sum().
index_mask: np.array
A bool mask of which indexes we want to include in the shuffled list.
partition_tree: np.array
The partition tree we should follow.
potential_interactions(shap_values_column: 'Any', shap_values_matrix: 'Any') -> 'npt.NDArray[Any]'
Order other features by how much interaction they seem to have with the feature at the given index.
This just bins the SHAP values for a feature along that feature's value. For true Shapley interaction
index values for SHAP see the interaction_contribs option implemented in XGBoost.
record_import_error(package_name: 'str', msg: 'str', e: 'ImportError') -> 'None'
safe_isinstance(obj: 'Any', class_path_str: 'str | list[str]') -> 'bool'
Acts as a safe version of isinstance without having to explicitly
import packages which may not exist in the users environment.
Checks if obj is an instance of type specified by class_path_str.
Parameters
----------
obj: Any
Some object you want to test against
class_path_str: str or list
A string or list of strings specifying full class paths
Example: `sklearn.ensemble.RandomForestRegressor`
Returns
-------
bool: True if isinstance is true and the package exists, False otherwise
sample(X: '_ArrayT', nsamples: 'int' = 100, random_state: 'int' = 0) -> '_ArrayT'
Performs sampling without replacement of the input data ``X``.
This is a simple wrapper over scikit-learn's ``shuffle`` function.
It is used mainly to downsample ``X`` for use as a background
dataset in SHAP :class:`.Explainer` and its subclasses.
.. versionchanged :: 0.42
The behaviour of ``sample`` was changed from sampling *with* replacement to sampling
*without* replacement.
Note that reproducibility might be broken when using this function pre- and post-0.42,
even with the specification of ``random_state``.
Parameters
----------
X : array-like
Data to sample from. Input data can be arrays, lists, dataframes
or scipy sparse matrices with a consistent first dimension.
nsamples : int
Number of samples to generate from ``X``.
random_state :
Determines random number generation for shuffling the data. Use this to
ensure reproducibility across multiple function calls.
shapley_coefficients(n: 'int') -> 'npt.NDArray[Any]'
show_progress(iterable: 'Iterable[T]', total: 'int | None' = None, desc: 'str | None' = None, silent: 'bool' = False, start_delay: 'float' = 10) -> 'ShowProgress[T]'
suppress_stderr() -> 'Iterator[None]'
DATA
__all__ = ['delta_minimization_order', 'hclust', 'hclust_ordering', 'p...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\shap\utils\__init__.py
shap.violin_plot
Python Library Documentation: function violin in module shap.plots._violin
violin(shap_values, features=None, feature_names=None, max_display=None, plot_type='violin', color=None, axis_color='#333333', title=None, alpha=1, show=True, sort=True, color_bar=True, plot_size='auto', layered_violin_max_num_bins=20, class_names=None, class_inds=None, color_bar_label='Feature value', cmap=<matplotlib.colors.LinearSegmentedColormap object at 0x00000213EEBFD820>, color_bar_label_size=12, color_bar_tick_size=11, axhline_lw=0.5, use_log_scale=False)
Create a SHAP violin plot, colored by feature values when they are provided.
Parameters
----------
shap_values : Explanation or numpy.ndarray
For single output explanations, this is a matrix of SHAP values (# samples x # features).
features : numpy.ndarray or pandas.DataFrame or list, optional
Matrix of feature values (# samples x # features), or a ``feature_names`` list as shorthand.
feature_names : list, optional
Names of the features (length: # features).
max_display : int, optional
How many top features to include in the plot (default is 20).
plot_type : {"violin", "layered_violin"}, optional
What type of summary plot to produce. A "layered_violin" plot shows the
distribution of the SHAP values of each variable. A "violin" plot is the same,
except with outliers drawn as scatter points.
color : str or None, optional
Color or colormap to use for the plot. If None, a default is chosen.
axis_color : str, optional
Color for the plot axes.
title : str or None, optional
Plot title (currently unused).
alpha : float, optional
Opacity of the plot elements.
show : bool, optional
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further after it has been created.
sort : bool, optional
Whether to sort features by the sum of their effect magnitudes.
color_bar : bool, optional
Whether to draw the color bar (legend).
plot_size : {"auto", float, (float, float), None}, optional
What size to make the plot. By default, the size is auto-scaled based on the number of
features that are being displayed. Passing a single float will cause each row to be that
many inches high. Passing a pair of floats will scale the plot by that
number of inches. If ``None`` is passed, then the size of the current figure will be left
unchanged.
layered_violin_max_num_bins : int, optional
Maximum number of bins for layered violin plots.
color_bar_label : str, optional
Label for the color bar.
cmap : str or Colormap, optional
Colormap to use for coloring points by feature value.
color_bar_label_size : int, optional
Font size for the color bar label. Default is 11.
color_bar_tick_size : int, optional
Font size for the color bar ticks. Default is 11.
axhline_lw : float, optional
Line width for horizontal lines in the plot.
use_log_scale : bool, optional
Whether to use a symmetric log scale for the x-axis.
Examples
--------
See `violin plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/violin.html>`_.
shap.waterfall_plot
Python Library Documentation: function waterfall in module shap.plots._waterfall
waterfall(shap_values, max_display=10, show=True)
Plots an explanation of a single prediction as a waterfall plot.
The SHAP value of a feature represents the impact of the evidence provided by that feature on the model's
output. The waterfall plot is designed to visually display how the SHAP values (evidence) of each feature
move the model output from our prior expectation under the background data distribution, to the final model
prediction given the evidence of all the features.
Features are sorted by the magnitude of their SHAP values with the smallest
magnitude features grouped together at the bottom of the plot when the number of
features in the models exceeds the ``max_display`` parameter.
Parameters
----------
shap_values : Explanation
A one-dimensional :class:`.Explanation` object that contains the feature values and SHAP values to plot.
max_display : int
The maximum number of features to display (default is 10).
show : bool
Whether :external+mpl:func:`matplotlib.pyplot.show()` is called before returning.
Setting this to ``False`` allows the plot to be customized further after it
has been created, returning the current axis via plt.gca().
Examples
--------
See `waterfall plot examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/plots/waterfall.html>`_.