@yukuairoy you can already pass gram and Xy as parameter to lars_path. Why is it not enough?

also I see a number of cosmetic changes to existing code in this PR. Avoid this when possible
so the diff is limited to what the new feature code.

@yukuairoy can you answer my question above?

@agramfort Thank you for looking at this PR. Previously users have to pass in non-None X and y for lars_path() to work. The "sufficient stats" mode allows users to skip providing X and y (using None as a placeholder) by providing the set of sufficient statistics instead. In addition to the Gram matrix and Cov matrix (Xy), n_samples is needed as the complete set of sufficient statistics. n_samples was not part of the signature of lars_path() hence we also need to add it into the function signature for this mode to work through.

I've sent a separate PR (#11703) to fix the cosmetic issues and I'll push another commit to make sure this current PR is only about the change in functionality.

@jnothman Thank you for the comment. Could you clarify what you mean by "n_samples = Xy.shape[0]???​"? I cannot find this line in my diff. Or are you suggesting that n_samples can be inferred from Xy?

Please correct me if I'm wrong, I'd think Xy.shape[0] informs us the n_features info as opposed to n_samples. As a matter of fact, n_samples cannot be inferred from either Gram or Xy unless it is explicitly input by the user.

thinking about it I think it would be cleaner to have a new lars_path_gram function that takes Gram and Xy as input (no X or y) and to deprecate the option to pass Gram and Xy to lars_path. That will simplify the API of lars_path.

Hi @jnothman, thanks very much for bringing this up. It looks like on the master branch there is indeed a documentation "bug" in the parameter description of Xy. After this PR is approved and merged into master, I can create another PR to fix that documentation "bug" if it helps the community.

Hi @agramfort, thanks very much for this nice thought. To provide a bit more context, in many of the existing client codebases we know (as well as several cases which the unit-test code exemplified), sometimes users like to invoke so-called "precomputed" mode of the lars_path(...) function, i.e. passing in both X, y, besides Gram and Xy which are literally precomputed. Under the hood of the numerical implementation, knowing X directly might enable the solving algorithm to employ slightly more efficiently numerical linear-algebra routines, compared with the case where X is not known. This is also consistent with the fact that the numerical output of the “precomputed” mode is not always exactly equal to output of the raw mode (some living examples can be found in the test-cases; more can be found in client codebases though they are hard to see from the github perspective). If we deprecate the option to pass Gram and Xy to lars_path(...), one concern is that it will likely break many of the existing client codebases, which may not be thoroughly necessary.

@yukuairoy you will have to change the code of your clients anyway to support what you are aiming for.

When you start to have parameters that are necessary/optional depending on other parameters documenting the API starts to be a mess. With the current master you always need X and y and you can pass precomputed values to avoid recomputation. With what you propose we can have X and y None but then we need to pass n_samples. It starts to be mess I think.

I would prefer to have

lars_path(X, y, precompute=’auto’ | True | False) that would follow the Lars API http://scikit-learn.org/stable/modules/generated/sklearn.linear_model.Lars.html

and

lars_path_gram(Gram, Xy, n_samples)

of course we should do this without code duplication via a private function.

@agramfort I agree that we should keep the two modes separate. My only concern with your suggestion of lars_path(X, y, precompute=’auto’ | True | False) is in order to support the precompute mode, lars_path(), in addition to a precompute parameter, still needs to take Gram and Xy -- making the precompute parameter redundant.

How about we keep the original

lars_path(X, y, Xy=None, Gram=None, max_iter=500, alpha_min=0, method='lar', copy_X=True, eps=np.finfo(np.float).eps, copy_Gram=True, verbose=0, return_path=True, return_n_iter=False, positive=False)

intact and add an additional

lars_path_gram(Gram, Xy, n_samples, max_iter=500, alpha_min=0, method='lar', copy_X=True, eps=np.finfo(np.float).eps, copy_Gram=True, verbose=0, return_path=True, return_n_iter=False, positive=False)?

This way we get to keep backward compatibility. Of course we'll use a private function to avoid code duplication.

Thanks @agramfort and @jnothman for the comments. I've updated the code. Please take a look.

@agramfort Do you have further comments?

@agramfort Friendly ping

@agramfort can you please review the current version?

@jnothman Thanks for reviewing this merge request. Is there anything we can do to make sure @agramfort reviews the latest changes?

@yukuairoy we need a what's new update before merging.

@agramfort @jnothman thanks for LGTM. I've updated the What's New.

Thanks @yukuairoy!