Extensively updated sphinx Docs

docs/api/error_parity.binarize.rst

@@ -0,0 +1,12 @@
+error\_parity.binarize
+======================
+
+.. automodule:: error_parity.binarize
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      compute_binary_predictions
+

docs/api/error_parity.classifiers.rst

@@ -0,0 +1,16 @@
+error\_parity.classifiers
+=========================
+
+.. automodule:: error_parity.classifiers
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      BinaryClassifier
+      BinaryClassifierAtROCDiagonal
+      Classifier
+      EnsembleGroupwiseClassifiers
+      RandomizedClassifier
+

docs/api/error_parity.cvxpy_utils.rst

@@ -0,0 +1,16 @@
+error\_parity.cvxpy\_utils
+==========================
+
+.. automodule:: error_parity.cvxpy_utils
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      compute_fair_optimum
+      compute_halfspace_inequality
+      compute_line
+      make_cvxpy_halfspace_inequality
+      make_cvxpy_point_in_polygon_constraints
+

docs/api/error_parity.evaluation.rst

@@ -0,0 +1,16 @@
+error\_parity.evaluation
+========================
+
+.. automodule:: error_parity.evaluation
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      eval_accuracy_and_equalized_odds
+      evaluate_fairness
+      evaluate_performance
+      evaluate_predictions
+      evaluate_predictions_bootstrap
+

docs/api/error_parity.pareto_curve.rst

@@ -0,0 +1,15 @@
+error\_parity.pareto\_curve
+===========================
+
+.. automodule:: error_parity.pareto_curve
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      compute_inner_and_outer_adjustment_ci
+      compute_postprocessing_curve
+      fit_and_evaluate_postprocessing
+      get_envelope_of_postprocessing_frontier
+

docs/api/error_parity.plotting.rst

@@ -0,0 +1,14 @@
+error\_parity.plotting
+======================
+
+.. automodule:: error_parity.plotting
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      plot_polygon_edges
+      plot_postprocessing_frontier
+      plot_postprocessing_solution
+

docs/api/error_parity.roc_utils.rst

@@ -0,0 +1,15 @@
+error\_parity.roc\_utils
+========================
+
+.. automodule:: error_parity.roc_utils
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      calc_cost_of_point
+      compute_global_roc_from_groupwise
+      compute_roc_point_from_predictions
+      roc_convex_hull
+

docs/api/error_parity.threshold_optimizer.rst

@@ -0,0 +1,12 @@
+error\_parity.threshold\_optimizer
+==================================
+
+.. automodule:: error_parity.threshold_optimizer
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      RelaxedThresholdOptimizer
+

docs/concepts.rst

@@ -0,0 +1,33 @@
+Core concepts
+=============
+
+ROC curves and convex hulls
+---------------------------
+
+For each group, the model induces an ROC curve of achievable (FPR, TPR) pairs by thresholding scores. The convex hull of this curve characterizes all achievable points by mixing thresholds and, when necessary, randomization.
+
+Randomized thresholds
+---------------------
+
+When the optimal target lies strictly inside a segment of the ROC hull, it is realized by a randomized classifier that mixes at most two deterministic thresholds, and, if needed, the diagonal (random) classifier. See :class:`error_parity.classifiers.RandomizedClassifier`.
+
+Fairness constraints
+--------------------
+
+Let groups be indexed by ``a, b``. We support constraints expressed on group-specific rates. Examples:
+
+- Equalized odds: constrain distances between (TPR, FPR) pairs across groups.
+- Equal opportunity: constrain TPR parity.
+- Predictive equality: constrain FPR parity.
+- Demographic parity: constrain PPR (positive prediction rate) parity.
+
+Relaxations and \(\ell_p\) norms
+----------------------------------
+
+For equalized odds, distances between group ROC points are measured with an \(\ell_p\) norm, e.g., \(\ell_\infty\) (default), \(\ell_1\) (sum of absolute differences), or \(\ell_2\).
+
+Costs and performance
+---------------------
+
+The optimizer can compute theoretical cost at the global solution point for user-specified false positive and false negative costs. With unit costs, cost equals error rate. See :meth:`error_parity.threshold_optimizer.RelaxedThresholdOptimizer.cost`.
+

docs/conf.py

@@ -28,6 +28,7 @@
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.coverage',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
@@ -48,6 +49,24 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 autoclass_content = 'both'
+autosummary_generate = True
+autodoc_typehints = 'description'
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+autosectionlabel_prefix_document = True
+
+myst_heading_anchors = 3
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+    'sklearn': ('https://scikit-learn.org/stable/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/constraints.rst

@@ -0,0 +1,38 @@
+Constraints
+===========
+
+This page summarizes the implemented constraints and how to select them.
+
+Available constraints
+---------------------
+
+- **Equalized odds** (default): equalize both TPR and FPR across groups, up to a tolerance.
+
+  - Select with ``constraint="equalized_odds"``.
+  - Relaxation via \(\ell_p\) norm between group ROC points; choose ``l_p_norm``.
+
+- **Equal opportunity**: equalize TPR across groups.
+
+  - Select with ``constraint="true_positive_rate_parity"``.
+
+- **Predictive equality**: equalize FPR across groups.
+
+  - Select with ``constraint="false_positive_rate_parity"``.
+
+- **Demographic parity**: equalize positive prediction rate (PPR) across groups.
+
+  - Select with ``constraint="demographic_parity"``.
+
+Tolerance
+---------
+
+All constraints accept a nonnegative ``tolerance`` parameter specifying the maximum allowed disparity according to the constraint's metric. ``tolerance=0.0`` enforces strict parity.
+
+Practical guidance
+------------------
+
+- Use equalized odds when both types of errors matter and the base rates differ by group.
+- Use equal opportunity when minimizing false negatives for positives is paramount.
+- Use predictive equality when minimizing false positives for negatives is paramount.
+- Use demographic parity when the rate of positive decisions itself should be similar across groups.
+

docs/faq.rst

@@ -0,0 +1,28 @@
+FAQ
+===
+
+Do I need to retrain my model?
+------------------------------
+
+No. ``error-parity`` is a postprocessing method that wraps a score-based predictor.
+
+What if my groups are not 0..G-1?
+---------------------------------
+
+Encode them to integers starting at 0 before calling ``fit`` or prediction. Noncontiguous encodings raise a ``ValueError``.
+
+Can I use decision_function instead of predict_proba?
+-----------------------------------------------------
+
+Yes, pass ``predictor=lambda X: model.decision_function(X)``. Ensure higher values indicate higher likelihood of the positive class.
+
+What tolerance should I use?
+----------------------------
+
+Start with ``tolerance=0.0`` (strict). Increase gradually to explore trade-offs using the postprocessing curve utilities.
+
+How do I get uncertainty estimates?
+-----------------------------------
+
+Use :func:`error_parity.evaluation.evaluate_predictions_bootstrap` and the plotting utilities for confidence intervals on frontiers.
+

docs/glossary.rst

@@ -0,0 +1,21 @@
+Glossary
+========
+
+ROC
+   Receiver Operating Characteristic; plots TPR vs. FPR as threshold varies.
+
+ROC hull
+   The convex hull of achievable ROC points; mixing thresholds (and randomized classifiers) realizes any point on the hull.
+
+TPR / FNR
+   True positive rate / false negative rate; ``FNR = 1 - TPR``.
+
+FPR / TNR
+   False positive rate / true negative rate; ``TNR = 1 - FPR``.
+
+PPR
+   Positive prediction rate; fraction of predictions that are positive.
+
+Tolerance
+   Maximum allowed disparity under a chosen fairness constraint.
+