[R-package] remove lgb.unloader() (#5204)

* [R-package] remove lgb.unloader()

* update version reference

R-package/NAMESPACE

@@ -31,7 +31,6 @@ export(lgb.plot.interpretation)
 export(lgb.restore_handle)
 export(lgb.save)
 export(lgb.train)
-export(lgb.unloader)
 export(lightgbm)
 export(readRDS.lgb.Booster)
 export(saveRDS.lgb.Booster)

R-package/R/lgb.unloader.R

-#' @name lgb.unloader
-#' @title Remove lightgbm and its objects from an environment
-#' @description Attempts to unload LightGBM packages so you can remove objects cleanly without
-#'              having to restart R. This is useful for instance if an object becomes stuck for no
-#'              apparent reason and you do not want to restart R to fix the lost object.
-#' @param restore Whether to reload \code{LightGBM} immediately after detaching from R.
-#'                Defaults to \code{TRUE} which means automatically reload \code{LightGBM} once
-#'                unloading is performed.
-#' @param wipe Whether to wipe all \code{lgb.Dataset} and \code{lgb.Booster} from the global
-#'             environment. Defaults to \code{FALSE} which means to not remove them.
-#' @param envir The environment to perform wiping on if \code{wipe == TRUE}. Defaults to
-#'              \code{.GlobalEnv} which is the global environment.
-#'
-#' @return NULL invisibly.
-#'
-#' @examples
-#' \donttest{
-#' data(agaricus.train, package = "lightgbm")
-#' train <- agaricus.train
-#' dtrain <- lgb.Dataset(train$data, label = train$label)
-#' data(agaricus.test, package = "lightgbm")
-#' test <- agaricus.test
-#' dtest <- lgb.Dataset.create.valid(dtrain, test$data, label = test$label)
-#' params <- list(
-#'   objective = "regression"
-#'   , metric = "l2"
-#'   , min_data = 1L
-#'   , learning_rate = 1.0
-#' )
-#' valids <- list(test = dtest)
-#' model <- lgb.train(
-#'   params = params
-#'   , data = dtrain
-#'   , nrounds = 5L
-#'   , valids = valids
-#' )
-#'
-#' lgb.unloader(restore = FALSE, wipe = FALSE, envir = .GlobalEnv)
-#' rm(model, dtrain, dtest) # Not needed if wipe = TRUE
-#' gc() # Not needed if wipe = TRUE
-#'
-#' library(lightgbm)
-#' # Do whatever you want again with LightGBM without object clashing
-#' }
-#' @export
-lgb.unloader <- function(restore = TRUE, wipe = FALSE, envir = .GlobalEnv) {
-
-  # Unload package
-  try(detach("package:lightgbm", unload = TRUE), silent = TRUE)
-
-  # Should we wipe variables? (lgb.Booster, lgb.Dataset)
-  if (wipe) {
-    boosters <- Filter(
-      f = function(x) {
-        inherits(get(x, envir = envir), "lgb.Booster")
-      }
-      , x = ls(envir = envir)
-    )
-    datasets <- Filter(
-      f = function(x) {
-        inherits(get(x, envir = envir), "lgb.Dataset")
-      }
-      , x = ls(envir = envir)
-    )
-    rm(list = c(boosters, datasets), envir = envir)
-    gc(verbose = FALSE)
-  }
-
-  # Load package back?
-  if (restore) {
-    library(lightgbm)
-  }
-
-  return(invisible(NULL))
-
-}

R-package/demo/weight_param.R

@@ -72,8 +72,6 @@ small_weight_loss <- as.numeric(model$record_evals$test$l2$eval)
 plot(small_weight_loss) # It learns!
 
 # Run 3: sum of weights equal to 6513 (x 1e5) with adjusted regularization (learning)
-# To make it better, we are first cleaning the environment and reloading LightGBM
-lgb.unloader(wipe = TRUE)
 
 # And now, we are doing as usual
 library(lightgbm)

R-package/man/lgb.unloader.Rd

-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/lgb.unloader.R
-\name{lgb.unloader}
-\alias{lgb.unloader}
-\title{Remove lightgbm and its objects from an environment}
-\usage{
-lgb.unloader(restore = TRUE, wipe = FALSE, envir = .GlobalEnv)
-}
-\arguments{
-\item{restore}{Whether to reload \code{LightGBM} immediately after detaching from R.
-Defaults to \code{TRUE} which means automatically reload \code{LightGBM} once
-unloading is performed.}
-
-\item{wipe}{Whether to wipe all \code{lgb.Dataset} and \code{lgb.Booster} from the global
-environment. Defaults to \code{FALSE} which means to not remove them.}
-
-\item{envir}{The environment to perform wiping on if \code{wipe == TRUE}. Defaults to
-\code{.GlobalEnv} which is the global environment.}
-}
-\value{
-NULL invisibly.
-}
-\description{
-Attempts to unload LightGBM packages so you can remove objects cleanly without
-             having to restart R. This is useful for instance if an object becomes stuck for no
-             apparent reason and you do not want to restart R to fix the lost object.
-}
-\examples{
-\donttest{
-data(agaricus.train, package = "lightgbm")
-train <- agaricus.train
-dtrain <- lgb.Dataset(train$data, label = train$label)
-data(agaricus.test, package = "lightgbm")
-test <- agaricus.test
-dtest <- lgb.Dataset.create.valid(dtrain, test$data, label = test$label)
-params <- list(
-  objective = "regression"
-  , metric = "l2"
-  , min_data = 1L
-  , learning_rate = 1.0
-)
-valids <- list(test = dtest)
-model <- lgb.train(
-  params = params
-  , data = dtrain
-  , nrounds = 5L
-  , valids = valids
-)
-
-lgb.unloader(restore = FALSE, wipe = FALSE, envir = .GlobalEnv)
-rm(model, dtrain, dtest) # Not needed if wipe = TRUE
-gc() # Not needed if wipe = TRUE
-
-library(lightgbm)
-# Do whatever you want again with LightGBM without object clashing
-}
-}

R-package/pkgdown/_pkgdown.yml

@@ -95,7 +95,3 @@ reference:
     - '`lgb.interprete`'
     - '`lgb.plot.importance`'
     - '`lgb.plot.interpretation`'
-  - title: Miscellaneous
-    desc: Ungroupable functions to troubleshoot LightGBM
-    contents:
-    - '`lgb.unloader`'

R-package/tests/testthat/test_lgb.unloader.R

-VERBOSITY <- as.integer(
-    Sys.getenv("LIGHTGBM_TEST_VERBOSITY", "-1")
-)
-
-CALCULATING_TEST_COVERAGE <- Sys.getenv("R_COVR", unset = "unset") != "unset"
-
-test_that("lgb.unloader works as expected", {
-    testthat::skip_if(
-        condition = CALCULATING_TEST_COVERAGE
-        , message = "lgb.unloader() tests are skipped when calculating test coverage"
-    )
-    data(agaricus.train, package = "lightgbm")
-    train <- agaricus.train
-    dtrain <- lgb.Dataset(train$data, label = train$label)
-    bst <- lgb.train(
-        params = list(
-            objective = "regression"
-            , metric = "l2"
-            , min_data = 1L
-            , learning_rate = 1.0
-            , verbosity = VERBOSITY
-        )
-        , data = dtrain
-        , nrounds = 1L
-    )
-    expect_true(exists("bst"))
-    result <- lgb.unloader(restore = TRUE, wipe = TRUE, envir = environment())
-    expect_false(exists("bst"))
-    expect_null(result)
-})
-
-test_that("lgb.unloader finds all boosters and removes them", {
-    testthat::skip_if(
-        condition = CALCULATING_TEST_COVERAGE
-        , message = "lgb.unloader() tests are skipped when calculating test coverage"
-    )
-    data(agaricus.train, package = "lightgbm")
-    train <- agaricus.train
-    dtrain <- lgb.Dataset(train$data, label = train$label)
-    bst1 <- lgb.train(
-        params = list(
-            objective = "regression"
-            , metric = "l2"
-            , min_data = 1L
-            , learning_rate = 1.0
-            , verbosity = VERBOSITY
-        )
-        , data = dtrain
-        , nrounds = 1L
-    )
-    bst2 <- lgb.train(
-        params = list(
-            objective = "regression"
-            , metric = "l2"
-            , min_data = 1L
-            , learning_rate = 1.0
-            , verbosity = VERBOSITY
-        )
-        , data = dtrain
-        , nrounds = 1L
-    )
-    expect_true(exists("bst1"))
-    expect_true(exists("bst2"))
-    lgb.unloader(restore = TRUE, wipe = TRUE, envir = environment())
-    expect_false(exists("bst1"))
-    expect_false(exists("bst2"))
-})

docs/FAQ.rst

@@ -247,9 +247,9 @@ R-package
 1. Any training command using LightGBM does not work after an error occurred during the training of a previous LightGBM model.
 ------------------------------------------------------------------------------------------------------------------------------
 
-Run ``lgb.unloader(wipe = TRUE)`` in the R console, and recreate the LightGBM datasets (this will wipe all LightGBM-related variables).
-Due to the pointers, choosing to not wipe variables will not fix the error.
-This is a known issue: `Microsoft/LightGBM#698 <https://github.com/microsoft/LightGBM/issues/698>`__.
+In older versions of the R package (prior to ``v3.3.0``), this could happen occasionally and the solution was to run ``lgb.unloader(wipe = TRUE)`` to remove all LightGBM-related objects. Some conversation about this could be found in `Microsoft/LightGBM#698 <https://github.com/microsoft/LightGBM/issues/698>`__.
+
+That is no longer necessary as of ``v3.3.0``, and function ``lgb.unloader()`` has since been removed from the R package.
 
 2. I used ``setinfo()``, tried to print my ``lgb.Dataset``, and now the R console froze!
 ----------------------------------------------------------------------------------------