kernelshap_image
================

.. py:module:: kernelshap_image


Classes
-------

.. autoapisummary::

   kernelshap_image.KERNELSHAPImage


Functions
---------

.. autoapisummary::

   kernelshap_image._create_heatemaps


Module Contents
---------------

.. py:class:: KERNELSHAPImage(axis_labels=None, preprocess_function=None)

   Kernel SHAP implementation based on shap https://github.com/slundberg/shap.


   .. py:attribute:: preprocess_function


   .. py:attribute:: axis_labels


   .. py:attribute:: onnx_to_tf


   .. py:method:: _segment_image(image, n_segments, compactness, sigma, **kwargs)
      :staticmethod:


      Create segmentation to explain by segment, not every pixel.

      This could help speed-up the calculation when the input size is very large.

      This function segments image using k-means clustering in Color-(x,y,z) space. It uses
      scikit-image.

      :param image: Input image to be segmented.
      :type image: np.ndarray
      :param n_segments: The (approximate) number of labels in the segmented output image
      :type n_segments: int
      :param compactness: Balances color proximity and space proximity.
      :type compactness: int
      :param sigma: Width of Gaussian smoothing kernel
      :type sigma: float
      :param kwargs: These keyword parameters are passed on

      :returns: integer mask indicating segment labels with the shape of the input image.
                the number of segments is less than or equal to n_segments.

      Check keyword arguments for the skimage.segmentation.slic function
      via the following link:
      https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic



   .. py:method:: explain(model_or_function, input_data, labels, nsamples='auto', background=None, n_segments=100, compactness=10.0, sigma=0, **kwargs)

      Run the KernelSHAP explainer.

      The model will be called with the function of image segmentation.

      :param model_or_function: The path to a ONNX model on disk.
      :type model_or_function: str
      :param input_data: Data to be explained. It is mandatory to only
                         provide a single example as input. This is because
                         KernelShap is generally used for sample-based
                         interpretability, training a separate interpretable
                         model to explain a model prediction on each individual
                         example. The input dimension must be
                         [batch, height, width, color_channels] or
                         [batch, color_channels, height, width] (see axis_labels)
      :type input_data: np.ndarray
      :param labels: Indices of classes to be explained
      :type labels: Iterable(int)
      :param nsamples: 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`
      :type nsamples: "auto" or int
      :param background: Background color for the masked image
      :type background: int
      :param n_segments: The (approximate) number of labels in the segmented output image
      :type n_segments: int
      :param compactness: Balances color proximity and space proximity. Higher values give
                          more weight to space proximity, making superpixel shapes more
                          square/cubic.
      :type compactness: int
      :param sigma: Width of Gaussian smoothing kernel for pre-processing for
                    each dimension of the image. Zero means no smoothing.
      :type sigma: float
      :param kwargs: These keyword parameters are passed on

      Other keyword arguments: see the documentation of kernel explainer of SHAP
                               (also in function "shap_values") via:
      https://github.com/slundberg/shap/blob/master/shap/explainers/_kernel.py
                               and the documentation of image segmentation via:
      https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic

      :returns: Explanation heatmap of Shapley values for each class (np.ndarray).



   .. py:method:: _prepare_image_data(input_data)

      Transforms the data to be of the shape and type KernelSHAP expects.

      :param input_data: Data to be explained
      :type input_data: NumPy-compatible array

      :returns: transformed input data



   .. py:method:: _mask_image(features, segmentation, image, background=None, channels_axis_index=2, datatype=np.float32)

      Define a function that depends on a binary mask representing if an image region is hidden.

      :param features: A matrix of samples (# samples x # features)
                       on which to explain the model's output.
      :type features: np.ndarray
      :param segmentation: Image segmentations generated by
                           the function _segment_image
      :type segmentation: np.ndarray
      :param image: Image to be explained
      :type image: np.ndarray
      :param background: Background color for the masked image
      :type background: int
      :param channels_axis_index: See the function _prepare_image_data
      :type channels_axis_index: int
      :param datatype: Datatype for the returned value
      :type datatype: np.dtype



   .. py:method:: _runner(features)

      Define a runner/wrapper to load models and values.

      :param features: A matrix of samples (# samples x # features)
                       on which to explain the model's output.
      :type features: np.ndarray



.. py:function:: _create_heatemaps(shap_values_list, image_segments)

   Create heatmaps from the shap values and the image segments.

   The final heatmaps has a shape of (n_classes, *image_segments.shape).