[docs] R docs cleanup (#2375)

* R docs cleanup

* regenerated R documentation files

R-package/R/lgb.Dataset.R

@@ -635,9 +635,9 @@ Dataset <- R6::R6Class(
   )
 )
 
-#' Construct lgb.Dataset object
+#' Construct \code{lgb.Dataset} object
 #'
-#' Construct lgb.Dataset object from dense matrix, sparse matrix
+#' Construct \code{lgb.Dataset} object from dense matrix, sparse matrix
 #' or local file (that was created previously by saving an \code{lgb.Dataset}).
 #'
 #' @param data a \code{matrix} object, a \code{dgCMatrix} object or a character representing a filename
@@ -646,7 +646,7 @@ Dataset <- R6::R6Class(
 #' @param colnames names of columns
 #' @param categorical_feature categorical features
 #' @param free_raw_data TRUE for need to free raw data after construct
-#' @param info a list of information of the lgb.Dataset object
+#' @param info a list of information of the \code{lgb.Dataset} object
 #' @param ... other information to pass to \code{info} or parameters pass to \code{params}
 #'
 #' @return constructed dataset
@@ -690,7 +690,7 @@ lgb.Dataset <- function(data,
 #'
 #' @param dataset \code{lgb.Dataset} object, training data
 #' @param data a \code{matrix} object, a \code{dgCMatrix} object or a character representing a filename
-#' @param info a list of information of the lgb.Dataset object
+#' @param info a list of information of the \code{lgb.Dataset} object
 #' @param ... other information to pass to \code{info}.
 #'
 #' @return constructed dataset
@@ -741,7 +741,7 @@ lgb.Dataset.construct <- function(dataset) {
 
 }
 
-#' Dimensions of an lgb.Dataset
+#' Dimensions of an \code{lgb.Dataset}
 #'
 #' Returns a vector of numbers of rows and of columns in an \code{lgb.Dataset}.
 #' @param x Object of class \code{lgb.Dataset}
@@ -852,9 +852,9 @@ dimnames.lgb.Dataset <- function(x) {
 #' Slice a dataset
 #'
 #' Get a new \code{lgb.Dataset} containing the specified rows of
-#' original lgb.Dataset object
+#' original \code{lgb.Dataset} object
 #'
-#' @param dataset Object of class "lgb.Dataset"
+#' @param dataset Object of class \code{lgb.Dataset}
 #' @param idxset a integer vector of indices of rows needed
 #' @param ... other parameters (currently not used)
 #' @return constructed sub dataset
@@ -888,7 +888,7 @@ slice.lgb.Dataset <- function(dataset, idxset, ...) {
 
 }
 
-#' Get information of an lgb.Dataset object
+#' Get information of an \code{lgb.Dataset} object
 #'
 #' @param dataset Object of class \code{lgb.Dataset}
 #' @param name the name of the information field to get (see details)
@@ -901,8 +901,8 @@ slice.lgb.Dataset <- function(dataset, idxset, ...) {
 #' \itemize{
 #'     \item \code{label}: label lightgbm learn from ;
 #'     \item \code{weight}: to do a weight rescale ;
-#'     \item \code{group}: group size
-#'     \item \code{init_score}: initial score is the base prediction lightgbm will boost from ;
+#'     \item \code{group}: group size ;
+#'     \item \code{init_score}: initial score is the base prediction lightgbm will boost from.
 #' }
 #'
 #' @examples
@@ -937,9 +937,9 @@ getinfo.lgb.Dataset <- function(dataset, name, ...) {
 
 }
 
-#' Set information of an lgb.Dataset object
+#' Set information of an \code{lgb.Dataset} object
 #'
-#' @param dataset Object of class "lgb.Dataset"
+#' @param dataset Object of class \code{lgb.Dataset}
 #' @param name the name of the field to get
 #' @param info the specific field of information to set
 #' @param ... other parameters

R-package/R/lgb.prepare.R

@@ -1,30 +1,18 @@
 #' Data preparator for LightGBM datasets (numeric)
 #'
-#' Attempts to prepare a clean dataset to prepare to put in a lgb.Dataset. Factors and characters are converted to numeric without integers. Please use \code{lgb.prepare_rules} if you want to apply this transformation to other datasets.
+#' Attempts to prepare a clean dataset to prepare to put in a \code{lgb.Dataset}. Factors and characters are converted to numeric without integers. Please use \code{lgb.prepare_rules} if you want to apply this transformation to other datasets.
 #'
 #' @param data A data.frame or data.table to prepare.
 #'
-#' @return The cleaned dataset. It must be converted to a matrix format (\code{as.matrix}) for input in lgb.Dataset.
+#' @return The cleaned dataset. It must be converted to a matrix format (\code{as.matrix}) for input in \code{lgb.Dataset}.
 #'
 #' @examples
 #' library(lightgbm)
 #' data(iris)
 #'
 #' str(iris)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : Factor w/ 3 levels "setosa","versicolor",..: 1 1 1 1 ...
 #'
 #' str(lgb.prepare(data = iris)) # Convert all factors/chars to numeric
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : num  1 1 1 1 1 1 1 1 1 1 ...
 #'
 #' \dontrun{
 #' # When lightgbm package is installed, and you do not want to load it

R-package/R/lgb.prepare2.R

@@ -1,31 +1,19 @@
 #' Data preparator for LightGBM datasets (integer)
 #'
-#' Attempts to prepare a clean dataset to prepare to put in a lgb.Dataset. Factors and characters are converted to numeric (specifically: integer). Please use \code{lgb.prepare_rules2} if you want to apply this transformation to other datasets. This is useful if you have a specific need for integer dataset instead of numeric dataset. Note that there are programs which do not support integer-only input. Consider this as a half memory technique which is dangerous, especially for LightGBM.
+#' Attempts to prepare a clean dataset to prepare to put in a \code{lgb.Dataset}. Factors and characters are converted to numeric (specifically: integer). Please use \code{lgb.prepare_rules2} if you want to apply this transformation to other datasets. This is useful if you have a specific need for integer dataset instead of numeric dataset. Note that there are programs which do not support integer-only input. Consider this as a half memory technique which is dangerous, especially for LightGBM.
 #'
 #' @param data A data.frame or data.table to prepare.
 #'
-#' @return The cleaned dataset. It must be converted to a matrix format (\code{as.matrix}) for input in lgb.Dataset.
+#' @return The cleaned dataset. It must be converted to a matrix format (\code{as.matrix}) for input in \code{lgb.Dataset}.
 #'
 #' @examples
 #' library(lightgbm)
 #' data(iris)
 #'
 #' str(iris)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : Factor w/ 3 levels "setosa","versicolor",..: 1 1 1 1 ...
 #'
 #' # Convert all factors/chars to integer
 #' str(lgb.prepare2(data = iris))
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : int  1 1 1 1 1 1 1 1 1 1 ...
 #'
 #' \dontrun{
 #' # When lightgbm package is installed, and you do not want to load it

R-package/R/lgb.prepare_rules.R

@@ -1,53 +1,35 @@
 #' Data preparator for LightGBM datasets with rules (numeric)
 #'
-#' Attempts to prepare a clean dataset to prepare to put in a lgb.Dataset. Factors and characters are converted to numeric. In addition, keeps rules created so you can convert other datasets using this converter.
+#' Attempts to prepare a clean dataset to prepare to put in a \code{lgb.Dataset}. Factors and characters are converted to numeric. In addition, keeps rules created so you can convert other datasets using this converter.
 #'
 #' @param data A data.frame or data.table to prepare.
 #' @param rules A set of rules from the data preparator, if already used.
 #'
-#' @return A list with the cleaned dataset (\code{data}) and the rules (\code{rules}). The data must be converted to a matrix format (\code{as.matrix}) for input in lgb.Dataset.
+#' @return A list with the cleaned dataset (\code{data}) and the rules (\code{rules}). The data must be converted to a matrix format (\code{as.matrix}) for input in \code{lgb.Dataset}.
 #'
 #' @examples
 #' library(lightgbm)
 #' data(iris)
 #'
 #' str(iris)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : Factor w/ 3 levels "setosa","versicolor",..: 1 1 1 1 ...
 #'
 #' new_iris <- lgb.prepare_rules(data = iris) # Autoconverter
 #' str(new_iris$data)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : num  1 1 1 1 1 1 1 1 1 1 ...
 #'
 #' data(iris) # Erase iris dataset
 #' iris$Species[1] <- "NEW FACTOR" # Introduce junk factor (NA)
-#' # Warning message:
-#' # In `[<-.factor`(`*tmp*`, 1, value = c(NA, 1L, 1L, 1L, 1L, 1L, 1L,  :
-#' #  invalid factor level, NA generated
 #'
 #' # Use conversion using known rules
 #' # Unknown factors become 0, excellent for sparse datasets
 #' newer_iris <- lgb.prepare_rules(data = iris, rules = new_iris$rules)
 #'
 #' # Unknown factor is now zero, perfect for sparse datasets
 #' newer_iris$data[1, ] # Species became 0 as it is an unknown factor
-#' #   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
-#' # 1          5.1         3.5          1.4         0.2       0
 #'
 #' newer_iris$data[1, 5] <- 1 # Put back real initial value
 #'
 #' # Is the newly created dataset equal? YES!
 #' all.equal(new_iris$data, newer_iris$data)
-#' # [1] TRUE
 #'
 #' # Can we test our own rules?
 #' data(iris) # Erase iris dataset
@@ -58,12 +40,6 @@
 #'                                    "virginica" = 1))
 #' newest_iris <- lgb.prepare_rules(data = iris, rules = personal_rules)
 #' str(newest_iris$data) # SUCCESS!
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : num  3 3 3 3 3 3 3 3 3 3 ...
 #'
 #' @importFrom data.table set
 #' @export

R-package/R/lgb.prepare_rules2.R

@@ -1,53 +1,35 @@
 #' Data preparator for LightGBM datasets with rules (integer)
 #'
-#' Attempts to prepare a clean dataset to prepare to put in a lgb.Dataset. Factors and characters are converted to numeric (specifically: integer). In addition, keeps rules created so you can convert other datasets using this converter. This is useful if you have a specific need for integer dataset instead of numeric dataset. Note that there are programs which do not support integer-only input. Consider this as a half memory technique which is dangerous, especially for LightGBM.
+#' Attempts to prepare a clean dataset to prepare to put in a \code{lgb.Dataset}. Factors and characters are converted to numeric (specifically: integer). In addition, keeps rules created so you can convert other datasets using this converter. This is useful if you have a specific need for integer dataset instead of numeric dataset. Note that there are programs which do not support integer-only input. Consider this as a half memory technique which is dangerous, especially for LightGBM.
 #'
 #' @param data A data.frame or data.table to prepare.
 #' @param rules A set of rules from the data preparator, if already used.
 #'
-#' @return A list with the cleaned dataset (\code{data}) and the rules (\code{rules}). The data must be converted to a matrix format (\code{as.matrix}) for input in lgb.Dataset.
+#' @return A list with the cleaned dataset (\code{data}) and the rules (\code{rules}). The data must be converted to a matrix format (\code{as.matrix}) for input in \code{lgb.Dataset}.
 #'
 #' @examples
 #' library(lightgbm)
 #' data(iris)
 #'
 #' str(iris)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : Factor w/ 3 levels "setosa","versicolor",..: 1 1 1 1 ...
 #'
 #' new_iris <- lgb.prepare_rules2(data = iris) # Autoconverter
 #' str(new_iris$data)
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : int  1 1 1 1 1 1 1 1 1 1 ...
 #'
 #' data(iris) # Erase iris dataset
 #' iris$Species[1] <- "NEW FACTOR" # Introduce junk factor (NA)
-#' # Warning message:
-#' # In `[<-.factor`(`*tmp*`, 1, value = c(NA, 1L, 1L, 1L, 1L, 1L, 1L,  :
-#' #  invalid factor level, NA generated
 #'
 #' # Use conversion using known rules
 #' # Unknown factors become 0, excellent for sparse datasets
 #' newer_iris <- lgb.prepare_rules2(data = iris, rules = new_iris$rules)
 #'
 #' # Unknown factor is now zero, perfect for sparse datasets
 #' newer_iris$data[1, ] # Species became 0 as it is an unknown factor
-#' #   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
-#' # 1          5.1         3.5          1.4         0.2       0
 #'
 #' newer_iris$data[1, 5] <- 1 # Put back real initial value
 #'
 #' # Is the newly created dataset equal? YES!
 #' all.equal(new_iris$data, newer_iris$data)
-#' # [1] TRUE
 #'
 #' # Can we test our own rules?
 #' data(iris) # Erase iris dataset
@@ -58,12 +40,6 @@
 #'                                    "virginica" = 1L))
 #' newest_iris <- lgb.prepare_rules2(data = iris, rules = personal_rules)
 #' str(newest_iris$data) # SUCCESS!
-#' # 'data.frame':	150 obs. of  5 variables:
-#' # $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
-#' # $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
-#' # $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
-#' # $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
-#' # $ Species     : int  3 3 3 3 3 3 3 3 3 3 ...
 #'
 #' @importFrom data.table set
 #' @export

R-package/R/readRDS.lgb.Booster.R

@@ -1,11 +1,11 @@
-#' readRDS for lgb.Booster models
+#' readRDS for \code{lgb.Booster} models
 #'
 #' Attempts to load a model using RDS.
 #'
 #' @param file a connection or the name of the file where the R object is saved to or read from.
 #' @param refhook a hook function for handling reference objects.
 #'
-#' @return lgb.Booster.
+#' @return \code{lgb.Booster}.
 #'
 #' @examples
 #' library(lightgbm)

R-package/R/saveRDS.lgb.Booster.R

@@ -1,4 +1,4 @@
-#' saveRDS for lgb.Booster models
+#' saveRDS for \code{lgb.Booster} models
 #'
 #' Attempts to save a model using RDS. Has an additional parameter (\code{raw}) which decides whether to save the raw model or not.
 #'