LightGBM R 包

目录

• 安装
  • 安装 CRAN 包
  • 使用 CMake 从源码安装
  • 安装 GPU 版本的构建
  • 安装预编译二进制文件
  • 从预编译的 lib_lightgbm 安装
• 示例
• 测试
  • 运行测试
  • 代码覆盖率
• 更新文档
• 准备 CRAN 包
• 外部仓库
• 已知问题

安装

最简单的安装方法是，前往“安装 CRAN 包”。

如果遇到任何问题，请尝试“使用 CMake 从源码安装”。这可以在带有 Visual Studio 的 Windows 系统上生成更高效的库版本。

要构建启用 GPU 的包版本，请按照“安装 GPU 版本的构建”中的步骤进行操作。

如果以上任何选项都不适合您或无法满足您的需求，请通过提交议题告知维护者。

当您的包安装完成后，可以通过运行以下代码快速检查 LightGBM R 包是否正常工作

library(lightgbm)
data(agaricus.train, package='lightgbm')
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
model <- lgb.cv(
    params = list(
        objective = "regression"
        , metric = "l2"
    )
    , data = dtrain
)

安装 CRAN 包

lightgbm 可在 CRAN 上获取，并可通过以下 R 代码安装。

install.packages("lightgbm", repos = "https://cran.r-project.cn")

这是安装 lightgbm 的最简单方法。它不需要 CMake 或 Visual Studio，并且应该在许多不同的操作系统和编译器上运行良好。

每个 CRAN 包也在 LightGBM 发布页面上提供，名称类似于 lightgbm-{VERSION}-r-cran.tar.gz。

自定义安装 (Linux, Mac)

上述步骤应适用于大多数系统，但使用高度定制环境的用户可能希望更改 R 从源构建包的方式。

要更改安装 CRAN 包时使用的编译器，您可以创建文件 ~/.R/Makevars 来覆盖 CC (C 编译器) 和 CXX (C++ 编译器)。

例如，要在 Mac 上使用 gcc 而不是 clang，您可以使用以下内容

# ~/.R/Makevars
CC=gcc-8
CXX=g++-8
CXX11=g++-8

使用 CMake 从源码安装

您需要先安装 git 和 CMake。

注意：此方法仅支持 64 位系统。如果需要在 32 位 Windows (i386) 上运行 LightGBM，请按照“安装 CRAN 包”中的说明进行操作。

Windows 环境准备

注意：Windows 用户可能需要以管理员权限运行（取决于您安装此包的方式，可以是 R 或命令提示符）。

安装 64 位版本的 Rtools 是必须的。

安装 Rtools 和 CMake 后，请确保将以下路径添加到环境变量 PATH 中。这些路径可能在安装其他软件时已自动添加。

• Rtools
  • 如果您使用 Rtools 3.x，例如
    • C:\Rtools\mingw_64\bin
  • 如果您使用 Rtools 4.0，例如
    • C:\rtools40\mingw64\bin
    • C:\rtools40\usr\bin
  • 如果您使用 Rtools 4.2+，例如
    • C:\rtools42\x86_64-w64-mingw32.static.posix\bin
    • C:\rtools42\usr\bin
    • 注意：例如，对于 R 4.3，这是 rtools43\
• CMake
  • 例如：C:\Program Files\CMake\bin
• R
  • 例如：C:\Program Files\R\R-3.6.1\bin

注意：从 Rtools 4.0 开始需要两个 Rtools 路径，因为 Rtools 4.0 中更改了路径和包含的软件列表。

注意：Rtools42 及更高版本在编译器工具链方面与以前的版本有很大不同，并且您安装它的方式会改变构建包所需的内容。请参阅“如何：在 Windows 上构建 R 4.2 和包”。

Windows 工具链选项

“工具链”指的是用于构建库的软件集合。R 包可以使用三种不同的工具链进行构建。

Windows 用户注意：对于多核系统，建议在 Windows 中使用 Visual Studio，因为它具有更好的多线程效率。对于非常简单的系统（双核计算机或更差），建议使用 MinGW64 以获得最大性能。如果您不知道如何选择，建议使用默认编译器 Visual Studio。不要在多核系统上的 Windows 中尝试使用 MinGW。它的结果可能会比 Visual Studio 慢 10 倍。

Visual Studio (默认)

默认情况下，该包将使用 Visual Studio Build Tools 构建。

MinGW (R 3.x)

如果您使用的是 R 3.x 并且使用 Visual Studio 安装失败，LightGBM 将回退到使用 Rtools 捆绑的 MinGW。

如果要强制 LightGBM 使用 MinGW（适用于任何 R 版本），请将 --use-mingw 参数传递给安装脚本。

Rscript build_r.R --use-mingw

MSYS2 (R 4.x)

如果您使用的是 R 4.x 并且使用 Visual Studio 安装失败，LightGBM 将回退到使用 MSYS2。这应该适用于 Rtools 4.0 中已经捆绑的工具。

如果要强制 LightGBM 使用 MSYS2（适用于任何 R 版本），请将 --use-msys2 参数传递给安装脚本。

Rscript build_r.R --use-msys2

Mac OS 环境准备

您可以使用 Apple Clang 或 gcc 进行安装。如果您更喜欢 Apple Clang，则应先安装 OpenMP（安装详情可在安装指南中找到）。如果您更喜欢 gcc，则需要安装它（安装详情可在安装指南中找到），并设置一些环境变量来告诉 R 使用 gcc 和 g++。如果您通过 Homebrew 安装这些，您的 g++ 和 gcc 版本很可能位于 /usr/local/bin 中，如下所示。

# replace 8 with version of gcc installed on your machine
export CXX=/usr/local/bin/g++-8 CC=/usr/local/bin/gcc-8

使用 CMake 安装

在按照上面针对您的操作系统的“准备”步骤操作后，使用以下命令构建和安装 R 包

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
Rscript build_r.R

build_r.R 脚本在名为 lightgbm_r 的临时目录中构建包。每次运行脚本时，它都会销毁并重新创建该目录。该脚本支持以下命令行选项

• --no-build-vignettes: 跳过构建 vignettes。
• -j[jobs]: 编译 LightGBM 时使用的线程数。例如，-j4 将尝试同时编译 4 个对象。
  • 默认情况下，此脚本使用单线程编译
  • 为获得最佳结果，请将 -j 设置为物理 CPU 的数量
• --skip-install: 构建包的 tarball，但不安装它。
• --use-gpu: 构建库的 GPU 版本。
• --use-mingw: 强制使用 MinGW 工具链，无论 R 版本如何。
• --use-msys2: 强制使用 MSYS2 工具链，无论 R 版本如何。

注意：在 Windows 中使用 Visual Studio/VS Build Tools 进行构建时，您应该使用 Windows CMD 或 PowerShell。

安装 GPU 版本的构建

您需要先安装 Boost 和 OpenCL：安装详情可在安装指南中找到。

安装这些其他库后，请按照“使用 CMake 从源码安装”中的步骤进行操作。当您执行到提到 build_r.R 的步骤时，传递 --use-gpu 标志。

Rscript build_r.R --use-gpu

根据您的设置，您可能还需要或想要提供额外的配置。例如，您可能需要提供 Boost 和 OpenCL 的位置。

Rscript build_r.R \
    --use-gpu \
    --opencl-library=/usr/lib/x86_64-linux-gnu/libOpenCL.so \
    --boost-librarydir=/usr/lib/x86_64-linux-gnu

以下选项对应于同名的 CMake FindBoost 选项。

• --boost-root
• --boost-dir
• --boost-include-dir
• --boost-librarydir

以下选项对应于同名的 CMake FindOpenCL 选项。

• --opencl-include-dir
• --opencl-library

安装预编译二进制文件

CRAN 在每次发布到 CRAN 后几天，会为 Mac 和 Windows 准备预编译二进制文件。可以使用以下 R 代码安装它们。

install.packages(
    "lightgbm"
    , type = "both"
    , repos = "https://cran.r-project.cn"
)

这些包不需要编译，因此安装速度更快、更容易，比从源码构建的包要方便。

CRAN 不为 Linux 准备预编译二进制文件，并且截至本文撰写时，本项目也不提供。

从预编译的 lib_lightgbm 安装

LightGBM 的早期版本提供了先编译 C++ 库 (lib_lightgbm.{dll,dylib,so}) 然后构建一个包装它的 R 包的能力。

从版本 3.0.0 开始，这不再受支持。如果您从源构建有困难，请提交议题。

示例

请访问 demo

• 包装器基础教程
• 从现有预测结果进行 Boosting
• 提前停止
• 交叉验证
• 多分类训练/预测
• 叶子节点（不）稳定性
• 权重参数调整关系

测试

R 包的单元测试会在每次提交时通过 GitHub Actions 等集成自动运行。在 R-package/tests/testthat 中添加新测试是提高 R 包可靠性的重要途径。

运行测试

在开发 R 包时，运行以下代码来运行单元测试。

sh build-cran-package.sh \
    --no-build-vignettes

R CMD INSTALL --with-keep.source lightgbm*.tar.gz
cd R-package/tests
Rscript testthat.R

要使用更详细的日志运行测试，请将环境变量 LIGHTGBM_TEST_VERBOSITY 设置为参数 verbosity 的有效值。

export LIGHTGBM_TEST_VERBOSITY=1
cd R-package/tests
Rscript testthat.R

代码覆盖率

添加测试时，您可能希望使用测试覆盖率来识别未测试的区域，并检查您添加的测试是否覆盖了预期代码的所有分支。

以下示例显示了如何在 macOS 或 Linux 设置上为 R 包生成代码覆盖率。要根据您的环境进行调整，请参阅上面描述的自定义步骤。

# Install
sh build-cran-package.sh \
    --no-build-vignettes

# Get coverage
Rscript -e " \
    library(covr);
    coverage <- covr::package_coverage('./lightgbm_r', type = 'tests', quiet = FALSE);
    print(coverage);
    covr::report(coverage, file = file.path(getwd(), 'coverage.html'), browse = TRUE);
    "

更新文档

R 包使用 {roxygen2} 生成其文档。生成的 DESCRIPTION、NAMESPACE 和 man/ 文件已检入到源代码控制中。要重新生成这些文件，请运行以下命令。

Rscript \
    --vanilla \
    -e "install.packages('roxygen2', repos = 'https://cran.rstudio.com')"

sh build-cran-package.sh --no-build-vignettes
R CMD INSTALL \
  --with-keep.source \
  ./lightgbm_*.tar.gz

cd R-package
Rscript \
    --vanilla \
    -e "roxygen2::roxygenize(load = 'installed')"

准备 CRAN 包

本节主要供维护者参考，但也可能帮助用户和贡献者理解 R 包的结构。

LightGBM 的大部分使用 CMake 来处理设置编译器和链接器标志、包含头文件位置以及链接到其他库等任务。由于 CRAN 包通常不假定存在 CMake，因此 R 包使用 CRAN 支持的工具链中构建包含 C++ 代码的 R 包的替代方法：Autoconf。

有关此方法的更多信息，请参阅“编写 R 扩展”。

构建 CRAN 包

从仓库的根目录运行以下命令。

git submodule update --init --recursive
sh build-cran-package.sh

这将创建一个文件 lightgbm_${VERSION}.tar.gz，其中 VERSION 是 LightGBM 的版本。

该脚本支持以下命令行选项

• --no-build-vignettes: 跳过构建 vignettes。
• --r-executable=[可执行文件路径]: 使用替代的 R 构建。

此外，CRAN 包在对任何仓库分支的每次提交时都会生成，并可在相关 Azure Pipelines 运行的“Artifacts”部分找到。

从 CRAN 包进行标准安装

构建包后，使用以下命令进行安装

R CMD install lightgbm_*.tar.gz

修改 CRAN 包

很多细节都由 R CMD build 和 R CMD install 自动处理，因此可能难以理解 R 包中的文件是如何相互关联的。有关这些细节的全面论述可在“编写 R 扩展”中找到。

本节简要说明了构建 CRAN 包的关键文件。要更新包，请编辑与您的更改相关的文件，然后重新运行构建 CRAN 包中的步骤。

Linux 或 Mac

构建时，将运行 configure 并使用 Makevars.in 作为模板创建文件 Makevars。

1. 编辑 configure.ac。

2. 使用 autoconf 创建 configure。不要手动编辑。此文件必须在 Ubuntu 22.04 上生成。

   如果您有可用的 Ubuntu 22.04 环境，请从 LightGBM 仓库的根目录运行提供的脚本。

   ./R-package/recreate-configure.sh

   如果您无法轻松访问 Ubuntu 22.04 环境，可以通过从本仓库根目录运行以下代码，使用 Docker 生成 configure 脚本。

   docker run \
       --rm \
       -v $(pwd):/opt/LightGBM \
       -w /opt/LightGBM \
       ubuntu:22.04 \
       ./R-package/recreate-configure.sh

   本项目使用的 autoconf 版本存储在 R-package/AUTOCONF_UBUNTU_VERSION 中。要更新该版本，请更新该文件并运行上述命令。要查看可用版本，请参阅 https://packages.ubuntu.com/search?keywords=autoconf。

3. 编辑 src/Makevars.in。

或者，GitHub Actions 可以为您重新生成此文件。在拉取请求中（仅限内部拉取请求，不适用于分叉仓库的拉取请求），使用以下短语创建评论

/gha run r-configure

Windows 配置

构建时，将运行 configure.win 并使用 Makevars.win.in 作为模板创建文件 Makevars.win。

1. 直接编辑 configure.win。
2. 编辑 src/Makevars.win.in。

测试 CRAN 包

lightgbm 在每次提交时都会自动测试，涵盖了操作系统、R 版本和编译器的多种组合。本节介绍在开发期间如何在本地测试包。

Windows, Mac 和 Linux

sh build-cran-package.sh
R CMD check --as-cran lightgbm_*.tar.gz

ASAN 和 UBSAN

所有上传到 CRAN 的包必须通过使用 gcc 和 clang 构建的测试，并使用两个 sanitizers 进行检测：Address Sanitizer (ASAN) 和 Undefined Behavior Sanitizer (UBSAN)。

更多背景信息，请参阅

• 这篇博客文章
• CRAN 关于这些检查的顶级文档
• CRAN 对这些检查的配置

您可以使用 Docker 在本地复制这些检查。有关用于测试的镜像的更多信息，请参阅 https://github.com/wch/r-debug。

在下面的代码中，环境变量 R_CUSTOMIZATION 应设置为以下两个值之一。

• "san" = 复制 CRAN 的 gcc-ASAN 和 gcc-UBSAN 检查
• "csan" = 复制 CRAN 的 clang-ASAN 和 clang-UBSAN 检查

docker run \
  --rm \
  -it \
  -v $(pwd):/opt/LightGBM \
  -w /opt/LightGBM \
  --env R_CUSTOMIZATION=san \
  wch1/r-debug:latest \
  /bin/bash

# install dependencies
RDscript${R_CUSTOMIZATION} \
  -e "install.packages(c('R6', 'data.table', 'jsonlite', 'knitr', 'markdown', 'Matrix', 'RhpcBLASctl', 'testthat'), repos = 'https://cran.r-project.cn', Ncpus = parallel::detectCores())"

# install lightgbm
sh build-cran-package.sh --r-executable=RD${R_CUSTOMIZATION}
RD${R_CUSTOMIZATION} \
  CMD INSTALL lightgbm_*.tar.gz

# run tests
cd R-package/tests
rm -f ./tests.log
RDscript${R_CUSTOMIZATION} testthat.R >> tests.log 2>&1

# check that tests passed
echo "test exit code: $?"
tail -300 ./tests.log

Valgrind

所有上传到 CRAN 的包必须在构建和测试时，不产生任何 valgrind 报告的问题。valgrind 是一个性能分析工具，可以捕获内存泄漏和非法写入等严重问题。更多信息请参阅这篇博客文章。

您可以使用 Docker 在本地复制这些检查。请注意，为使用 valgrind 而构建的经过检测的 R 版本运行速度慢很多，这些测试可能需要长达 20 分钟才能运行完成。

docker run \
    --rm \
    -v $(pwd):/opt/LightGBM \
    -w /opt/LightGBM \
    -it \
        wch1/r-debug

RDscriptvalgrind -e "install.packages(c('R6', 'data.table', 'jsonlite', 'knitr', 'markdown', 'Matrix', 'RhpcBLASctl', 'testthat'), repos = 'https://cran.rstudio.com', Ncpus = parallel::detectCores())"

sh build-cran-package.sh \
    --r-executable=RDvalgrind

RDvalgrind CMD INSTALL \
    --preclean \
    --install-tests \
        lightgbm_*.tar.gz

cd R-package/tests

RDvalgrind \
    --no-readline \
    --vanilla \
    -d "valgrind --tool=memcheck --leak-check=full --track-origins=yes" \
        -f testthat.R \
2>&1 \
| tee out.log \
| cat

这些测试也可以通过在拉取请求中留下评论来触发

/gha run r-valgrind

已知问题

有关 R 包的已知问题信息，请参阅 LightGBM 主要 FAQ 页面的 R 包部分。