fairscoring.metrics.calibration
===============================

.. py:module:: fairscoring.metrics.calibration

.. autoapi-nested-parse::

   A module to define the calibration bias metric.



Classes
-------

.. autoapisummary::

   fairscoring.metrics.calibration.CalibrationMetric


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

.. py:class:: CalibrationMetric(weighting = 'quantiles', n_bins = 50, name = 'Calibration', score_transform = None)

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


   This metric measures the differences between two calibration curves [BeDB24]_.

   Calibration is a way to measure sufficiency bias for continuous scores.
   The `weighting` parameter specifies how differences over the total score range are weighted.

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

   :param weighting: Integral over quantiles / scores
   :type weighting: ("quantiles", "scores")
   :param n_bins: Number of bins that are used to compute the calibration curves
   :type n_bins: int
   :param name: Name of metric.
   :type name: str, default="Calibration"
   :param score_transform: A transformation of the scores prior to the bias computation.
                           There are two supported methods:

                           - rescaling (to the interval `[0,1]`.
                             In this case, the :meth:`~fairscoring.metrics._calibration.CalibrationMetric.bias` method can take min and max scores.
                           - quantile transformation. This leads to standardized bias measures.
   :type score_transform: {"rescale","quantile",None}


   .. 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.