Resolve merge conflicts: Keep upstream code, keep local doc improvements

Author: statmlben

doc/source/autoapi/rehline/index.rst

@@ -573,13 +573,13 @@ Classes
 
    Attributes
    ----------
-   coef\_ : ndarray of shape (n_features,)
+   coef_ : ndarray of shape (n_features,)
        Coefficients excluding the intercept.
 
-   intercept\_ : float
+   intercept_ : float
        Intercept term. 0.0 if ``fit_intercept=False``.
 
-   classes\_ : ndarray of shape (2,)
+   classes_ : ndarray of shape (2,)
        Unique class labels in the original label space.
 
    _label_encoder : LabelEncoder
@@ -692,7 +692,7 @@ Classes
          - ``{'name': 'nonnegative'}`` or ``{'name': '>=0'}``
          - ``{'name': 'fair', 'sen_idx': list[int], 'tol_sen': list[float]}``
          - ``{'name': 'custom', 'A': ndarray[K, d], 'b': ndarray[K]}``
-         
+
        Note: when ``fit_intercept=True``, a constant column is appended **as the last column**;
        since you index sensitive columns by ``sen_idx`` on the *original* features, indices stay valid.
    C : float, default=1.0
@@ -722,11 +722,11 @@ Classes
 
    Attributes
    ----------
-   coef\_ : ndarray of shape (n_features,)
+   coef_ : ndarray of shape (n_features,)
        Learned linear coefficients (excluding the intercept term).
-   intercept\_ : float
+   intercept_ : float
        Intercept term extracted from the last coefficient when ``fit_intercept=True``, otherwise 0.0.
-   n_features_in\_ : int
+   n_features_in_ : int
        Number of input features seen during :meth:`fit` (before intercept augmentation).
 
    Notes
@@ -748,7 +748,7 @@ Classes
       * - :py:obj:`fit <rehline.plq_Ridge_Regressor.fit>`\ (X, y, sample_weight)
         - If ``fit_intercept=True``, a constant column (value = ``intercept_scaling``) is appended
       * - :py:obj:`decision_function <rehline.plq_Ridge_Regressor.decision_function>`\ (X)
-        - Compute f(X) = X @ coef\_ + intercept\_.
+        - Compute f(X) = X @ coef_ + intercept_.
       * - :py:obj:`predict <rehline.plq_Ridge_Regressor.predict>`\ (X)
         - Predict targets as the linear decision function.
 
@@ -782,7 +782,7 @@ Classes
 
    .. py:method:: decision_function(X)
 
-      Compute f(X) = X @ coef\_ + intercept\_.
+      Compute f(X) = X @ coef_ + intercept_.
 
       Parameters
       ----------
@@ -798,6 +798,7 @@ Classes
    .. py:method:: predict(X)
 
       Predict targets as the linear decision function.
+
       Parameters
       ----------
       X : ndarray of shape (n_samples, n_features)
@@ -811,17 +812,17 @@ Classes
 
 
 
-.. py:class:: plqMF_Ridge(n_users, n_items, loss, constraint=[], biased=True, rank=10, C=1.0, rho=0.5, init_mean=0.0, init_sd=0.1, random_state=None, max_iter=10000, tol=0.0001, shrink=1, trace_freq=100, max_iter_CD=10, tol_CD=0.0001, verbose=0)
+.. py:class:: plqMF_Ridge(n_users, n_items, loss, biased=True, constraint_user=[], constraint_item=[], rank=10, C=1.0, rho=0.5, init_mean=0.0, init_sd=0.1, random_state=None, max_iter=10000, tol=0.0001, shrink=1, trace_freq=100, max_iter_CD=10, tol_CD=0.0001, verbose=0)
 
    Bases: :py:obj:`rehline._base._BaseReHLine`, :py:obj:`sklearn.base.BaseEstimator`
 
    Matrix Factorization (MF) with a piecewise linear-quadratic objective and ridge penalty.
 
    .. math::
        \min_{\substack{
-           \mathbf{P} \in \mathbb{R}^{n \times r}\ 
+           \mathbf{P} \in \mathbb{R}^{n \times k}\ 
            \pmb{\alpha} \in \mathbb{R}^n \\
-           \mathbf{Q} \in \mathbb{R}^{m \times r}\ 
+           \mathbf{Q} \in \mathbb{R}^{m \times k}\ 
            \pmb{\beta} \in \mathbb{R}^m
        }} 
        \left[
@@ -835,21 +836,15 @@ Classes
 
    .. math::
        \ \text{ s.t. } \ 
-       \mathbf{A} \begin{bmatrix}
-                       \pmb{\alpha} & \mathbf{P}
-                   \end{bmatrix}^T + 
-                   \mathbf{b}\mathbf{1}_{n}^T \geq \mathbf{0}
-       \ \text{ and } \ 
-       \mathbf{A} \begin{bmatrix}
-                       \pmb{\beta} & \mathbf{Q}
-                   \end{bmatrix}^T + 
-                   \mathbf{b}\mathbf{1}_{m}^T \geq \mathbf{0}
+       \mathbf{A}_{\text{user}} \begin{pmatrix} \alpha_u \\ \mathbf{p}_u \end{pmatrix} + \mathbf{b}_{\text{user}} \geq \mathbf{0},\ u = 1,\dots,n
+       \quad \text{and} \quad
+       \mathbf{A}_{\text{item}} \begin{pmatrix} \beta_i \\ \mathbf{q}_i \end{pmatrix} + \mathbf{b}_{\text{item}} \geq \mathbf{0},\ i = 1,\dots,m
        
    The function supports various loss functions, including:
        - 'hinge', 'svm' or 'SVM'
        - 'MAE' or 'mae' or 'mean absolute error'
-       - 'hinge square' or 'svm square' or 'SVM square'
-       - 'MSE' or 'mse' or 'mean square error'
+       - 'squared hinge' or 'squared svm' or 'squared SVM'
+       - 'MSE' or 'mse' or 'mean squared error'
 
    The following constraint types are supported:
        * 'nonnegative' or '>=0': A non-negativity constraint.
@@ -867,8 +862,12 @@ Classes
    loss : dict
        A dictionary specifying the loss function parameters. 
 
-   constraint : list of dict
-       A list of dictionaries, where each dictionary represents a constraint.
+   constraint_user : list of dict
+       A list of dictionaries, where each dictionary represents a constraint to user side parameters.
+       Each dictionary must contain a 'name' key, which specifies the type of constraint.
+
+   constraint_item : list of dict
+       A list of dictionaries, where each dictionary represents a constraint to item side parameters.
        Each dictionary must contain a 'name' key, which specifies the type of constraint.
 
    biased : bool, default=True
@@ -965,7 +964,7 @@ Classes
    decision_function(X)
        The decision function evaluated on the given dataset.
 
-   obj(X, y, loss))
+   obj(X, y)
        Compute the values of loss term and objective function.
 
    Notes
@@ -987,7 +986,7 @@ Classes
         - Fit the model based on the given training data.
       * - :py:obj:`decision_function <rehline.plqMF_Ridge.decision_function>`\ (X)
         - The decision function evaluated on the given dataset
-      * - :py:obj:`obj <rehline.plqMF_Ridge.obj>`\ (X, y, loss)
+      * - :py:obj:`obj <rehline.plqMF_Ridge.obj>`\ (X, y)
         - Compute the values of loss term and objective function.
 
 
@@ -1034,7 +1033,7 @@ Classes
           Predicted ratings for the input pairs.
 
 
-   .. py:method:: obj(X, y, loss)
+   .. py:method:: obj(X, y)
 
       Compute the values of loss term and objective function.
 
@@ -1045,9 +1044,6 @@ Classes
 
       y : array-like of shape (n_ratings,)
           Actual rating values.
-
-      loss : dict
-          A dictionary specifying the loss function parameters. 
 
       Returns
       -------

doc/source/tutorials/constraint.rst

@@ -1,54 +1,103 @@
 Constraint
 **********
 
-Supported linear constraints in ReHLine are listed in the table below.
+ReHLine allows you to impose various linear constraints on the model coefficients.
 
-Usage
------
+Usage Pattern
+-------------
 
-.. code:: python
+Define constraints as a list of dictionaries:
 
-   # list of
-   # name (str): name of the custom linear constraints
-   # loss_kwargs: more keys and values for constraint parameters
-   constraint = [{'name': <constraint_name>, <**constraint_kwargs>}, ...]
+.. code-block:: python
 
-.. list-table::
- :align: left
- :widths: 5 20 15
- :header-rows: 1
+   # list of constraint dictionaries
+   constraint = [{'name': <constraint_name>, **kwargs}, ...]
 
- * - constraint
-   - | args
-   - | Example
 
- * - **nonnegative**
-   - | ``name``: 'nonnegative' or '>=0'
-   - | ``constraint=[{'name': '>=0'}]``
+Supported Constraints
+---------------------
 
- * - **fair**
-   - | ``name``: 'fair' or 'fairness'
-     | ``sen_idx``: a list contains column indices for sensitive attributes
-     | ``tol_sen``: 1d array [p] of tolerance for fairness
-   - | ``constraint=[{'name': 'fair', 'sen_idx': sen_idx, 'tol_sen': tol_sen}]``
+Non-negative
+^^^^^^^^^^^^
+Constrains all coefficients to be non-negative (:math:`\beta_j \ge 0`) [1]_.
 
- * - **monotonic**
-   - | ``name``: 'monotonic' or 'monotonicity'
-     | ``decreasing`` (*bool*): False (default)
-   - | ``constraint=[{'name': 'monotonic', 'decreasing': True}]``
+* **Names**: ``'nonnegative'``, ``'>=0'``
+* **Parameters**: None
 
- * - **custom**
-   - | ``name``: 'custom'
-     | ``A``: 2d array [K x d] for linear constraint coefficients
-     | ``b``: 1d array [K] of constraint intercepts
-   - | ``constraint=[{'name': 'custom', 'A': A, 'b': b}]``
+.. code-block:: python
 
-Related Examples
-----------------
+   constraint = [{'name': '>=0'}]
+
+**Related Example**
 
 .. nblinkgallery::
-   :caption: Constraints
-   :name: rst-link-gallery
+   :name: nmf-gallery
 
-   ../examples/FairSVM.ipynb
    ../examples/NMF.ipynb
+
+Fairness
+^^^^^^^^
+Constrains the correlation between predictions and sensitive attributes to be within a tolerance [2]_.
+
+* **Names**: ``'fair'``, ``'fairness'``
+* **Parameters**:
+    * ``sen_idx`` (*list of int*): Column indices of sensitive attributes in ``X``.
+    * ``tol_sen`` (*list of float*): Tolerance thresholds for each sensitive attribute.
+
+.. code-block:: python
+
+   # Example: Constrain fairness w.r.t. feature at index 0 with tolerance 0.01
+   constraint = [{'name': 'fair', 'sen_idx': [0], 'tol_sen': [0.01]}]
+
+**Related Example**
+
+.. nblinkgallery::
+   :name: fair-gallery
+
+   ../examples/FairSVM.ipynb
+
+Monotonicity
+^^^^^^^^^^^^
+Constrains coefficients to be monotonically increasing or decreasing [3]_.
+Increasing: :math:`\beta_i \le \beta_{i+1}`. Decreasing: :math:`\beta_i \ge \beta_{i+1}`.
+
+* **Names**: ``'monotonic'``, ``'monotonicity'``
+* **Parameters**:
+    * ``decreasing`` (*bool*, default=False): If ``True``, enforces decreasing monotonicity.
+
+.. code-block:: python
+
+   # Monotonically increasing
+   constraint = [{'name': 'monotonic'}]
+
+   # Monotonically decreasing
+   constraint = [{'name': 'monotonic', 'decreasing': True}]
+
+Custom Constraints
+^^^^^^^^^^^^^^^^^^
+Define arbitrary linear constraints of the form :math:`A\beta + b \ge 0`.
+
+* **Names**: ``'custom'``
+* **Parameters**:
+    * ``A`` (*ndarray*): Coefficient matrix of shape (K, d).
+    * ``b`` (*ndarray*): Intercept vector of shape (K,).
+
+.. code-block:: python
+
+   import numpy as np
+
+   # Example: beta_0 + beta_1 >= 1
+   A = np.zeros((1, d))
+   A[0, 0] = 1
+   A[0, 1] = 1
+   b = np.array([-1.0])
+
+   constraint = [{'name': 'custom', 'A': A, 'b': b}]
+
+
+References
+----------
+
+.. [1] `Lee, D. D., & Seung, H. S. (1999). Learning the parts of objects by non-negative matrix factorization. Nature, 401(6755), 788-791. <https://www.nature.com/articles/44565>`_
+.. [2] `Zafar, M. B., Valera, I., Gomez Rodriguez, M., & Gummadi, K. P. (2019). Fairness Constraints: A Flexible Approach for Fair Classification. Journal of Machine Learning Research, 20(75), 1-42. <https://www.jmlr.org/papers/v20/18-262.html>`_
+.. [3] `Nature Research Intelligence. Monotonicity Constraints in Machine Learning and Classification. <https://www.nature.com/research-intelligence/nri-topic-summaries/monotonicity-constraints-in-machine-learning-and-classification-micro-23773>`_