update doc

statmlben · statmlben · commit 3d7112fb2d5c · 2024-08-21T14:08:22.000+08:00
diff --git a/doc/_templates/autoapi/index.rst b/doc/_templates/autoapi/index.rst
@@ -4,7 +4,6 @@ API Reference
 This page contains auto-generated API reference documentation [#f1]_.
 
 .. toctree::
-   :titlesonly:
 
    /autoapi/rehline/index
 
diff --git a/doc/source/benchmark.rst b/doc/source/benchmark.rst
@@ -1,5 +1,5 @@
-📚 Benchmark
-============
+Benchmark
+=========
 
 We have developed a benchmark for evaluating the performance of optimization methods, which is built on top of the `benchopt <https://github.com/benchopt/benchopt>`_. For those interested in reproducing the benchmark results presented in our paper, we provide a dedicated repository, `ReHLine-benchmark <https://github.com/softmin/ReHLine-benchmark>`_, which contains all the necessary resources and instructions.
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -57,13 +57,7 @@
 	'numpydoc',
 	'nbsphinx',
 	]
-autoapi_dirs = ['../../rehline']
-
-# path to the examples scripts
-# sphinx_gallery_conf = {
-#     'examples_dirs': '../examples',   # path to your example scripts
-#     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
-# }
+autoapi_dirs = ['../../rehline/']
 
 autosummary_generate = True
 numpydoc_show_class_members = False
@@ -73,17 +67,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-
-
-not_document_data = 'sphinx_nbexamples.gallery_config'
-
-example_gallery_config = dict(
-    insert_bokeh='0.12.1',
-    urls='https://github.com/softmin/ReHLine-python/tree/main/examples',
-    )
-process_examples = not osp.exists(osp.join(osp.dirname(__file__), 'examples'))
-
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
diff --git a/doc/source/example.rst b/doc/source/example.rst
@@ -1,10 +1,23 @@
-🌰 Example
-==========
+Example
+=======
 
-- SVM and FairSVM [colab: svm_]
+Example Gallery
+---------------
 
-.. _svm: https://colab.research.google.com/drive/1f_7t1t6FNxAooQOmpyhHCOVq0IKgMxe-?usp=sharing
+.. nblinkgallery::
+   :caption: A few links
+   :name: rst-link-gallery
 
-- Quantile Regression [colab: qt_]
+   examples/ReHLine_QR
+   examples/ReHLine_SVM_FairSVM
+
+List of Examples
+----------------
+
+.. toctree::
+   :maxdepth: 0
+
+   examples/ReHLine_QR.ipynb
+   examples/ReHLine_SVM_FairSVM.ipynb
+   
 
-.. _qt: https://colab.research.google.com/drive/1LwatjwjnMSB97eLVyuOiUY3sl3A3Ie__?usp=sharing
diff --git a/doc/source/examples/ReHLine_QR.ipynb b/doc/source/examples/ReHLine_QR.ipynb
diff --git a/doc/source/examples/ReHLine_SVM_FairSVM.ipynb b/doc/source/examples/ReHLine_SVM_FairSVM.ipynb
diff --git a/doc/source/figs/logo.png b/doc/source/figs/logo.png
diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst
@@ -0,0 +1,43 @@
+Getting started
+===============
+
+This page provides a starter example to introduce users to the ``rehline`` package and showcase its primary features, facilitating exploration and familiarization.
+
+To proceed, make sure that you have already installed ``rehline``:
+
+.. code:: bash
+
+	pip install rehline
+
+--------------------------------
+
+``rehline`` is a generic solver for flexible machine learning Empirical Risk Minimization (ERM), particularly suited for formulations with *non-smooth* objectives.
+
+
+Let's start first by generating a toy dataset and splitting it to train and test sets. For that, we will use scikit-learn make_regression
+
+.. code:: python
+
+    # imports
+    from sklearn.datasets import make_regression
+    from sklearn.model_selection import train_test_split
+
+    # generate toy data
+    X, y = make_regression(n_samples=100, n_features=1000)
+
+    # split data
+    X_train, X_test, y_train, y_test = train_test_split(X, y)
+
+Then let's use ``rehline`` to fit a **quantile regression** at quantile level 0.75.
+
+.. code:: python
+
+    # imports
+    from sklearn.datasets import make_regression
+    from sklearn.model_selection import train_test_split
+
+    # generate toy data
+    X, y = make_regression(n_samples=100, n_features=1000)
+
+    # split data
+    X_train, X_test, y_train, y_test = train_test_split(X, y)
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -6,7 +6,7 @@
 🦌 ReHLine
 ==========
 
-.. image:: logo.png
+.. image:: figs/logo.png
    :width: 18%
    :align: right
 
@@ -52,38 +52,14 @@ The proposed **ReHLine** solver has appealing exhibits appealing properties:
       - The optimization algorithm has a provable **LINEAR** convergence rate, and the per-iteration computational complexity is **LINEAR** in the sample size.
 
 🔨 Installation
-===============
+---------------
 
 Install ``rehline`` using ``pip``
 
 .. code:: bash
 
 	pip install rehline
 
-See more details in `installation <./installation.rst>`_.
-
-📮 Formulation
---------------
-
-`ReHLine` is designed to address the empirical regularized ReLU-ReHU minimization problem, named *ReHLine optimization*, of the following form:
-
-.. math::
-
-  \min_{\mathbf{\beta} \in \mathbb{R}^d} \sum_{i=1}^n \sum_{l=1}^L \text{ReLU}( u_{li} \mathbf{x}_i^\intercal \mathbf{\beta} + v_{li}) + \sum_{i=1}^n \sum_{h=1}^H {\text{ReHU}}_{\tau_{hi}}( s_{hi} \mathbf{x}_i^\intercal \mathbf{\beta} + t_{hi}) + \frac{1}{2} \| \mathbf{\beta} \|_2^2, \ \text{ s.t. } \mathbf{A} \mathbf{\beta} + \mathbf{b} \geq \mathbf{0},
-
-
-where :math:`\mathbf{U} = (u_{li}),\mathbf{V} = (v_{li}) \in \mathbb{R}^{L \times n}` 
-and :math:`\mathbf{S} = (s_{hi}),\mathbf{T} = (t_{hi}),\mathbf{\tau} = (\tau_{hi}) \in \mathbb{R}^{H \times n}` 
-are the ReLU-ReHU loss parameters, and :math:`(\mathbf{A},\mathbf{b})` are the constraint parameters. 
-This formulation has a wide range of applications spanning various fields, including statistics, 
-machine learning, computational biology, and social studies. 
-Some popular examples include SVMs with fairness constraints (FairSVM), 
-elastic net regularized quantile regression (ElasticQR), 
-and ridge regularized Huber minimization (RidgeHuber).
-
-.. image:: ./figs/tab.png
-
-
 Reference
 ---------
 If you use this code please star 🌟 the repository and cite the following paper:
@@ -99,11 +75,8 @@ If you use this code please star 🌟 the repository and cite the following pape
 
 
 .. toctree::
-   :maxdepth: 0
+   :maxdepth: 2
    :hidden:
 
-   getting_started
-   tutorials
-   installation
-   examples/index
+   example
    benchmark
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
diff --git a/doc/source/tutorials.rst b/doc/source/tutorials.rst
@@ -0,0 +1,23 @@
+Tutorials
+=========
+
+`ReHLine` is designed to address the empirical regularized ReLU-ReHU minimization problem, named *ReHLine optimization*, of the following form:
+
+.. math::
+
+  \min_{\mathbf{\beta} \in \mathbb{R}^d} \sum_{i=1}^n \sum_{l=1}^L \text{ReLU}( u_{li} \mathbf{x}_i^\intercal \mathbf{\beta} + v_{li}) + \sum_{i=1}^n \sum_{h=1}^H {\text{ReHU}}_{\tau_{hi}}( s_{hi} \mathbf{x}_i^\intercal \mathbf{\beta} + t_{hi}) + \frac{1}{2} \| \mathbf{\beta} \|_2^2, \ \text{ s.t. } \mathbf{A} \mathbf{\beta} + \mathbf{b} \geq \mathbf{0},
+
+
+where :math:`\mathbf{U} = (u_{li}),\mathbf{V} = (v_{li}) \in \mathbb{R}^{L \times n}` 
+and :math:`\mathbf{S} = (s_{hi}),\mathbf{T} = (t_{hi}),\mathbf{\tau} = (\tau_{hi}) \in \mathbb{R}^{H \times n}` 
+are the ReLU-ReHU loss parameters, and :math:`(\mathbf{A},\mathbf{b})` are the constraint parameters. 
+This formulation has a wide range of applications spanning various fields, including statistics, 
+machine learning, computational biology, and social studies. 
+Some popular examples include SVMs with fairness constraints (FairSVM), 
+elastic net regularized quantile regression (ElasticQR), 
+and ridge regularized Huber minimization (RidgeHuber).
+
+.. image:: ./figs/tab.png
+
+Solving Custom ERMs
+-------------------
diff --git a/rehline/_class.py b/rehline/_class.py
@@ -485,10 +485,6 @@ class ReHLineLinear(ReHLine):
     n_iter_: int
         Maximum number of iterations run across all classes.
 
-    References
-    ----------
-    .. [1] `Dai, B., Qiu, Y,. (2023). ReHLine: Regularized Composite ReLU-ReHU Loss Minimization with Linear Computation and Linear Convergence 
-        <https://openreview.net/pdf?id=3pEBW2UPAD>`_
     """
     def __init__(self, loss={'name':'QR', 'qt':[.25, .75]}, C=1.,
                        U=np.empty(shape=(0,0)), V=np.empty(shape=(0,0)),
