fairscoring.plots
=================

.. py:module:: fairscoring.plots

.. autoapi-nested-parse::

   Plots to visualize and analyze different bias metrics



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/fairscoring/plots/colors/index


Functions
---------

.. autoapisummary::

   fairscoring.plots.plot_groupwise_score_calibration
   fairscoring.plots.plot_groupwise_cdfs
   fairscoring.plots.plot_cdf_diffs


Package Contents
----------------

.. py:function:: plot_groupwise_score_calibration(scores, target, attribute, groups, favorable_target, *, ax = None, palette = sns.color_palette(), n_bins = 20, n_bootstrap = 10, rescale = True, rescale_by = None, prefer_high_scores = True, strategy = 'uniform')

   Plot groupwise score calibration.
   Calibration plots. Optional with bootstrap curves.

   :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 ax: The axes into which the calibration curves shall be plotted
   :type ax: matplotlib.axes.Axes, optional
   :param palette: Color palette, number of colors must at least be number of groups
   :type palette: list or Colormap, Optional
   :param n_bins: (Maximal) number of bins
   :type n_bins: int, Default=20
   :param n_bootstrap: Number of bootstrap samples; can be slow for large datasets.
                       Set to `None`, to disable bootstrapping.
   :type n_bootstrap: int, optional, Default=10
   :param rescale_by: Maximum and minimum possible score value for rescaling. If None, the minimum and maximum from the data are used.
   :type rescale_by: List, optional
   :param rescale: True if the values are rescaled.
   :type rescale: bool, default=True
   :param prefer_high_scores: Specify whether high scores or low scores are favorable.
   :type prefer_high_scores: bool, optional

   :param strategy: Strategy to determine bins
   :type strategy: {'uniform', 'quantiles'}

   .. seealso:: :obj:`fairscoring.metrics.CalibrationMetric`, :obj:`sklearn.calibration.calibration_curve`


.. py:function:: plot_groupwise_cdfs(scores, target, attribute, groups, favorable_target, *, ax = None, palette = sns.color_palette(), fairness_type, quantile_transform = True, prefer_high_scores = True)

   Plot groupwise cumulative distributions functions (cdfs).

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

                  __Note__: Currently, only plots with exactly two groups are possible.
   :type groups: list
   :param favorable_target: The favorable outcome.
   :type favorable_target: str or int
   :param ax: The axes into which the cdfs shall be plotted
   :type ax: matplotlib.axes.Axes, optional
   :param palette: Color palette, number of colors must at least be number of groups
   :type palette: list or Colormap, Optional
   :param fairness_type: Specifies the type of fairness that is measured. Accepted values are:
                         1. `"IND"` (Independence),
                         2. `"EO"` (Equal Opportunity),
                         3. `"PE"` (Predictive Equality),
   :type fairness_type: {"IND", "EO", "PE"}
   :param quantile_transform: Specify whether the scores shall be quantile transformed.
   :type quantile_transform: bool, default=True
   :param prefer_high_scores: Specify whether high scores or low scores are favorable.
   :type prefer_high_scores: bool, default=True


.. py:function:: plot_cdf_diffs(scores, target, attribute, groups, favorable_target, *, ax = None, palette = sns.color_palette(), fairness_type, quantile_transform = True, prefer_high_scores = True)

   Plots the difference between two cumulative distributions functions (cdfs).

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

                  __Note__: There must be exactly two groups to plot the differences.
   :type groups: list
   :param favorable_target: The favorable outcome.
   :type favorable_target: str or int
   :param ax: The axes into which the cdfs shall be plotted
   :type ax: matplotlib.axes.Axes, optional
   :param palette: Color palette, number of colors must at least be number of groups
   :type palette: list or Colormap, Optional
   :param fairness_type: Specifies the type of fairness that is measured. Accepted values are:
                         1. `"IND"` (Independence),
                         2. `"EO"` (Equal Opportunity),
                         3. `"PE"` (Predictive Equality),
   :type fairness_type: {"IND", "EO", "PE"}
   :param quantile_transform: Specify whether the scores shall be quantile transformed.
   :type quantile_transform: bool, default=True
   :param prefer_high_scores: Specify whether high scores or low scores are favorable.
   :type prefer_high_scores: bool, default=True