class_docstr: Pickier version of MetricFrame.
  
  This holds the internal result from a disaggregated metric
  computation, and provides `apply_grouping()` (to cover min
  and max), `difference()` and `ratio()` methods.
  
  The main difference to the results computed by MetricFrame
  is that no account is made of whether the user supplied
  a bare function or a dictionary. Hence the results are
  always Series or DataFrame.
  
  Parameters
  ----------
  overall: Series or DataFrame
      The metric function(s) computed on the entire dataset, split by
      control features if supplied
  by_group: Series or DataFrame
      The metric function(s) computed on each subgroup identified by
      the sensitive and control features
class_docstr_tok: ["Pickier","version","of","MetricFrame",".","This","holds","the","internal","result","from","a","disaggregated","metric","computation",",","and","provides","`","apply_grouping","(",")","`","(","to","cover","min","and","max",")",",","`","difference","(",")","`","and","`","ratio","(",")","`","methods",".","The","main","difference","to","the","results","computed","by","MetricFrame","is","that","no","account","is","made","of","whether","the","user","supplied","a","bare","function","or","a","dictionary",".","Hence","the","results","are","always","Series","or","DataFrame",".","Parameters","--","--","--","--","--","overall",":","Series","or","DataFrame","The","metric","function","(","s",")","computed","on","the","entire","dataset",",","split","by","control","features","if","supplied","by_group",":","Series","or","DataFrame","The","metric","function","(","s",")","computed","on","each","subgroup","identified","by","the","sensitive","and","control","features"]
docstr: Manufacture a DisaggregatedResult.
  
  This is essentially a more restricted version of the MetricFrame
  constructor.
  
  All of the `data` have to be supplied as a DataFrame.
  The metric functions have to be supplied as a dictionary of
  AnnotatedMetricFunction.
  The latter class contains the metric function itself, and
  mappings between the metric function arguments and the columns
  of the `data` DataFrame.
  The sensitive and (optional) control features are lists of
  column names in `data`.
  
  Parameters
  ----------
  data : DataFrame
      A DataFrame containing all of the columns required to compute the metrics
  annotated_functions: Dict[str, AnnotatedMetricFunction]
      A dictionary of metric functions, each of which is annotated with the
      mapping of columns in `data` to argument names in the function
  sensitive_feature_names: List[str]
      The list of columns in `data` which correspond to the sensitive feature(s)
  control_feature_names: Optional[List[str]]
      Optional list of columns in `data` which correspond to the control features,
      if any
  
  Returns
  -------
  DisaggregatedResult
      Freshly constructed instance of this class
docstr_tok: ["Manufacture","a","DisaggregatedResult",".","This","is","essentially","a","more","restricted","version","of","the","MetricFrame","constructor",".","All","of","the","`","data","`","have","to","be","supplied","as","a","DataFrame",".","The","metric","functions","have","to","be","supplied","as","a","dictionary","of","AnnotatedMetricFunction",".","The","latter","class","contains","the","metric","function","itself",",","and","mappings","between","the","metric","function","arguments","and","the","columns","of","the","`","data","`","DataFrame",".","The","sensitive","and","(","optional",")","control","features","are","lists","of","column","names","in","`","data","`",".","Parameters","--","--","--","--","--","data",":","DataFrame","A","DataFrame","containing","all","of","the","columns","required","to","compute","the","metrics","annotated_functions",":","Dict","[","str",",","AnnotatedMetricFunction","]","A","dictionary","of","metric","functions",",","each","of","which","is","annotated","with","the","mapping","of","columns","in","`","data","`","to","argument","names","in","the","function","sensitive_feature_names",":","List","[","str","]","The","list","of","columns","in","`","data","`","which","correspond","to","the","sensitive","feature","(","s",")","control_feature_names",":","Optional","[","List","[","str","]","]","Optional","list","of","columns","in","`","data","`","which","correspond","to","the","control","features",",","if","any","Returns","--","--","--","-","DisaggregatedResult","Freshly","constructed","instance","of","this","class"]
code: def create(
      *,
      data: pd.DataFrame,
      annotated_functions: Dict[str, AnnotatedMetricFunction],
      sensitive_feature_names: List[str],
      control_feature_names: Optional[List[str]],
  ) -> "DisaggregatedResult":
      """Manufacture a DisaggregatedResult.
  
      This is essentially a more restricted version of the MetricFrame
      constructor.
  
      All of the `data` have to be supplied as a DataFrame.
      The metric functions have to be supplied as a dictionary of
      AnnotatedMetricFunction.
      The latter class contains the metric function itself, and
      mappings between the metric function arguments and the columns
      of the `data` DataFrame.
      The sensitive and (optional) control features are lists of
      column names in `data`.
  
      Parameters
      ----------
      data : DataFrame
          A DataFrame containing all of the columns required to compute the metrics
      annotated_functions: Dict[str, AnnotatedMetricFunction]
          A dictionary of metric functions, each of which is annotated with the
          mapping of columns in `data` to argument names in the function
      sensitive_feature_names: List[str]
          The list of columns in `data` which correspond to the sensitive feature(s)
      control_feature_names: Optional[List[str]]
          Optional list of columns in `data` which correspond to the control features,
          if any
  
      Returns
      -------
      DisaggregatedResult
          Freshly constructed instance of this class
      """
      # Calculate the 'overall' values
      if control_feature_names is None:
          overall = apply_to_dataframe(
              data, metric_functions=annotated_functions
          )
      else:
          temp = data.groupby(by=control_feature_names).apply(
              apply_to_dataframe, metric_functions=annotated_functions
          )
          # If there are multiple control features, might have missing combinations
          if len(control_feature_names) > 1:
              cf_classes = extract_unique_classes(
                  data, control_feature_names
              )
              all_indices = pd.MultiIndex.from_product(
                  cf_classes.values(), names=cf_classes.keys()
              )
  
              overall = temp.reindex(index=all_indices)
          else:
              overall = temp
  
      # Calculate the 'by_group' values
      all_grouping_names = [x for x in sensitive_feature_names]
      if control_feature_names is not None:
          # Note that we prepend the control feature names
          all_grouping_names = (
              control_feature_names + all_grouping_names
          )
  
      temp = data.groupby(all_grouping_names).apply(
          apply_to_dataframe, metric_functions=annotated_functions
      )
      if len(all_grouping_names) > 1:
          # We might have missing combinations in the input, so expand to fill
          all_classes = extract_unique_classes(data, all_grouping_names)
          all_indices = pd.MultiIndex.from_product(
              all_classes.values(),
              names=all_classes.keys(),
          )
  
          by_group = temp.reindex(index=all_indices)
      else:
          by_group = temp
  
      return DisaggregatedResult(overall, by_group)
  
file_path: fairlearn/fairlearn/metrics/_disaggregated_result.py
imports: import logging
  from typing import Dict, List, Optional, Union
  import numpy
  import pandas
  from ._annotated_metric_function import AnnotatedMetricFunction
label_desc: Use image node_id 7 for calling the DisaggregatedResult obj's underlying member method code with example usage: obj.create() and returns: DisaggregatedResult