class_docstr: 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.
class_docstr_tok: ["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","."]
docstr: 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.
docstr_tok: ["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","."]
code: def __init__(
      self,
      model,
      masker,
      link=links.identity,
      feature_names=None,
      linearize_link=True,
      seed=None,
      **call_args,
  ):
      """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.
      """
  
      # setting seed for random generation: if seed is not None, then shap values computation should be reproducible
      np.random.seed(seed)
  
      if masker is None:
          raise ValueError("masker cannot be None.")
  
      super().__init__(
          model,
          masker,
          link=link,
          linearize_link=linearize_link,
          feature_names=feature_names,
      )
  
      if not isinstance(self.model, Model):
          self.model = Model(self.model)
  
      # 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:
          # this signature should match the __call__ signature of the class defined below
          class PermutationExplainer(self.__class__):
              def __call__(
                  self,
                  *args,
                  max_evals=500,
                  main_effects=False,
                  error_bounds=False,
                  batch_size="auto",
                  outputs=None,
                  silent=False,
              ):
                  return super().__call__(
                      *args,
                      max_evals=max_evals,
                      main_effects=main_effects,
                      error_bounds=error_bounds,
                      batch_size=batch_size,
                      outputs=outputs,
                      silent=silent,
                  )
  
          PermutationExplainer.__call__.__doc__ = (
              self.__class__.__call__.__doc__
          )
          self.__class__ = PermutationExplainer
          for k, v in call_args.items():
              self.__call__.__kwdefaults__[k] = v
  
file_path: shap/shap/explainers/_permutation.py
imports: import warnings
  import numpy
  from ..None import links
  from ..models import Model
  from ..utils import MaskedModel, partition_tree_shuffle
  from ._explainer import Explainer
label_desc: Use image node_id 1 to create a new PermutationExplainer object from inherited base classes: Explainer with example: obj = PermutationExplainer(model, masker, link, feature_names, linearize_link, seed)