class_docstr_tok: []
docstr: Calculates disparities between groups for the predefined list of group
  metrics using a predefined reference group (denominator) value for each
  attribute.
  
  :param df: output dataframe of Group class get_crosstabs() method.
  :param original_df: dataframe of sample features and model results.
      Includes a required 'score 'column and possible 'label_value' column.
  :param ref_groups_dict: dictionary of format: {'attribute_name': 'attribute_value', ...}
  :param key_columns: optional, key identifying columns for grouping
      variables and bias metrics in intermediate joins. Defaults are
      'model_id', 'score_threshold', 'attribute_name'.
  :param input_group_metrics: optional, columns list corresponding to
      the group metrics for which we want to calculate disparity values
  :param fill_divbyzero: optional, fill value to use when divided by
      zero. Default is None.
  :param check_significance: whether to determine statistical signifance
      for disparity metrics. Default is False.
  :param selected_significance: specific measures (beyond label_value and
      score) to which to limit statistical significance calculations when
      check_significance is True. Default is False, i.e., significance
      will be calculated for all metrics.
  :param alpha: statistical significance level to use in significance
      determination. Default is 5e-2 (0.05).
  :param mask_significance: whether to display a T/F mask over calculated
      p-values from statistical significance determination. Default is True.
  :return: A dataframe with same number of rows as the input (crosstab)
      with additional disparity metrics columns and ref_group_values
      for each metric.
docstr_tok: ["Calculates","disparities","between","groups","for","the","predefined","list","of","group","metrics","using","a","predefined","reference","group","(","denominator",")","value","for","each","attribute",".",":","param","df",":","output","dataframe","of","Group","class","get_crosstabs","(",")","method",".",":","param","original_df",":","dataframe","of","sample","features","and","model","results",".","Includes","a","required","'score","'column","and","possible","'label_value","'","column",".",":","param","ref_groups_dict",":","dictionary","of","format",":","{","'attribute_name","'",":","'attribute_value","'",",","...","}",":","param","key_columns",":","optional",",","key","identifying","columns","for","grouping","variables","and","bias","metrics","in","intermediate","joins",".","Defaults","are","'model_id","'",",","'score_threshold","'",",","'attribute_name","'",".",":","param","input_group_metrics",":","optional",",","columns","list","corresponding","to","the","group","metrics","for","which","we","want","to","calculate","disparity","values",":","param","fill_divbyzero",":","optional",",","fill","value","to","use","when","divided","by","zero",".","Default","is","None",".",":","param","check_significance",":","whether","to","determine","statistical","signifance","for","disparity","metrics",".","Default","is","False",".",":","param","selected_significance",":","specific","measures","(","beyond","label_value","and","score",")","to","which","to","limit","statistical","significance","calculations","when","check_significance","is","True",".","Default","is","False",",","i.e.",",","significance","will","be","calculated","for","all","metrics",".",":","param","alpha",":","statistical","significance","level","to","use","in","significance","determination",".","Default","is","5e-2","(","0.05",")",".",":","param","mask_significance",":","whether","to","display","a","T\/F","mask","over","calculated","p-values","from","statistical","significance","determination",".","Default","is","True",".",":","return",":","A","dataframe","with","same","number","of","rows","as","the","input","(","crosstab",")","with","additional","disparity","metrics","columns","and","ref_group_values","for","each","metric","."]
code: def get_disparity_predefined_groups(
      self,
      df,
      original_df,
      ref_groups_dict,
      key_columns=None,
      input_group_metrics=None,
      fill_divbyzero=None,
      check_significance=False,
      alpha=5e-2,
      mask_significance=True,
      selected_significance=False,
  ):
      """
      Calculates disparities between groups for the predefined list of group
      metrics using a predefined reference group (denominator) value for each
      attribute.
  
      :param df: output dataframe of Group class get_crosstabs() method.
      :param original_df: dataframe of sample features and model results.
          Includes a required 'score 'column and possible 'label_value' column.
      :param ref_groups_dict: dictionary of format: {'attribute_name': 'attribute_value', ...}
      :param key_columns: optional, key identifying columns for grouping
          variables and bias metrics in intermediate joins. Defaults are
          'model_id', 'score_threshold', 'attribute_name'.
      :param input_group_metrics: optional, columns list corresponding to
          the group metrics for which we want to calculate disparity values
      :param fill_divbyzero: optional, fill value to use when divided by
          zero. Default is None.
      :param check_significance: whether to determine statistical signifance
          for disparity metrics. Default is False.
      :param selected_significance: specific measures (beyond label_value and
          score) to which to limit statistical significance calculations when
          check_significance is True. Default is False, i.e., significance
          will be calculated for all metrics.
      :param alpha: statistical significance level to use in significance
          determination. Default is 5e-2 (0.05).
      :param mask_significance: whether to display a T/F mask over calculated
          p-values from statistical significance determination. Default is True.
      :return: A dataframe with same number of rows as the input (crosstab)
          with additional disparity metrics columns and ref_group_values
          for each metric.
      """
      # record df column order
      original_cols = df.columns
  
      if not key_columns:
          key_columns = original_cols.intersection(
              self.key_columns
          ).tolist()
      if not input_group_metrics:
          input_group_metrics = self.input_group_metrics
      if not fill_divbyzero:
          fill_divbyzero = self.fill_divbyzero
  
      try:
          self._verify_ref_groups_dict_len(df, ref_groups_dict)
      except ValueError:
          raise ValueError(
              "Bias.get_disparity_predefined_groups(): the number of "
              "predefined group values to use as reference is less "
              "than the actual number of attributes in the input "
              "dataframe."
          )
  
      df_ref_group = pd.DataFrame()
      try:
          for key, val in ref_groups_dict.items():
              group_slice = df.loc[
                  (df["attribute_name"] == key)
                  & (df["attribute_value"] == val)
              ]
              self._verify_ref_group_loc(group_slice)
              df_ref_group = pd.concat([df_ref_group, group_slice])
      except KeyError:
          raise KeyError(
              "get_disparity_predefined_groups(): reference groups "
              "and values provided do not exist as columns/values "
              "in the input dataframe.(Note: check for syntax errors)"
          )
      except ValueError:
          raise ValueError(
              "get_disparity_predefined_groups(): reference groups "
              "and values provided do not exist as columns/values "
              "in the input dataframe.(Note: check for syntax errors)"
          )
  
      disparity_metrics = [
          col + "_disparity" for col in input_group_metrics
      ]
      df_to_merge = pd.DataFrame()
  
      # we created the df_to_merge has a subset of the df_ref_group containing
      # the target ref group values which are now labeled as _disparity but
      # we still need to perform the division
      df_to_merge[key_columns + disparity_metrics] = df_ref_group[
          key_columns + input_group_metrics
      ]
  
      # we now need to create the ref_group_value columns in the df_to_merge
      for col in input_group_metrics:
          df_to_merge[col + "_ref_group_value"] = df_ref_group[
              "attribute_value"
          ]
      df = df.merge(df_to_merge, on=key_columns)
      df[disparity_metrics] = df[input_group_metrics].divide(
          df[disparity_metrics].values
      )
  
      # We are capping the disparity values to 10.0 when divided by zero...
      df = df.replace(np.inf, fill_divbyzero)
      if not check_significance:
          return df
  
      else:
          if not selected_significance:
              selected_significance = self.input_group_metrics
  
          # only proceed with columns actually in dataframe
          selected_significance = set(
              original_cols.intersection(selected_significance)
          )
  
          # always includes label and score significance
          selected_significance = selected_significance.union(
              {"label_value", "score"}
          )
  
          # compile dictionary of reference groups based on bias-augmented crosstab
          full_ref_dict = {}
  
          # for predefined groups, use the largest of the predefined groups as
          # ref group for score and label value
          # key is an attribute_name, val is an attribute_value
          for key, val in ref_groups_dict.items():
              full_ref_dict[key] = {"label_value": val, "score": val}
              for measure in selected_significance:
                  full_ref_dict[key][measure] = val
  
          # run significance method on bias-augmented crosstab based on false
          # positives, false negatives, scores, and label values in original df
          self._get_statistical_significance(
              original_df,
              df,
              ref_dict=full_ref_dict,
              score_thresholds=None,
              attr_cols=None,
              alpha=5e-2,
              selected_significance=selected_significance,
          )
  
          # if specified, apply T/F mask to significance columns
          if mask_significance:
              significance_cols = df.columns[
                  df.columns.str.contains("_significance")
              ]
              truemask = df.loc[:, significance_cols] < alpha
              falsemask = df.loc[:, significance_cols] >= alpha
  
              df.loc[:, significance_cols] = np.select(
                  [truemask, falsemask], [True, False], default=None
              )
  
          # check what new disparity columns are and order as disparity,
          # ref_group, significance for each
          base_sig = ["label_value_significance", "score_significance"]
  
          new_cols = sorted(
              list(set(df.columns) - set(original_cols) - set(base_sig))
          )
  
          return df[original_cols.tolist() + base_sig + new_cols]
  
imports: import logging
  from aequitas.plotting import assemble_ref_groups
  import numpy
  import pandas
  from scipy import stats
label_desc: Use image node_id 6 for calling the Bias obj's underlying member method code with example usage: obj.get_disparity_predefined_groups(df, original_df, ref_groups_dict, key_columns, input_group_metrics, fill_divbyzero, check_significance, alpha, mask_significance, selected_significance) and returns: df, df