class_docstr: 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.
class_docstr_tok: ["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","."]
docstr: 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>`_
docstr_tok: ["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",">","`","_"]
code: def __init__(
      self,
      model,
      masker,
      *,
      output_names=None,
      link=links.identity,
      linearize_link=True,
      feature_names=None,
      **call_args,
  ):
      """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>`_
      """
  
      super().__init__(
          model,
          masker,
          link=link,
          linearize_link=linearize_link,
          algorithm="partition",
          output_names=output_names,
          feature_names=feature_names,
      )
  
      # convert dataframes
      # if isinstance(masker, pd.DataFrame):
      #     masker = TabularMasker(masker)
      # elif isinstance(masker, np.ndarray) and len(masker.shape) == 2:
      #     masker = TabularMasker(masker)
      # elif safe_isinstance(masker, "transformers.PreTrainedTokenizer"):
      #     masker = TextMasker(masker)
      # self.masker = masker
  
      # TODO: maybe? if we have a tabular masker then we build a PermutationExplainer that we
      # will use for sampling
      self.input_shape = (
          masker.shape[1:]
          if hasattr(masker, "shape") and not callable(masker.shape)
          else None
      )
      # self.output_names = output_names
      if not safe_isinstance(self.model, "shap.models.Model"):
          self.model = Model(
              self.model
          )  # lambda *args: np.array(model(*args))
      self.expected_value = None
      self._curr_base_value = None
      if getattr(self.masker, "clustering", None) is None:
          raise ValueError(
              "The passed masker must have a .clustering attribute defined! Try shap.maskers.Partition(data) for example."
          )
      # if partition_tree is None:
      #     if not hasattr(masker, "partition_tree"):
      #         raise ValueError("The passed masker does not have masker.clustering, so the partition_tree must be passed!")
      #     self.partition_tree = masker.clustering
      # else:
      #     self.partition_tree = partition_tree
  
      # handle higher dimensional tensor inputs
      if self.input_shape is not None and len(self.input_shape) > 1:
          self._reshaped_model = lambda x: self.model(
              x.reshape(x.shape[0], *self.input_shape)
          )
      else:
          self._reshaped_model = self.model
  
      # if we don't have a dynamic clustering algorithm then can precowe mpute
      # a lot of information
      if not callable(self.masker.clustering):
          self._clustering = self.masker.clustering
          self._mask_matrix = make_masks(self._clustering)
  
      # if we have gotten default arguments for the call function we need to wrap ourselves in a new class that
      # has a call function with those new default arguments
      if len(call_args) > 0:
  
          class PartitionExplainer(self.__class__):
              # this signature should match the __call__ signature of the class defined below
              def __call__(
                  self,
                  *args,
                  max_evals=500,
                  fixed_context=None,
                  main_effects=False,
                  error_bounds=False,
                  batch_size="auto",
                  outputs=None,
                  silent=False,
              ):
                  return super().__call__(
                      *args,
                      max_evals=max_evals,
                      fixed_context=fixed_context,
                      main_effects=main_effects,
                      error_bounds=error_bounds,
                      batch_size=batch_size,
                      outputs=outputs,
                      silent=silent,
                  )
  
          PartitionExplainer.__call__.__doc__ = (
              self.__class__.__call__.__doc__
          )
          self.__class__ = PartitionExplainer
          for k, v in call_args.items():
              self.__call__.__kwdefaults__[k] = v
  
file_path: shap/shap/explainers/_partition.py
imports: import queue
  import time
  import numpy
  from numba import njit
  from tqdm.auto import tqdm
  from ..None import Explanation, links
  from ..models import Model
  from ..utils import MaskedModel, OpChain, make_masks, safe_isinstance
  from ._explainer import Explainer
label_desc: Use image node_id 1 to create a new PartitionExplainer object from inherited base classes: Explainer with example: obj = PartitionExplainer(model, masker)