[R-package] Rename weight -> weights

[david-cortes]

ref #4968

The lightgbm() function accept observation weights as a parameter named weight. In base R and in other popular R packages for decision trees (and for other model types too) the convention is to name this argument weights instead.

Example decision tree packages naming it weights: ranger (as "case.weights"), gbm, rpart, C5.0, party, evtree, (and wrappers over them such as caret).

The only popular decision tree library I could find naming them weight is xgboost. I'll also have to guess that the ratio of weights to weight would be even higher among linear modeling packages.

As such, this PR changes the name of the argument to be more in line with the rest of the R libraries which users are likely to be familiar with. Additionally, it changes the documentation which incorrectly describes this parameter as being the response value (which it isn't).

It should be noted that this is not a breaking change since existing code using weight would still work under this PR.

[jameslamb]

Thanks for the proposal and for fixing the documentation!

I checked the various packages you mentioned and can confirm that weights (with an s) is used across many of them. Thanks for listing those out!

this is not a breaking change since existing code using weight would still work under this PR

@StrikerRUS I noticed you changed the label on this PR to "breaking". I'm going to change it back to "feature". As @david-cortes is alluding to, R allows for partial matching of keyword argument names.

f <- function(weights){
    print(weights + 5)
}

f(weight = 7)
# 12

@david-cortes will you please add a unit test confirming that weighted training with lightgbm::lightgbm() works as expected using both keyword argument weight and weights? As a general rule, every user-facing change to this project should be accompanied by tests demonstrating their correctness and ensuring that we don't accidentally break that behavior with future.

I recall that previously, R CMD check complained about the use of partial argument-matching in package code (#3629). If it complains about such a unit test, then I wouldn't support changing this keyword argument. But if it's possible to keep a test demonstrating that both weight and weights work, then I support this change to make lightgbm::lightgbm() a bit more consistent with other statistical modeling packages in R.

[StrikerRUS]

@jameslamb

I noticed you changed the label on this PR to "breaking". I'm going to change it back to "feature".

Sorry, my bad!

R allows for partial matching of keyword argument names.

Wow! Didn't know about that, interesting feature!

[david-cortes]

Added tests.

[jameslamb]

excellent, thanks very much!

[github-actions]

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.