fairscoring.metrics.roc
=======================

.. py:module:: fairscoring.metrics.roc

.. autoapi-nested-parse::

   ROC-Base metrics.



Classes
-------

.. autoapisummary::

   fairscoring.metrics.roc.ROCBiasMetric


Module Contents
---------------

.. py:class:: ROCBiasMetric(name, bias_type)

   Bases: :py:obj:`fairscoring.metrics.base.TwoGroupMetric`


   ROC-Based Fairness Metrics.

   These metrics compute the absolute between ROC area (ABROCA) of two roc-curve [VoBC21]_.
   The following two metrics can be distinguished:

   `roc`
       Compares the classic roc-curves of two groups with each other.

   `xroc`
       Builds roc curves with class 0 samples from one group and class 1 samples from the other group.

   This metric returns a :class:`~fairscoring.metrics.base.TwoGroupBiasResult` object, which allows to split
   the bias in positive and negative parts.

   :param name: Name of the metric.
   :type name: str
   :param bias_type:
   :type bias_type: {"roc", "xroc"}

   .. rubric:: Notes

   This metric is not influenced by monotonic score transformations.
   For this reason, no `score_transform` parameter is provided.


   .. py:method:: bias(scores, target, attribute, groups, favorable_target, *, min_score = None, max_score = None, n_permute = None, seed = None, prefer_high_scores = True)

      Bias computation

      :param scores: A list of scores
      :type scores: ArrayLike
      :param target: The binary target values. Must have the same length as `scores`.
      :type target: ArrayLike
      :param attribute: The protected attribute. Must have the same length as `scores`.
      :type attribute: ndarray
      :param groups: A list of groups. Each group is given by a value of the protected attribute.
                     A value of `None` is used to define a group with all elements that are not in another group.
      :type groups: list
      :param favorable_target: The favorable outcome
      :type favorable_target: str or int
      :param min_score: The minimal score. This might influence the bias computation, e.g. by defining the integral bounds.
                        This is also used for rescaling.
      :type min_score: float
      :param max_score: The maximal score. This might influence the bias computation, e.g. by defining the integral bounds.
                        This is also used for rescaling
      :type max_score: float
      :param n_permute: Number of iterations for the permutation test.
                        Permutation tests are only performed if this value is `>0`.
      :type n_permute: int, optional
      :param prefer_high_scores: Specify whether high scores or low scores are favorable.
      :type prefer_high_scores: bool, optional

      :returns: **bias** -- The computed bias (including intermediate results)
      :rtype: BiasResult

      :param seed: Random seed for the permutation test.
                   Only required if the result need to be 100% reproducible.
      :type seed: int, optional



   .. py:method:: __call__(scores, target, attribute, groups, favorable_target, *, min_score = None, max_score = None, prefer_high_scores = True)

      Bias computation.

      This method allows to use the bias metric as a function.

      :param scores: A list of scores
      :type scores: ArrayLike
      :param target: The binary target values. Must have the same length as `scores`.
      :type target: ArrayLike
      :param attribute: The protected attribute. Must have the same length as `scores`.
      :type attribute: ndarray
      :param groups: A list of groups. Each group is given by a value of the protected attribute.
                     A value of `None` is used to define a group with all elements that are not in another group.
      :type groups: list
      :param favorable_target: The favorable outcome
      :type favorable_target: str or int
      :param min_score: The minimal score. This might influence the bias computation, e.g. by defining the integral bounds.
                        This is also used for rescaling.
      :type min_score: float
      :param max_score: The maximal score. This might influence the bias computation, e.g. by defining the integral bounds.
                        This is also used for rescaling
      :type max_score: float
      :param prefer_high_scores: Specify whether high scores or low scores are favorable.
      :type prefer_high_scores: bool, optional

      :returns: **bias** -- The computed bias.
      :rtype: float

      .. rubric:: Notes

      This method offers fewer parameters than :meth:`~fairscoring.metrics._base.BaseBiasMetric.bias`,
      because not all will affect the pure bias value.