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: Return the minimum ratio between groups for each metric.
  
  This method calculates a scalar value for each underlying metric by
  finding the minimum ratio (that is, the ratio is forced to be
  less than unity) between the entries in each
  column of the :attr:`.by_group` property.
  
  There are two allowed values for the ``method=`` parameter. The
  value ``between_groups`` computes the minimum ratio between
  any two pairs of groups in the :attr:`.by_group` property (i.e.
  ``group_min() / group_max()``). Alternatively, ``to_overall``
  computes the ratio between each subgroup and the
  corresponding value from :attr:`.overall` (if there are control
  features, then :attr:`.overall` is multivalued for each metric),
  expressing the ratio as a number less than 1.
  The result is the minimum of these values.
  
  Parameters
  ----------
  method : str
      How to compute the aggregate. Default is :code:`between_groups`
  errors: {'raise', 'coerce'}, default 'coerce'
      if 'raise', then invalid parsing will raise an exception
      if 'coerce', then invalid parsing will be set as NaN
  
  Returns
  -------
  typing.Any or pandas.Series or pandas.DataFrame
docstr_tok: ["Return","the","minimum","ratio","between","groups","for","each","metric",".","This","method","calculates","a","scalar","value","for","each","underlying","metric","by","finding","the","minimum","ratio","(","that","is",",","the","ratio","is","forced","to","be","less","than","unity",")","between","the","entries","in","each","column","of","the",":","attr",":","`",".by_group","`","property",".","There","are","two","allowed","values","for","the","``","method=","``","parameter",".","The","value","``","between_groups","``","computes","the","minimum","ratio","between","any","two","pairs","of","groups","in","the",":","attr",":","`",".by_group","`","property","(","i.e",".","``","group_min","(",")","\/","group_max","(",")","``",")",".","Alternatively",",","``","to_overall","``","computes","the","ratio","between","each","subgroup","and","the","corresponding","value","from",":","attr",":","`",".overall","`","(","if","there","are","control","features",",","then",":","attr",":","`",".overall","`","is","multivalued","for","each","metric",")",",","expressing","the","ratio","as","a","number","less","than","1",".","The","result","is","the","minimum","of","these","values",".","Parameters","--","--","--","--","--","method",":","str","How","to","compute","the","aggregate",".","Default","is",":","code",":","`","between_groups","`","errors",":","{","'raise","'",",","'coerce","'","}",",","default","'coerce'","if","'raise","'",",","then","invalid","parsing","will","raise","an","exception","if","'coerce","'",",","then","invalid","parsing","will","be","set","as","NaN","Returns","--","--","--","-","typing.Any","or","pandas.Series","or","pandas.DataFrame"]
code: def ratio(
      self,
      control_feature_names: List[str],
      method: str = "between_groups",
      errors: str = "coerce",
  ) -> Union[pd.Series, pd.DataFrame]:
      """Return the minimum ratio between groups for each metric.
  
      This method calculates a scalar value for each underlying metric by
      finding the minimum ratio (that is, the ratio is forced to be
      less than unity) between the entries in each
      column of the :attr:`.by_group` property.
  
      There are two allowed values for the ``method=`` parameter. The
      value ``between_groups`` computes the minimum ratio between
      any two pairs of groups in the :attr:`.by_group` property (i.e.
      ``group_min() / group_max()``). Alternatively, ``to_overall``
      computes the ratio between each subgroup and the
      corresponding value from :attr:`.overall` (if there are control
      features, then :attr:`.overall` is multivalued for each metric),
      expressing the ratio as a number less than 1.
      The result is the minimum of these values.
  
      Parameters
      ----------
      method : str
          How to compute the aggregate. Default is :code:`between_groups`
      errors: {'raise', 'coerce'}, default 'coerce'
          if 'raise', then invalid parsing will raise an exception
          if 'coerce', then invalid parsing will be set as NaN
  
      Returns
      -------
      typing.Any or pandas.Series or pandas.DataFrame
      """
  
      def ratio_sub_one(x):
          if x > 1:
              return 1 / x
          else:
              return x
  
      if errors not in _VALID_ERROR_STRING:
          raise ValueError(_INVALID_ERRORS_VALUE_ERROR_MESSAGE)
  
      result = None
      if method == "between_groups":
          result = self.apply_grouping(
              "min", control_feature_names, errors=errors
          ) / self.apply_grouping(
              "max", control_feature_names, errors=errors
          )
      elif method == "to_overall":
          ratios = None
  
          if control_feature_names is not None:
              # It's easiest to give in to the DataFrame columns preference
              ratios = self.by_group.unstack(
                  level=control_feature_names
              ) / self.overall.unstack(level=control_feature_names)
          else:
              ratios = self.by_group / self.overall
  
          ratios = ratios.apply(lambda x: x.transform(ratio_sub_one))
          if not control_feature_names:
              result = ratios.min()
          else:
              result = ratios.min().unstack(0)
      else:
          raise ValueError(
              "Unrecognised method '{0}' in ratio() call".format(method)
          )
  
      assert isinstance(result, pd.Series) or isinstance(
          result, pd.DataFrame
      )
  
      return result
  
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 6 for calling the DisaggregatedResult obj's underlying member method code with example usage: obj.ratio(control_feature_names, method, errors) and returns: result, unknown, x