diff --git a/doc/_templates/autoapi/index.rst b/doc/_templates/autoapi/index.rst index 5e9f6f8..78035e1 100644 --- 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 index 0059435..b837ff1 100644 --- 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 `_. For those interested in reproducing the benchmark results presented in our paper, we provide a dedicated repository, `ReHLine-benchmark `_, which contains all the necessary resources and instructions. diff --git a/doc/source/conf.py b/doc/source/conf.py index a115ea3..176cb92 100644 --- 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 index 45eb6b9..fea40e8 100644 --- 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/examples/ReHLine_QR.ipynb b/doc/source/examples/ReHLine_QR.ipynb similarity index 100% rename from examples/ReHLine_QR.ipynb rename to doc/source/examples/ReHLine_QR.ipynb diff --git a/examples/ReHLine_SVM_FairSVM.ipynb b/doc/source/examples/ReHLine_SVM_FairSVM.ipynb similarity index 100% rename from examples/ReHLine_SVM_FairSVM.ipynb rename to doc/source/examples/ReHLine_SVM_FairSVM.ipynb diff --git a/doc/source/logo.png b/doc/source/figs/logo.png similarity index 100% rename from doc/source/logo.png rename to doc/source/figs/logo.png diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index e69de29..7bfae1d 100644 --- 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) \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 8f4146f..1f6ad40 100644 --- 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,7 +52,7 @@ 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`` @@ -60,30 +60,6 @@ Install ``rehline`` using ``pip`` 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 deleted file mode 100644 index 5fd0d42..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,31 +0,0 @@ -🔨 Installation -=============== - -Dependencies ------------- - -``rehline`` requires: **Python>=3.10** + `requirements <./requirements.txt>`_ - -.. code:: bash - - pip install -r requirements.txt - -User installation ------------------ - -Install ``rehline`` using ``pip`` - -.. code:: bash - - pip install rehline - - -Source code ------------ - -You can check the latest sources with the command. - -.. code:: bash - - git clone https://github.com/softmin/ReHLine-python.git - diff --git a/doc/source/tutorials.rst b/doc/source/tutorials.rst index e69de29..989d208 100644 --- 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 +------------------- \ No newline at end of file diff --git a/rehline/_class.py b/rehline/_class.py index b1f1e97..3cb08aa 100644 --- 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 - `_ """ def __init__(self, loss={'name':'QR', 'qt':[.25, .75]}, C=1., U=np.empty(shape=(0,0)), V=np.empty(shape=(0,0)),