class_docstr: 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.
class_docstr_tok: ["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","."]
docstr: 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
  -------
  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. 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.
docstr_tok: ["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","--","--","--","-","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",".","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","."]
code: def 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, the limit of the original model
          is used (``None``). ``-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. 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.
      """
  
      assert (
          self.model.model_output == "raw"
      ), 'Only model_output = "raw" is supported for SHAP interaction values right now!'
      # assert self.feature_perturbation == "tree_path_dependent", "Only feature_perturbation = \"tree_path_dependent\" is supported for SHAP interaction values right now!"
      transform = "identity"
  
      # see if we have a default tree_limit in place.
      if tree_limit is None:
          tree_limit = (
              -1
              if self.model.tree_limit is None
              else self.model.tree_limit
          )
  
      # shortcut using the C++ version of Tree SHAP in XGBoost
      if (
          self.model.model_type == "xgboost"
          and self.feature_perturbation == "tree_path_dependent"
      ):
          import xgboost
  
          if not isinstance(X, xgboost.core.DMatrix):
              X = xgboost.DMatrix(X)
          if tree_limit == -1:
              tree_limit = 0
          xgb_tree_limit = tree_limit // self.model.num_stacked_models
          phi = self.model.original_model.predict(
              X,
              iteration_range=(0, xgb_tree_limit),
              pred_interactions=True,
              validate_features=False,
          )
  
          # note we pull off the last column and keep it as our expected_value
          if len(phi.shape) == 4:
              self.expected_value = [
                  phi[0, i, -1, -1] for i in range(phi.shape[1])
              ]
              return [phi[:, i, :-1, :-1] for i in range(phi.shape[1])]
          else:
              self.expected_value = phi[0, -1, -1]
              return phi[:, :-1, :-1]
  
      (
          X,
          y,
          X_missing,
          flat_output,
          tree_limit,
          _,
      ) = self._validate_inputs(X, y, tree_limit, False)
      # run the core algorithm using the C extension
      assert_import("cext")
      phi = np.zeros(
          (
              X.shape[0],
              X.shape[1] + 1,
              X.shape[1] + 1,
              self.model.num_outputs,
          )
      )
      _cext.dense_tree_shap(
          self.model.children_left,
          self.model.children_right,
          self.model.children_default,
          self.model.features,
          self.model.thresholds,
          self.model.values,
          self.model.node_sample_weight,
          self.model.max_depth,
          X,
          X_missing,
          y,
          self.data,
          self.data_missing,
          tree_limit,
          self.model.base_offset,
          phi,
          feature_perturbation_codes[self.feature_perturbation],
          output_transform_codes[transform],
          True,
      )
  
      return self._get_shap_interactions_output(phi, flat_output)
  
imports: import json
  import os
  import struct
  import time
  import warnings
  import numpy
  import pandas
  import scipy.sparse
  import scipy.special
  from packaging import version
  from ..None import maskers
  from .._explanation import Explanation
  from ..utils import assert_import, record_import_error, safe_isinstance
  from ..utils._exceptions import DimensionError, ExplainerError, InvalidFeaturePerturbationError, InvalidMaskerError, InvalidModelError
  from ..utils._legacy import DenseData
  from ._explainer import Explainer
label_desc: Use image node_id 7 for calling the TreeExplainer obj's underlying member method code with example usage: obj.shap_interaction_values(X, y, tree_limit) and returns: self, unknown, phi