LightGBM

https://lightgbm.readthedocs.io/en/stable/
Admin
LightGBM is a gradient boosting framework using tree-based learning algorithms, designed for...
Tokens:402,248
Snippets:2,680
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Error: setup script specifies an absolute path

Source: https://lightgbm.readthedocs.io/en/stable/FAQ.html

Example error message when running `python setup.py install` for LightGBM versions prior to v4.0.0. As of v4.0.0, directly invoking setup.py is not supported.

```text
error: Error: setup script specifies an absolute path:
/Users/Microsoft/LightGBM/python-package/lightgbm/../../lib_lightgbm.so
setup() arguments must *always* be /-separated paths relative to the setup.py directory, *never* absolute paths.

```

--------------------------------

### Install LightGBM from source with pip install --no-binary lightgbm lightgbm

Source: https://lightgbm.readthedocs.io/en/stable/FAQ.html

Command to install LightGBM from source, recommended when encountering segfaults after installing from PyPI.

```bash
pip install --no-binary lightgbm lightgbm
```

--------------------------------

### Install Python interface and dependencies

Source: https://lightgbm.readthedocs.io/en/stable/_sources/GPU-Tutorial.rst.txt

Install the Python interface of LightGBM along with necessary Python-package dependencies. After installation, set the parameter "device": "gpu" to use GPU in Python.

```bash
sudo apt-get -y install python3-pip python3-venv
sudo -H pip install numpy scipy scikit-learn -U
sudo sh ./build-python.sh install --precompile
```

--------------------------------

### Install Python Interface and Dependencies

Source: https://lightgbm.readthedocs.io/en/stable/GPU-Tutorial.html

Installs the LightGBM Python interface and required Python packages (numpy, scipy, scikit-learn) using pip, then builds and installs the Python package with GPU precompilation.

```bash
sudo apt-get -y install python3-pip python3-venv
sudo -H pip install numpy scipy scikit-learn -U
sudo sh ./build-python.sh install --precompile

```

--------------------------------

### Install building tools and dependencies for LightGBM

Source: https://lightgbm.readthedocs.io/en/stable/GPU-Tutorial.html

Install git, cmake, build-essential, and Boost libraries required to build LightGBM.

```bash
sudo apt-get install --no-install-recommends git cmake build-essential libboost-dev libboost-system-dev libboost-filesystem-dev

```

--------------------------------

### Verify LightGBM installation

Source: https://lightgbm.readthedocs.io/en/stable/Python-Intro.html

Import LightGBM in Python to verify the installation.

```python
import lightgbm as lgb

```

--------------------------------

### Restart server after driver installation

Source: https://lightgbm.readthedocs.io/en/stable/GPU-Tutorial.html

Restart the server after installing NVIDIA drivers. The server should be up again after about 30 seconds.

```bash
sudo init 6

```

--------------------------------

### feature_importance

Source: https://lightgbm.readthedocs.io/en/stable/_modules/lightgbm/basic.html

Get feature importances.

```APIDOC
## feature_importance

### Description
Get feature importances.

### Method
feature_importance

### Parameters
- **importance_type** (str, optional, default="split") - How the importance is calculated. If "split", result contains numbers of times the feature is used in a model. If "gain", result contains total gains of splits which use the feature.
- **iteration** (int or None, optional, default=None) - Limit number of iterations in the feature importance calculation. If None, if the best iteration exists, it is used; otherwise, all trees are used. If <= 0, all trees are used (no limits).

### Returns
- **result** (numpy array) - Array with feature importances.

```

--------------------------------

### Get inner evaluation count and names with LGBM_BoosterGetEvalCounts and LGBM_BoosterGetEvalNames

Source: https://lightgbm.readthedocs.io/en/stable/_modules/lightgbm/basic.html

Internal method that retrieves the number and names of inner evaluation metrics using LGBM_BoosterGetEvalCounts and LGBM_BoosterGetEvalNames. It reallocates string buffers if the reserved size is insufficient and raises ValueError if the number of eval names does not match the count. It also determines which metrics are higher-better based on name prefixes.

```python
    def __get_eval_info(self) -> None:
        """Get inner evaluation count and names."""
        if self.__need_reload_eval_info:
            self.__need_reload_eval_info = False
            out_num_eval = ctypes.c_int(0)
            # Get num of inner evals
            _safe_call(
                _LIB.LGBM_BoosterGetEvalCounts(
                    self._handle,
                    ctypes.byref(out_num_eval),
                )
            )
            self.__num_inner_eval = out_num_eval.value
            if self.__num_inner_eval > 0:
                # Get name of eval metrics
                tmp_out_len = ctypes.c_int(0)
                reserved_string_buffer_size = 255
                required_string_buffer_size = ctypes.c_size_t(0)
                string_buffers = [
                    ctypes.create_string_buffer(reserved_string_buffer_size) for _ in range(self.__num_inner_eval)
                ]
                ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(*map(ctypes.addressof, string_buffers))  # type: ignore[misc]
                _safe_call(
                    _LIB.LGBM_BoosterGetEvalNames(
                        self._handle,
                        ctypes.c_int(self.__num_inner_eval),
                        ctypes.byref(tmp_out_len),
                        ctypes.c_size_t(reserved_string_buffer_size),
                        ctypes.byref(required_string_buffer_size),
                        ptr_string_buffers,
                    )
                )
                if self.__num_inner_eval != tmp_out_len.value:
                    raise ValueError("Length of eval names doesn't equal with num_evals")
                actual_string_buffer_size = required_string_buffer_size.value
                # if buffer length is not long enough, reallocate buffers
                if reserved_string_buffer_size < actual_string_buffer_size:
                    string_buffers = [
                        ctypes.create_string_buffer(actual_string_buffer_size) for _ in range(self.__num_inner_eval)
                    ]
                    ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(
                        *map(ctypes.addressof, string_buffers)
                    )  # type: ignore[misc]
                    _safe_call(
                        _LIB.LGBM_BoosterGetEvalNames(
                            self._handle,
                            ctypes.c_int(self.__num_inner_eval),
                            ctypes.byref(tmp_out_len),
                            ctypes.c_size_t(actual_string_buffer_size),
                            ctypes.byref(required_string_buffer_size),
                            ptr_string_buffers,
                        )
                    )
                self.__name_inner_eval = [string_buffers[i].value.decode("utf-8") for i in range(self.__num_inner_eval)]
                self.__higher_better_inner_eval = [
                    name.startswith(("auc", "ndcg@", "map@", "average_precision")) for name in self.__name_inner_eval
                ]
```

--------------------------------

### Booster.upper_bound()

Source: https://lightgbm.readthedocs.io/en/stable/_modules/lightgbm/basic.html

Gets the upper bound value of a model.

```APIDOC
## Booster.upper_bound()

### Description
Gets the upper bound value of a model.

### Method
upper_bound()

### Returns
- **upper_bound** (float) - Upper bound value of the model.
```

--------------------------------

### Dataset.subset

Source: https://lightgbm.readthedocs.io/en/stable/_modules/lightgbm/basic.html

Gets a subset of the current Dataset using the specified indices. The subset shares the same feature names, categorical features, and predictor as the original Dataset.

```APIDOC
## Dataset.subset

### Description
Gets a subset of the current Dataset using the specified indices. The subset shares the same feature names, categorical features, and predictor as the original Dataset.

### Method
subset

### Parameters
- **used_indices** (list of int) - Required - Indices used to create the subset.
- **params** (dict, None) - Optional (default=None) - These parameters will be passed to Dataset constructor.

### Returns
- **subset** (Dataset) - Subset of the current Dataset.
```

--------------------------------

### Set up workspace on /mnt/workspace

Source: https://lightgbm.readthedocs.io/en/stable/GPU-Tutorial.html

Create and change to a workspace directory on the NV6 instance's SSD. Skip if using your own machine.

```bash
sudo mkdir -p /mnt/workspace
sudo chown $(whoami):$(whoami) /mnt/workspace
cd /mnt/workspace

```

--------------------------------

### Example: get column names of lgb.Dataset

Source: https://lightgbm.readthedocs.io/en/stable/R/reference/dimnames.lgb.Dataset.html

Example from the documentation showing how to get the dimension names of an lgb.Dataset. The output shows that row names are NULL and column names are the feature names from the agaricus dataset.

```r
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
lgb.Dataset.construct(dtrain)
dimnames(dtrain)
#> [[1]]
#> NULL
#> 
#> [[2]]
#>   [1] "cap-shape=bell"                   "cap-shape=conical"               
#>   [3] "cap-shape=convex"                 "cap-shape=flat"                  
#>   [5] "cap-shape=knobbed"                "cap-shape=sunken"                
#>   [7] "cap-surface=fibrous"              "cap-surface=grooves"             
#>   [9] "cap-surface=scaly"                "cap-surface=smooth"              
#>  [11] "cap-color=brown"                  "cap-color=buff"                  
#>  [13] "cap-color=cinnamon"               "cap-color=gray"                  
#>  [15] "cap-color=green"                  "cap-color=pink"                  
#>  [17] "cap-color=purple"                 "cap-color=red"                   
#>  [19] "cap-color=white"                  "cap-color=yellow"                
#>  [21] "bruises?=bruises"                 "bruises?=no"                     
#>  [23] "odor=almond"                      "odor=anise"                      
#>  [25] "odor=creosote"                    "odor=fishy"                      
#>  [27] "odor=foul"                        "odor=musty"                      
#>  [29] "odor=none"                        "odor=pungent"                    
#>  [31] "odor=spicy"                       "gill-attachment=attached"        
#>  [33] "gill-attachment=descending"       "gill-attachment=free"            
#>  [35] "gill-attachment=notched"          "gill-spacing=close"              
#>  [37] "gill-spacing=crowded"             "gill-spacing=distant"            
#>  [39] "gill-size=broad"                  "gill-size=narrow"                
#>  [41] "gill-color=black"                 "gill-color=brown"                
#>  [43] "gill-color=buff"                  "gill-color=chocolate"            
#>  [45] "gill-color=gray"                  "gill-color=green"                
#>  [47] "gill-color=orange"                "gill-color=pink"                 
#>  [49] "gill-color=purple"                "gill-color=red"                  
#>  [51] "gill-color=white"                 "gill-color=yellow"               
#>  [53] "stalk-shape=enlarging"            "stalk-shape=tapering"            
#>  [55] "stalk-root=bulbous"               "stalk-root=club"                 
#>  [57] "stalk-root=cup"                   "stalk-root=equal"                
#>  [59] "stalk-root=rhizomorphs"           "stalk-root=rooted"               
#>  [61] "stalk-root=missing"               "stalk-surface-above-ring=fibrous"
#>  [63] "stalk-surface-above-ring=scaly"   "stalk-surface-above-ring=silky"  
#>  [65] "stalk-surface-above-ring=smooth"  "stalk-surface-below-ring=fibrous"
#>  [67] "stalk-surface-below-ring=scaly"   "stalk-surface-below-ring=silky"  
#>  [69] "stalk-surface-below-ring=smooth"  "stalk-color-above-ring=brown"    
#>  [71] "stalk-color-above-ring=buff"      "stalk-color-above-ring=cinnamon" 
#>  [73] "stalk-color-above-ring=gray"      "stalk-color-above-ring=orange"   
#>  [75] "stalk-color-above-ring=pink"      "stalk-color-above-ring=red"      
#>  [77] "stalk-color-above-ring=white"     "stalk-color-above-ring=yellow"   
#>  [79] "stalk-color-below-ring=brown"     "stalk-color-below-ring=buff"     
#>  [81] "stalk-color-below-ring=cinnamon"  "stalk-color-below-ring=gray"     
#>  [83] "stalk-color-below-ring=orange"    "stalk-color-below-ring=pink"     
#>  [85] "stalk-color-below-ring=red"       "stalk-color-below-ring=white"    
#>  [87] "stalk-color-below-ring=yellow"    "veil-type=partial"               
#>  [89] "veil-type=universal"              "veil-color=brown"                
#>  [91] "veil-color=orange"                "veil-color=white"                
#>  [93] "veil-color=yellow"                "ring-number=none"                
#>  [95] "ring-number=one"                  "ring-number=two"                 
#>  [97] "ring-type=cobwebby"               "ring-type=evanescent"            
#>  [99] "ring-type=flaring"                "ring-type=large"                 
#> [101] "ring-type=none"                   "ring-type=pendant"               
```

--------------------------------

### Build documentation with Docker

Source: https://lightgbm.readthedocs.io/en/stable/README.html

Build the LightGBM documentation locally using the same Docker image Read the Docs uses. Run from the repository root; after completion, open docs/_build/html/index.html in your browser.

```bash
docker run \
    --rm \
    --user=0 \
    -v $(pwd):/opt/LightGBM \
    --env C_API=true \
    --env CONDA=/opt/miniforge \
    --env READTHEDOCS=true \
    --workdir=/opt/LightGBM/docs \
    --entrypoint="" \
    readthedocs/build:ubuntu-24.04-2024.06.17 \
    /bin/bash build-docs.sh

```

--------------------------------

### LGBMRegressor.get_metadata_routing

Source: https://lightgbm.readthedocs.io/en/stable/pythonapi/lightgbm.LGBMRegressor.html

Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

```APIDOC
## LGBMRegressor.get_metadata_routing

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
get_metadata_routing

### Returns
- **routing** (MetadataRequest) - A `MetadataRequest` encapsulating routing information.
```

--------------------------------

### Example: train model and plot feature contribution

Source: https://lightgbm.readthedocs.io/en/stable/R/reference/lgb.plot.interpretation.html

Complete example that trains a LightGBM model on the agaricus dataset and then plots the top 3 feature contributions using lgb.plot.interpretation. Includes setup of the dataset, parameters, and the plot call.

```r
# \donttest{
Logit <- function(x) {
  log(x / (1.0 - x))
}
data(agaricus.train, package = "lightgbm")
labels <- agaricus.train$label
dtrain <- lgb.Dataset(
  agaricus.train$data
  , label = labels
)
set_field(
  dataset = dtrain
  , field_name = "init_score"
  , data = rep(Logit(mean(labels)), length(labels))
)

data(agaricus.test, package = "lightgbm")

params <- list(
  objective = "binary"
  , learning_rate = 0.1
  , max_depth = -1L
  , min_data_in_leaf = 1L
  , min_sum_hessian_in_leaf = 1.0
  , num_threads = 2L
)
model <- lgb.train(
  params = params
  , data = dtrain
  , nrounds = 5L
)
#> [LightGBM] [Info] Number of positive: 3140, number of negative: 3373
#> [LightGBM] [Info] Auto-choosing row-wise multi-threading, the overhead of testing was 0.000620 seconds.
#> You can set `force_row_wise=true` to remove the overhead.
#> And if memory is not enough, you can set `force_col_wise=true`.
#> [LightGBM] [Info] Total Bins 232
#> [LightGBM] [Info] Number of data points in the train set: 6513, number of used features: 116
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf

tree_interpretation <- lgb.interpret(
  model = model
  , data = agaricus.test$data
  , idxset = 1L:5L
)
lgb.plot.interpretation(
  tree_interpretation_dt = tree_interpretation[[1L]]
  , top_n = 3L
)

# }
```

--------------------------------

### Create GPU Configuration File

Source: https://lightgbm.readthedocs.io/en/stable/GPU-Tutorial.html

Creates a LightGBM configuration file (lightgbm_gpu.conf) with GPU settings and appends the number of threads. The configuration uses device=gpu, gpu_platform_id=0, and gpu_device_id=0.

```bash
cat > lightgbm_gpu.conf <<EOF
max_bin = 63
num_leaves = 255
num_iterations = 50
learning_rate = 0.1
tree_learner = serial
task = train
is_training_metric = false
min_data_in_leaf = 1
min_sum_hessian_in_leaf = 100
ndcg_eval_at = 1,3,5,10
device = gpu
gpu_platform_id = 0
gpu_device_id = 0
EOF
echo "num_threads=$(nproc)" >> lightgbm_gpu.conf

```

--------------------------------

### Fix 'setup script specifies an absolute path' error

Source: https://lightgbm.readthedocs.io/en/stable/_sources/FAQ.rst.txt

This error occurs when installing lightgbm from GitHub using 'python setup.py install' in versions prior to v4.0.0. The error is solved in the latest version; if it persists, remove the 'lightgbm.egg-info' folder and reinstall.

```console
error: Error: setup script specifies an absolute path:
/Users/Microsoft/LightGBM/python-package/lightgbm/../../lib_lightgbm.so
setup() arguments must *always* be /-separated paths relative to the setup.py directory, *never* absolute paths.
```

--------------------------------

### Override compilers in ~/.R/Makevars

Source: https://lightgbm.readthedocs.io/en/stable/R/index.html

Example ~/.R/Makevars file to override the C and C++ compilers used when installing the CRAN package. Shown for using gcc-14 instead of clang on macOS.

```bash
# ~/.R/Makevars
CC=gcc-14
CC17=gcc-14
CXX=g++-14
CXX17=g++-14
```

--------------------------------

### Run LightGBM with command-line parameter override

Source: https://lightgbm.readthedocs.io/en/stable/Quick-Start.html

Command line parameters have higher priority than config file parameters. This example keeps num_trees=10 and ignores the same parameter in the config file.

```bash
lightgbm config=train.conf num_trees=10
```

--------------------------------

### Verify LightGBM R-package installation

Source: https://lightgbm.readthedocs.io/en/stable/R/index.html

Quick check that the LightGBM R-package is working. Loads the package, creates a dataset from the agaricus.train example, and runs cross-validation with a regression objective and L2 metric.

```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
)
```

--------------------------------

### Load LightGBM model from file or string

Source: https://lightgbm.readthedocs.io/en/stable/R/reference/lgb.load.html

Example demonstrating training a model, saving it to a file, and loading it back from both a file and a string representation.

```R
# \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
  , num_threads = 2L
)
valids <- list(test = dtest)
model <- lgb.train(
  params = params
  , data = dtrain
  , nrounds = 5L
  , valids = valids
  , early_stopping_rounds = 3L
)
#> [LightGBM] [Info] Auto-choosing row-wise multi-threading, the overhead of testing was 0.000615 seconds.
#> You can set `force_row_wise=true` to remove the overhead.
#> And if memory is not enough, you can set `force_col_wise=true`.
#> [LightGBM] [Info] Total Bins 232
#> [LightGBM] [Info] Number of data points in the train set: 6513, number of used features: 116
#> [LightGBM] [Info] Start training from score 0.482113
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [1]:  test's l2:6.44165e-17 
#> Will train until there is no improvement in 3 rounds.
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [2]:  test's l2:1.97215e-31 
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [3]:  test's l2:0 
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] Stopped training because there are no more leaves that meet the split requirements
#> [4]:  test's l2:0 
#> [LightGBM] [Warning] No further splits with positive gain, best gain: -inf
#> [LightGBM] [Warning] Stopped training because there are no more leaves that meet the split requirements
#> [5]:  test's l2:0 
#> Did not meet early stopping, best iteration is: [3]:  test's l2:0
model_file <- tempfile(fileext = ".txt")
lgb.save(model, model_file)
load_booster <- lgb.load(filename = model_file)
model_string <- model$save_model_to_string(NULL) # saves best iteration
load_booster_from_str <- lgb.load(model_str = model_string)
# }
```

--------------------------------

### R error: package ‘Matrix’ is not available

Source: https://lightgbm.readthedocs.io/en/stable/FAQ.html

Example error message shown when installing the lightgbm R-package on R versions older than 4.4.0, because Matrix 1.7-0 requires R >= 4.4.0.

```text
package ‘Matrix’ is not available for this version of R

```

--------------------------------

### Build LightGBM MPI on Windows from Command Line

Source: https://lightgbm.readthedocs.io/en/stable/Installation-Guide.html

Build the MPI version of LightGBM on Windows from the command line. Requires MS MPI (msmpisdk.msi and msmpisetup.exe), Git for Windows, CMake, and VS Build Tools (or Visual Studio). The resulting .exe and .dll files are placed in the LightGBM/Release folder.

```bash
git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DUSE_MPI=ON
cmake --build build --target ALL_BUILD --config Release

```

--------------------------------

### Install lightgbm from CRAN

Source: https://lightgbm.readthedocs.io/en/stable/R/index.html

Installs the lightgbm package from CRAN. This is the easiest installation method and does not require CMake or Visual Studio.

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

--------------------------------

### __init__

Source: https://lightgbm.readthedocs.io/en/stable/pythonapi/lightgbm.DaskLGBMRanker.html

Construct a gradient boosting model.

```APIDOC
## lightgbm.DaskLGBMRanker.__init__

### Description
Construct a gradient boosting model.

### Method
__init__

### Signature
__init__(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=100, subsample_for_bin=200000, objective=None, class_weight=None, min_split_gain=0.0, min_child_weight=1e-3, min_child_samples=20, subsample=1.0, subsample_freq=0, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=None, importance_type='split', **kwargs)
```

--------------------------------

### Install CRAN package with R CMD install

Source: https://lightgbm.readthedocs.io/en/stable/R/index.html

Installs a built CRAN package tarball. Use after building the package with build-cran-package.sh.

```bash
R CMD install lightgbm_*.tar.gz
```
Tokens:
Raw