docstr: SHAP summary plot for one feature with protected groups on y-axis.
  
  :param frame: H2OFrame
  :param column: String containing column name.
  :param protected_columns: List of categorical columns that contain sensitive information
                            such as race, gender, age etc.
  :param category: Used to specify what category to inspect when categorical feature is one hot encoded, typically in XGBoost.
  :param autoscale: If ``True``, try to guess when to use log transformation on X axis.
  :param figsize: Tuple with figure size; passed directly to matplotlib.
  :param jitter: Amount of jitter used to show the point density.
  :param alpha: Transparency of the points.
  :param save_plot_path_prefix: A prefix of the path to save the plot via using matplotlib function savefig. 
                                The suffix of the path will be determined from a column name for which SHAP values
                                were calculated for.
  :background_frame: Optional frame, that is used as the source of baselines for the marginal SHAP.
  :return: H2OExplanation object
  
  :examples:
  >>> from h2o.estimators import H2OGradientBoostingEstimator
  >>> data = h2o.import_file("https://s3.amazonaws.com/h2o-public-test-data/smalldata/admissibleml_test/taiwan_credit_card_uci.csv")
  >>> x = ['LIMIT_BAL', 'AGE', 'PAY_0', 'PAY_2', 'PAY_3', 'PAY_4', 'PAY_5', 'PAY_6', 'BILL_AMT1', 'BILL_AMT2', 'BILL_AMT3',
  >>>      'BILL_AMT4', 'BILL_AMT5', 'BILL_AMT6', 'PAY_AMT1', 'PAY_AMT2', 'PAY_AMT3', 'PAY_AMT4', 'PAY_AMT5', 'PAY_AMT6']
  >>> y = "default payment next month"
  >>> protected_columns = ['SEX', 'EDUCATION']
  >>>
  >>> for c in [y] + protected_columns:
  >>>     data[c] = data[c].asfactor()
  >>>
  >>> train, test = data.split_frame([0.8])
  >>>
  >>> reference = ["1", "2"]  # university educated man
  >>> favorable_class = "0"  # no default next month
  >>>
  >>> gbm = H2OGradientBoostingEstimator()
  >>> gbm.train(x, y, training_frame=train)
  >>>
  >>> gbm.fair_shap_plot(test, "AGE", protected_columns)
docstr_tok: ["SHAP","summary","plot","for","one","feature","with","protected","groups","on","y-axis",".",":","param","frame",":","H2OFrame",":","param","column",":","String","containing","column","name",".",":","param","protected_columns",":","List","of","categorical","columns","that","contain","sensitive","information","such","as","race",",","gender",",","age","etc",".",":","param","category",":","Used","to","specify","what","category","to","inspect","when","categorical","feature","is","one","hot","encoded",",","typically","in","XGBoost",".",":","param","autoscale",":","If","``","True","``",",","try","to","guess","when","to","use","log","transformation","on","X","axis",".",":","param","figsize",":","Tuple","with","figure","size",";","passed","directly","to","matplotlib",".",":","param","jitter",":","Amount","of","jitter","used","to","show","the","point","density",".",":","param","alpha",":","Transparency","of","the","points",".",":","param","save_plot_path_prefix",":","A","prefix","of","the","path","to","save","the","plot","via","using","matplotlib","function","savefig",".","The","suffix","of","the","path","will","be","determined","from","a","column","name","for","which","SHAP","values","were","calculated","for",".",":","background_frame",":","Optional","frame",",","that","is","used","as","the","source","of","baselines","for","the","marginal","SHAP",".",":","return",":","H2OExplanation","object",":","examples",":",">",">",">","from","h2o.estimators","import","H2OGradientBoostingEstimator",">",">",">","data","=","h2o.import_file","(","``","https",":","\/\/s3.amazonaws.com\/h2o-public-test-data\/smalldata\/admissibleml_test\/taiwan_credit_card_uci.csv","''",")",">",">",">","x","=","[","'LIMIT_BAL","'",",","'AGE","'",",","'PAY_0","'",",","'PAY_2","'",",","'PAY_3","'",",","'PAY_4","'",",","'PAY_5","'",",","'PAY_6","'",",","'BILL_AMT1","'",",","'BILL_AMT2","'",",","'BILL_AMT3","'",",",">",">",">","'BILL_AMT4","'",",","'BILL_AMT5","'",",","'BILL_AMT6","'",",","'PAY_AMT1","'",",","'PAY_AMT2","'",",","'PAY_AMT3","'",",","'PAY_AMT4","'",",","'PAY_AMT5","'",",","'PAY_AMT6","'","]",">",">",">","y","=","``","default","payment","next","month","''",">",">",">","protected_columns","=","[","'SEX","'",",","'EDUCATION","'","]",">",">",">",">",">",">","for","c","in","[","y","]","+","protected_columns",":",">",">",">","data","[","c","]","=","data","[","c","]",".asfactor","(",")",">",">",">",">",">",">","train",",","test","=","data.split_frame","(","[","0.8","]",")",">",">",">",">",">",">","reference","=","[","``","1","''",",","``","2","''","]","#","university","educated","man",">",">",">","favorable_class","=","``","0","''","#","no","default","next","month",">",">",">",">",">",">","gbm","=","H2OGradientBoostingEstimator","(",")",">",">",">","gbm.train","(","x",",","y",",","training_frame=train",")",">",">",">",">",">",">","gbm.fair_shap_plot","(","test",",","``","AGE","''",",","protected_columns",")"]
code: def fair_shap_plot(
      self,
      frame,
      column,
      protected_columns,
      autoscale=True,
      figsize=(16, 9),
      jitter=0.35,
      alpha=1,
      save_plot_path_prefix=None,
      background_frame=None,
  ):
      """
      SHAP summary plot for one feature with protected groups on y-axis.
  
      :param frame: H2OFrame
      :param column: String containing column name.
      :param protected_columns: List of categorical columns that contain sensitive information
                                such as race, gender, age etc.
      :param category: Used to specify what category to inspect when categorical feature is one hot encoded, typically in XGBoost.
      :param autoscale: If ``True``, try to guess when to use log transformation on X axis.
      :param figsize: Tuple with figure size; passed directly to matplotlib.
      :param jitter: Amount of jitter used to show the point density.
      :param alpha: Transparency of the points.
      :param save_plot_path_prefix: A prefix of the path to save the plot via using matplotlib function savefig.
                                    The suffix of the path will be determined from a column name for which SHAP values
                                    were calculated for.
      :background_frame: Optional frame, that is used as the source of baselines for the marginal SHAP.
      :return: H2OExplanation object
  
      :examples:
      >>> from h2o.estimators import H2OGradientBoostingEstimator
      >>> data = h2o.import_file("https://s3.amazonaws.com/h2o-public-test-data/smalldata/admissibleml_test/taiwan_credit_card_uci.csv")
      >>> x = ['LIMIT_BAL', 'AGE', 'PAY_0', 'PAY_2', 'PAY_3', 'PAY_4', 'PAY_5', 'PAY_6', 'BILL_AMT1', 'BILL_AMT2', 'BILL_AMT3',
      >>>      'BILL_AMT4', 'BILL_AMT5', 'BILL_AMT6', 'PAY_AMT1', 'PAY_AMT2', 'PAY_AMT3', 'PAY_AMT4', 'PAY_AMT5', 'PAY_AMT6']
      >>> y = "default payment next month"
      >>> protected_columns = ['SEX', 'EDUCATION']
      >>>
      >>> for c in [y] + protected_columns:
      >>>     data[c] = data[c].asfactor()
      >>>
      >>> train, test = data.split_frame([0.8])
      >>>
      >>> reference = ["1", "2"]  # university educated man
      >>> favorable_class = "0"  # no default next month
      >>>
      >>> gbm = H2OGradientBoostingEstimator()
      >>> gbm.train(x, y, training_frame=train)
      >>>
      >>> gbm.fair_shap_plot(test, "AGE", protected_columns)
      """
      import h2o
      from h2o.utils.shared_utils import can_use_numpy
  
      if not can_use_numpy():
          raise ImportError("numpy is required for fair_shap_plot.")
      import numpy as np
      from h2o.explanation._explain import no_progress_block
      from h2o.explanation import H2OExplanation
      from h2o.explanation._explain import NumpyFrame
      from h2o.explanation._explain import _density
      from h2o.utils.typechecks import assert_is_type
  
      assert_is_type(frame, h2o.H2OFrame)
      assert_is_type(column, str)
      assert_is_type(protected_columns, [str])
      assert_is_type(figsize, tuple, list)
      assert_is_type(jitter, float)
      assert_is_type(alpha, float, int)
      assert_is_type(autoscale, bool)
      assert_is_type(background_frame, None, h2o.H2OFrame)
  
      from h2o.plot import get_matplotlib_pyplot
  
      plt = get_matplotlib_pyplot(False, raise_if_not_available=True)
      pgs = product(
          *[
              frame[col].unique()["C1"].as_data_frame(False, False)
              for col in protected_columns
          ]
      )
      results = defaultdict(list)
      maxes = []
      contr_columns = [column]
      with no_progress_block():
          for pg in pgs:
              pg = [p[0] for p in pg]
              filtered_hdf = frame
              for i in range(len(protected_columns)):
                  filtered_hdf = filtered_hdf[
                      filtered_hdf[protected_columns[i]] == pg[i], :
                  ]
              if filtered_hdf.nrow == 0:
                  continue
              cont = NumpyFrame(
                  self.predict_contributions(
                      filtered_hdf,
                      output_format="compact",
                      background_frame=background_frame,
                  )
              )
              vals = NumpyFrame(filtered_hdf)[column]
              if not np.all(np.isnan(vals)):
                  maxes.append(np.nanmax(vals))
              if len(contr_columns) == 1 and all(
                  (c not in cont.columns for c in contr_columns)
              ):
                  contr_columns = [
                      c
                      for c in cont.columns
                      if c.startswith("{}.".format(contr_columns[0]))
                  ]
              for cc in contr_columns:
                  results[cc].append((pg, cont[cc], vals))
      maxes = np.array(maxes) - np.min(maxes) + 1
      autoscale = (
          autoscale
          and not frame[column].isfactor()[0]
          and frame[column].min() > -1
          and (
              np.nanmax(np.log(maxes)) - np.nanmin(np.log(maxes)) > 1
          ).all()
      )
      plots = H2OExplanation()
      for contr_column, result in results.items():
          plt.figure(figsize=figsize)
          for i, (pg, contr, vals) in enumerate(result):
              if not np.any(np.isfinite(vals)) or np.nanmin(
                  vals
              ) == np.nanmax(vals):
                  plt.scatter(
                      0, i, label=", ".join(pg), alpha=alpha, c="grey"
                  )
                  continue  # constant variable; plotting it can throw StopIteration in some versions of matplotlib
              indices = np.arange(len(contr))
              np.random.shuffle(indices)
              contr = contr[indices]
              vals = vals[indices]
              dens = _density(contr)
              plt.scatter(
                  x=contr,
                  y=i
                  + dens
                  * np.random.uniform(-jitter, jitter, size=len(contr)),
                  label=", ".join(pg),
                  alpha=alpha,
                  c=np.log1p(vals) if autoscale else vals,
              )
          plt.axvline(x=0, c="k")
          plt.title("SHAP Contributions for {}".format(contr_column))
          plt.xlabel("Contribution of {}".format(contr_column))
          plt.ylabel("Sensitive Features")
          plt.yticks(
              range(len(result)), [", ".join(pg) for pg, _, _ in result]
          )
          plt.grid()
          plt.colorbar().set_label(
              "log({})".format(contr_column)
              if autoscale
              else contr_column
          )
          if save_plot_path_prefix is not None:
              plt.savefig(
                  fname=save_plot_path_prefix + "_" + contr_column
              )
          plots[contr_column] = plt.gcf()
      return plots
  
file_path: h2o-3/h2o-py/h2o/model/extensions/fairness.py
imports: from collections import defaultdict
  from itertools import product
  from h2o.utils.threading import local_context
label_desc: Use image node_id 5 for calling the Fairness obj's underlying member method code with example usage: obj.fair_shap_plot(frame, column, protected_columns, autoscale, figsize, jitter, alpha, save_plot_path_prefix, background_frame) and returns: plots