[NEW FEATURE] DOC: add a few examples on least squares, lasso, enet

[mathurinm]

Is your feature request related to a problem? Please describe.

It is a bit hard for a newcomer to get all the building bricks (algorithm, gradient, prox) and their syntax, also because the signature of some classes is *args, **kwargs (eg GradBasic).

Describe the solution you'd like
Adding some examples may help. Here's code that you can reuse for OLS and Lasso:

import numpy as np
from modopt.opt.algorithms import ForwardBackward, POGM
from modopt.opt.gradient import GradBasic
from modopt.opt.proximity import IdentityProx, SparseThreshold
from modopt.opt.linear import Identity


from libsvmdata import fetch_libsvm

X, y = fetch_libsvm("rcv1.binary")

# OLS
x = np.zeros(X.shape[1])
L = np.linalg.norm(X, ord=2) ** 2
fb = ForwardBackward(
    x,
    grad=GradBasic(
        input_data=y,
        op=lambda w: X @ w,
        trans_op=lambda v: X.T @ v,
        input_data_writeable=True,
    ),
    prox=IdentityProx(),
    beta_param=1./L,
    auto_iterate=False,
    cost=None,
    progress=False,
)

fb.iterate(100)


# LASSO (maybe illustrate weights)

L = np.linalg.norm(X, ord=2) ** 2
weights = 1 / np.linalg.norm(X, axis=0)
var_init = np.zeros(X.shape[1])
pogm = POGM(
    x=var_init,  
    u=var_init,
    y=var_init,
    z=var_init,
    grad=GradBasic(
        input_data=y,
        op=lambda w: X @ w,
        trans_op=lambda v: X.T @ v,
        input_data_writeable=True,
    ),
    prox=SparseThreshold(Identity(), weights),
    beta_param=1. / L,
    metric_call_period=None,
)


# maybe FISTA, influence of some strategies, explain what parameters are for each method, etc.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Are you planning to submit a Pull Request?
I can submit the above code if there's already an example folder automatically deployed with sphinx or a sphinx-like.

[sfarrens]

Hi @mathurinm thanks for the suggestion. We are aiming to improve the documentation for the next PySAP release, so this is really helpful feedback. I will get back to you regarding the example folder etc.

[paquiteau]

I guess that #277 provides a solution to this :)