updated sphinx docs

Author: AndreFCruz

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