docstr:  Produce plots and dataframes related to a single model fairness.
  
  :param frame: H2OFrame
  :param protected_columns: List of categorical columns that contain sensitive information
                            such as race, gender, age etc.
  :param reference: List of values corresponding to a reference for each protected columns.
                    If set to None, it will use the biggest group as the reference.
  :param favorable_class: Positive/favorable outcome class of the response.
  :param metrics: List of metrics to show.
  :param figsize: Figure size; passed directly to Matplotlib
  :param render: if ``True``, render the model explanations; otherwise model explanations are just returned.
  :param background_frame: optional frame, that is used as the source of baselines for the marginal SHAP.
                           Setting it enables calculating SHAP in more models but it can be more time and memory consuming. 
  :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 single man
  >>> favorable_class = "0"  # no default next month
  >>>
  >>> gbm = H2OGradientBoostingEstimator()
  >>> gbm.train(x, y, training_frame=train)
  >>>
  >>> gbm.inspect_model_fairness(test, protected_columns, reference, favorable_class)
docstr_tok: ["Produce","plots","and","dataframes","related","to","a","single","model","fairness",".",":","param","frame",":","H2OFrame",":","param","protected_columns",":","List","of","categorical","columns","that","contain","sensitive","information","such","as","race",",","gender",",","age","etc",".",":","param","reference",":","List","of","values","corresponding","to","a","reference","for","each","protected","columns",".","If","set","to","None",",","it","will","use","the","biggest","group","as","the","reference",".",":","param","favorable_class",":","Positive\/favorable","outcome","class","of","the","response",".",":","param","metrics",":","List","of","metrics","to","show",".",":","param","figsize",":","Figure","size",";","passed","directly","to","Matplotlib",":","param","render",":","if","``","True","``",",","render","the","model","explanations",";","otherwise","model","explanations","are","just","returned",".",":","param","background_frame",":","optional","frame",",","that","is","used","as","the","source","of","baselines","for","the","marginal","SHAP",".","Setting","it","enables","calculating","SHAP","in","more","models","but","it","can","be","more","time","and","memory","consuming",".",":","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","single","man",">",">",">","favorable_class","=","``","0","''","#","no","default","next","month",">",">",">",">",">",">","gbm","=","H2OGradientBoostingEstimator","(",")",">",">",">","gbm.train","(","x",",","y",",","training_frame=train",")",">",">",">",">",">",">","gbm.inspect_model_fairness","(","test",",","protected_columns",",","reference",",","favorable_class",")"]
code: def inspect_model_fairness(
      self,
      frame,
      protected_columns,
      reference,
      favorable_class,
      metrics=(
          "auc",
          "aucpr",
          "f1",
          "p.value",
          "selectedRatio",
          "total",
      ),
      figsize=(16, 9),
      render=True,
      background_frame=None,
  ):
      """
       Produce plots and dataframes related to a single model fairness.
  
      :param frame: H2OFrame
      :param protected_columns: List of categorical columns that contain sensitive information
                                such as race, gender, age etc.
      :param reference: List of values corresponding to a reference for each protected columns.
                        If set to None, it will use the biggest group as the reference.
      :param favorable_class: Positive/favorable outcome class of the response.
      :param metrics: List of metrics to show.
      :param figsize: Figure size; passed directly to Matplotlib
      :param render: if ``True``, render the model explanations; otherwise model explanations are just returned.
      :param background_frame: optional frame, that is used as the source of baselines for the marginal SHAP.
                               Setting it enables calculating SHAP in more models but it can be more time and memory consuming.
      :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 single man
      >>> favorable_class = "0"  # no default next month
      >>>
      >>> gbm = H2OGradientBoostingEstimator()
      >>> gbm.train(x, y, training_frame=train)
      >>>
      >>> gbm.inspect_model_fairness(test, protected_columns, reference, favorable_class)
      """
      import h2o
      from h2o.utils.shared_utils import can_use_numpy
  
      if not can_use_numpy():
          raise ImportError(
              "numpy is required for inspect_model_fairness."
          )
      from h2o.explanation import H2OExplanation
      from h2o.explanation import Description
      from h2o.explanation._explain import NumpyFrame
      from h2o.explanation._explain import (
          _display,
          _dont_display,
          Header,
          _is_tree_model,
      )
      from h2o.model.extensions import has_extension
      from h2o.plot import get_matplotlib_pyplot
      from h2o.utils.typechecks import assert_is_type
  
      assert_is_type(frame, h2o.H2OFrame)
      assert_is_type(protected_columns, [str])
      assert_is_type(reference, [str])
      assert_is_type(favorable_class, str)
      assert_is_type(metrics, [str], tuple)
      assert_is_type(figsize, tuple, list)
      assert_is_type(render, bool)
      assert_is_type(background_frame, None, h2o.H2OFrame)
  
      plt = get_matplotlib_pyplot(False, raise_if_not_available=True)
      fair = self.fairness_metrics(
          frame=frame,
          protected_columns=protected_columns,
          reference=reference,
          favorable_class=favorable_class,
      )
  
      reference_frame = frame
      for i, pc in enumerate(protected_columns):
          reference_frame = reference_frame[
              reference_frame[pc] == reference[i], :
          ]
  
      cols_to_show = sorted(
          list(
              set(metrics)
              .union({"AIR_{}".format(m) for m in metrics})
              .intersection(fair["overview"].columns)
          )
      )
      overview = fair["overview"]
  
      if render:
          display = _display
      else:
          display = _dont_display
  
      result = H2OExplanation()
      result["overview"] = H2OExplanation()
      result["overview"]["header"] = display(
          Header("Overview for model " + self.model_id)
      )
      result["overview"]["description"] = display(
          Description("fairness_metrics")
      )
      with local_context(rows=overview.nrow):
          result["overview"]["data"] = display(
              overview[:, protected_columns + cols_to_show]
          )
  
      groups = [
          ", ".join(r)
          for r in overview[:, protected_columns].as_data_frame(
              False, False
          )
      ]
      reference_name = ", ".join(reference)
      result["overview"]["plots"] = H2OExplanation()
      overview = NumpyFrame(overview)
      permutation = sorted(
          range(overview.nrow), key=lambda i: -overview[i, "auc"]
      )
  
      def _permute(x):
          return [x[i] for i in permutation]
  
      groups = _permute(groups)
      for col in cols_to_show:
          plt.figure(figsize=figsize)
          plt.title(col)
          if "AIR_" in col:
              plt.bar(
                  groups,
                  _permute([a - 1 for a in overview[col]]),
                  bottom=1,
              )
              plt.axhline(1, c="k")
              plt.axhline(0.8, c="gray", linestyle="dashed")
              plt.axhline(1.25, c="gray", linestyle="dashed")
          elif "p-value" in col:
              plt.bar(groups, _permute(overview[col]))
              plt.axhline(0.05, c="r")
              plt.axhspan(0, 0.05, color="r", alpha=0.1)
          else:
              plt.bar(
                  groups,
                  _permute(overview[col]),
                  color=[
                      "C1" if g == reference_name else "C0"
                      for g in groups
                  ],
              )
          plt.grid()
          plt.xticks(rotation=90)
          result["overview"]["plots"][col] = display(plt.gcf())
  
      # ROC
      result["ROC"] = H2OExplanation()
      result["ROC"]["header"] = display(Header("ROC"))
      result["ROC"]["description"] = display(
          Description("fairness_roc")
      )
      result["ROC"]["plot"] = display(
          self.fair_roc_plot(
              frame,
              protected_columns,
              reference,
              favorable_class,
              figsize=figsize,
          )
      )
  
      # PR
      result["PR"] = H2OExplanation()
      result["PR"]["header"] = display(Header("Precision-Recall Curve"))
      result["PR"]["description"] = display(Description("fairness_prc"))
      result["PR"]["plot"] = display(
          self.fair_pr_plot(
              frame,
              protected_columns,
              reference,
              favorable_class,
              figsize=figsize,
          )
      )
  
      # permutation varimp
      perm = self.permutation_importance(frame)
      result["permutation_importance"] = H2OExplanation()
      result["permutation_importance"]["header"] = display(
          Header("Permutation Variable Importance")
      )
      result["permutation_importance"]["description"] = display(
          Description("fairness_varimp")
      )
      result["permutation_importance"]["data"] = display(perm)
      sorted_features = list(perm["Variable"])
  
      # PDP per group
      result["pdp"] = H2OExplanation()
      result["pdp"]["header"] = display(
          Header(
              "Partial Dependence Plots for Individual Protected Groups"
          )
      )
      result["pdp"]["description"] = display(
          Description("fairness_pdp")
      )
      result["pdp"]["plots"] = H2OExplanation()
      for col in sorted_features:
          result["pdp"]["plots"][col] = display(
              self.fair_pd_plot(
                  frame, col, protected_columns, figsize=figsize
              )
          )
  
      # SHAP per group
      if has_extension(self, "Contributions") and (
          _is_tree_model(self) or background_frame is not None
      ):
          result["shap"] = H2OExplanation()
          result["shap"]["header"] = display(
              Header("SHAP for Individual Protected Groups")
          )
          result["shap"]["description"] = display(
              Description("fairness_shap")
          )
          result["shap"]["plots"] = H2OExplanation()
          for col in sorted_features:
              result["shap"]["plots"][col] = display(
                  self.fair_shap_plot(
                      frame,
                      col,
                      protected_columns,
                      figsize=figsize,
                      background_frame=background_frame,
                  )
              )
  
      return result
  
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 6 for calling the Fairness obj's underlying member method code with example usage: obj.inspect_model_fairness(frame, protected_columns, reference, favorable_class, metrics, figsize, render, background_frame) and returns: result, unknown