[R-package] Rename `weight` -> `weights` (#4975)

* rename weight -> weights

* add test for 'weights' argument

* Update R-package/R/lightgbm.R

* update docs
Co-authored-by: James Lamb <jaylamb20@gmail.com>

R-package/R/lightgbm.R

@@ -91,7 +91,8 @@ NULL
 #' @description Simple interface for training a LightGBM model.
 #' @inheritParams lgb_shared_params
 #' @param label Vector of labels, used if \code{data} is not an \code{\link{lgb.Dataset}}
-#' @param weight vector of response values. If not NULL, will set to dataset
+#' @param weights Sample / observation weights for rows in the input data. If \code{NULL}, will assume that all
+#'                observations / rows have the same importance / weight.
 #' @param objective Optimization objective (e.g. `"regression"`, `"binary"`, etc.).
 #'                  For a list of accepted objectives, see
 #'                  \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html#objective}{
@@ -117,7 +118,7 @@ NULL
 #' @export
 lightgbm <- function(data,
                      label = NULL,
-                     weight = NULL,
+                     weights = NULL,
                      params = list(),
                      nrounds = 100L,
                      verbose = 1L,
@@ -140,7 +141,7 @@ lightgbm <- function(data,
 
   # Check whether data is lgb.Dataset, if not then create lgb.Dataset manually
   if (!lgb.is.Dataset(x = dtrain)) {
-    dtrain <- lgb.Dataset(data = data, label = label, weight = weight, init_score = init_score)
+    dtrain <- lgb.Dataset(data = data, label = label, weight = weights, init_score = init_score)
   }
 
   train_args <- list(

R-package/man/lightgbm.Rd

@@ -7,7 +7,7 @@
 lightgbm(
   data,
   label = NULL,
-  weight = NULL,
+  weights = NULL,
   params = list(),
   nrounds = 100L,
   verbose = 1L,
@@ -28,7 +28,8 @@ may allow you to pass other types of data like \code{matrix} and then separately
 
 \item{label}{Vector of labels, used if \code{data} is not an \code{\link{lgb.Dataset}}}
 
-\item{weight}{vector of response values. If not NULL, will set to dataset}
+\item{weights}{Sample / observation weights for rows in the input data. If \code{NULL}, will assume that all
+observations / rows have the same importance / weight.}
 
 \item{params}{a list of parameters. See \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html}{
 the "Parameters" section of the documentation} for a list of parameters and valid values.}

R-package/tests/testthat/test_basic.R

@@ -2927,3 +2927,29 @@ test_that("lightgbm() defaults to 'regression' objective if objective not otherw
   expect_true(any(model_txt_lines == "objective=regression"))
   expect_false(any(model_txt_lines == "objective=regression_l1"))
 })
+
+test_that("lightgbm() accepts 'weight' and 'weights'", {
+  data(mtcars)
+  X <- as.matrix(mtcars[, -1L])
+  y <- as.numeric(mtcars[, 1L])
+  w <- rep(1.0, nrow(X))
+  model <- lightgbm(
+    X
+    , y
+    , weights = w
+    , obj = "regression"
+    , nrounds = 5L
+    , verbose = -1L
+  )
+
+  # Avoid a bad CRAN check due to partial argument matches
+  lgb_args <- list(
+    X
+    , y
+    , weight = w
+    , obj = "regression"
+    , nrounds = 5L
+    , verbose = -1L
+  )
+  model <- do.call(lightgbm, lgb_args)
+})