[docs] document how to pass multi-value params from Python and R (fixes #4345) #4346
Conversation
include/LightGBM/config.h
Outdated
| @@ -471,6 +471,9 @@ struct Config { | |||
| // desc = used for constraints of monotonic features | |||
| // desc = ``1`` means increasing, ``-1`` means decreasing, ``0`` means non-constraint | |||
| // desc = you need to specify all features in order. For example, ``mc=-1,0,1`` means decreasing for 1st feature, non-constraint for 2nd feature and increasing for the 3rd feature | |||
| // desc = in the CLI or C++, use a string like ``"-1,0,1"`` | |||
| // desc = in the Python package, can use either a string or a list like ``[-1, 0, 1]`` | |||
| // desc = in the R package, can use either a string or a vector like ``c(-1, 0, 1)`` | |||
There was a problem hiding this comment.
| // desc = in the R package, can use either a string or a vector like ``c(-1, 0, 1)`` | |
| // desc = in the R package, can use either a string as in the CLI or a vector like ``c(-1, 0, 1)`` |
There was a problem hiding this comment.
based on #4346 (comment), I think we're going to add general documentation on the fact that you can use a list in Python / vector in R, instead of specifically adding notes like this on each parameter. So I've reverted the changes to the specific monotone_constraints docs.
docs/Parameters.rst
Outdated
| @@ -514,6 +514,12 @@ Learning Control Parameters | |||
|
|
|||
| - you need to specify all features in order. For example, ``mc=-1,0,1`` means decreasing for 1st feature, non-constraint for 2nd feature and increasing for the 3rd feature | |||
|
|
|||
| - in the CLI or C++, use a string like ``"-1,0,1"`` | |||
|
|
|||
| - in the Python package, can use either a string or a list like ``[-1, 0, 1]`` | |||
There was a problem hiding this comment.
@jameslamb I'd like to keep this important doc in a consistent state. Changes proposed in this this PR are actually applicable for any multi-***-type parameter. We have a lot of such params, e.g. max_bin_by_feature , cegb_penalty_feature_lazy, cegb_penalty_feature_coupled, categorical_feature, label_gain, etc. I think it will be better to write a separate paragraph about how multi-*** params can be passed to a program, if you think there should be some clarification for this.
Also, I'm against documenting internal string format for language wrappers. Actually, all params are passed via a string internally.
#4101 (comment)
I don't think we should expose this and it's better to encourage users to use native language structures to pass params.
There was a problem hiding this comment.
ok, I agree with both of these points. I'll split the unit tests part of this into a separate PR.
if you think there should be some clarification for this.
I definitely do. If an expert LightGBM user like @mayer79 wasn't aware (#4345 (comment)) then I think many others will be unaware or will spend time trying to figure it out from unit tests / example code.
There was a problem hiding this comment.
Ok, I've changed this to just document the concept generally. I think it's ready for review.
jameslamb
changed the title
Co-authored-by: Nikita Titov <nekit94-08@mail.ru>
jameslamb
changed the title
|
This pull request has been automatically locked since there has not been any recent activity since it was closed. To start a new related discussion, open a new issue at https://github.com/microsoft/LightGBM/issues including a reference to this. |
Fixed #4345
The documentation for
monotone_constraintsdoes not currently describe the expected data format for that parameter in the Python and R packages.Changes in this PR:
[-1, 0, 1]is valid in the Python package andc(-1, 0, 1)is valid in the R packageLightGBM/tests/python_package_test/test_engine.py
Line 1256 in 20e6338
Notes for Reviewers
This PR is still a work in progress. Will finish getting the tests working before asking for reviews.