### LightGBM Error Handling and Model Parsing Setup

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

This snippet demonstrates the initial checks and setup for parsing a LightGBM model. It includes error handling for missing pandas installation and ensures that the booster contains trees before proceeding with parsing.

```python
from typing import Dict, Any, Optional, List, Union
from collections import OrderedDict

# Assume PANDAS_INSTALLED and LightGBMError are defined elsewhere
# class LightGBMError(Exception):
#     pass
# PANDAS_INSTALLED = True # Placeholder

def parse_model(self) -> pandas.DataFrame:
    """
    Parses the model into a pandas DataFrame.

    Returns
    -------
    result : pandas DataFrame
        Returns a pandas DataFrame of the parsed model.
    """
    if not PANDAS_INSTALLED:
        raise LightGBMError(
            "This method cannot be run without pandas installed. "
            "You must install pandas and restart your session to use this method."
        )

    if self.num_trees() == 0:
        raise LightGBMError("There are no trees in this Booster and thus nothing to parse")

    def _is_split_node(tree: Dict[str, Any]) -> bool:
        return "split_index" in tree.keys()

    def create_node_record(
        tree: Dict[str, Any],
        node_depth: int = 1,
        tree_index: Optional[int] = None,
        feature_names: Optional[List[str]] = None,
        parent_node: Optional[str] = None,
    ) -> Dict[str, Any]:
        def _get_node_index(
            tree: Dict[str, Any],
            tree_index: Optional[int],
        ) -> str:
            tree_num = f"{tree_index}-" if tree_index is not None else ""
            is_split = _is_split_node(tree)
            node_type = "S" if is_split else "L"
            # if a single node tree it won't have `leaf_index` so return 0
            node_num = tree.get("split_index" if is_split else "leaf_index", 0)
            return f"{tree_num}{node_type}{node_num}"

        def _get_split_feature(
            tree: Dict[str, Any],
            feature_names: Optional[List[str]],
        ) -> Optional[str]:
            if _is_split_node(tree):
                if feature_names is not None:
                    feature_name = feature_names[tree["split_feature"]]
                else:
                    feature_name = tree["split_feature"]
            else:
                feature_name = None
            return feature_name

        def _is_single_node_tree(tree: Dict[str, Any]) -> bool:
            return set(tree.keys()) == {"leaf_value", "leaf_count"}

        # Create the node record, and populate universal data members
        node: Dict[str, Union[int, str, None]] = OrderedDict()
        node["tree_index"] = tree_index
        node["node_depth"] = node_depth
        node["node_index"] = _get_node_index(tree, tree_index)
        node["left_child"] = None
        node["right_child"] = None
        node["parent_index"] = parent_node
        node["split_feature"] = _get_split_feature(tree, feature_names)
        node["split_gain"] = None
        node["threshold"] = None
        node["decision_type"] = None
        node["missing_direction"] = None
        node["missing_type"] = None
        node["value"] = None
        node["weight"] = None
        node["count"] = None

```

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

### Dask Distributed Training

Source: https://lightgbm.readthedocs.io/en/stable/_sources/Parallel-Learning-Guide.rst.txt

Example of setting up a Dask cluster and training a LightGBM model in a distributed fashion. Requires Dask and LightGBM installed.

```python
cluster = LocalCluster(n_workers=2)
client = Client(cluster)

X = da.random.random((1000, 10), (500, 10))
y = da.random.random((1000,), (500,))

dask_model = lgb.DaskLGBMRegressor()
dask_model.fit(X, y)

# get underlying Booster object
bst = dask_model.booster_
```

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

### Python setup.py install absolute path error (pre-v4.0.0)

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

For LightGBM versions prior to v4.0.0, the setup script must use relative paths. This error indicates an absolute path was incorrectly specified.

```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 Build Tools and Dependencies

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

Installs essential tools and libraries required for building LightGBM, including git, cmake, and boost.

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

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

### Install Build Tools and Dependencies

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

Installs essential tools like git and cmake, along with Boost libraries required for building LightGBM.

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

```

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

### Install Python Interface for LightGBM

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

Installs the Python package manager and necessary Python dependencies, then builds and installs the LightGBM Python interface.

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

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

### Example usage of lgb.Dataset

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

Example demonstrating how to create an `lgb.Dataset` from data, save it to a file, and then load it back.

```R
# \donttest{ 
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
data_file <- tempfile(fileext = ".data")
lgb.Dataset.save(dtrain, data_file)
#> [LightGBM] [Info] Saving data to binary file /tmp/RtmpViPAUB/file13c558b8a1e2.data
dtrain <- lgb.Dataset(data_file)
lgb.Dataset.construct(dtrain)
#> [LightGBM] [Info] Load from binary file /tmp/RtmpViPAUB/file13c558b8a1e2.data
# }
```

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

### Install LightGBM via Pip

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

Use pip to install the LightGBM Python package. This is the recommended installation method.

```bash
pip install lightgbm

```

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

### Examples

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

Example of constructing a dataset.

```R
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
lgb.Dataset.construct(dtrain)
# }
```

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

### Example of saving an lgb.Dataset

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

This example demonstrates how to create an lgb.Dataset from sample data and then save it to a binary file using lgb.Dataset.save().

```R
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
lgb.Dataset.save(dtrain, tempfile(fileext = ".bin"))
# }
```

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

### Example of loading a LightGBM model

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

This example demonstrates how to train a LightGBM model, save it to a file, and then load it back using lgb.load. It also shows loading from a model string.

```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.000705 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)
# }
```

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

### Install LightGBM Python Interface

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

Installs the Python package manager, LightGBM's Python interface, and necessary dependencies. Ensure you have sudo privileges.

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

```

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

### Set Up Workspace and Clone LightGBM

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

Creates a workspace directory, sets ownership, and clones the LightGBM repository. Assumes an SSD mount at /mnt.

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

git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
```

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

### Set Up Workspace Directory

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

Creates and configures a workspace directory on the SSD mount for building LightGBM. This step is optional if using your own machine.

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

```

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

### Get Reference Chain of Datasets

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

Obtains a chain of Dataset objects starting from the current one and following its references. Useful for understanding dataset lineage and detecting reference loops, up to a specified limit.

```python
head = self
ref_chain: Set[Dataset] = set()
while len(ref_chain) < ref_limit:
    if isinstance(head, Dataset):
        ref_chain.add(head)
        if (head.reference is not None) and (head.reference not in ref_chain):
            head = head.reference
        else:
            break
    else:
        break
return ref_chain
```

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

### Dataset Push Rows Example

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

Internal method to push rows of data into a Dataset object. It handles data pointers, types, and row counts, updating the internal start row index.

```python
        _safe_call(
            _LIB.LGBM_DatasetPushRows(
                self._handle,
                data_ptr,
                data_type,
                ctypes.c_int32(nrow),
                ctypes.c_int32(ncol),
                ctypes.c_int32(self._start_row),
            )
        )
        self._start_row += nrow
        return self
```

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

### Run Distributed Learning (MPI Version - Windows)

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

Launches a LightGBM distributed learning job on Windows using MPI. Requires mpiexec, a machine list file, and a configuration file.

```bash
mpiexec.exe /machinefile mlist.txt lightgbm.exe config=your_config_file

```

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

### Build Java Wrapper with MinGW-w64 on Windows

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

Create a JAR file for the LightGBM Java wrapper on Windows using MinGW-w64. Requires Git, CMake, MinGW-w64, SWIG, and Java with JAVA_HOME configured. Note potential 'sh.exe' path issues.

```bash
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
cmake --build build -j4
```

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

### Create LightGBM Configuration for GPU

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

Creates a configuration file for LightGBM, enabling GPU training by setting 'device=gpu' and specifying GPU platform and device IDs. Appends the number of threads based on available processors.

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

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

### Install LightGBM using Homebrew on macOS

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

Install LightGBM on macOS using the Homebrew package manager. This is a straightforward installation method.

```bash
brew install lightgbm

```

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

### Install NVIDIA Drivers and OpenCL

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

Installs the recommended NVIDIA drivers and OpenCL development packages on Ubuntu. Restart the server after installation.

```bash
sudo apt-get update
sudo apt-get install --no-install-recommends nvidia-375
sudo apt-get install --no-install-recommends nvidia-opencl-icd-375 nvidia-opencl-dev opencl-headers

```

```bash
sudo init 6

```

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

### Run Distributed Learning (MPI Version - Linux)

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

Launches a LightGBM distributed learning job on Linux using MPI. Requires mpiexec, a machine list file, and a configuration file. Ensure MPI is run in the same path on all machines.

```bash
mpiexec --machinefile mlist.txt ./lightgbm config=your_config_file

```

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

### Run Distributed Learning (Socket Version - Windows)

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

Executes a LightGBM distributed learning job on Windows using socket communication. Requires a configuration file and mlist.txt.

```bash
lightgbm.exe config=your_config_file
```

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

### Build MPI Version on Windows via Command Line

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

Use this command-line approach on Windows to build the MPI version of LightGBM. Ensure MS MPI, Git, CMake, and VS Build Tools are installed.

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

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

### Install NVIDIA Drivers and OpenCL

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

Installs necessary NVIDIA drivers and OpenCL development packages on Ubuntu. Requires a server restart after installation.

```bash
sudo apt-get update
sudo apt-get install --no-install-recommends nvidia-375
sudo apt-get install --no-install-recommends nvidia-opencl-icd-375 nvidia-opencl-dev opencl-headers
```

```bash
sudo init 6
```

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

### LGBMRegressor Get Parameters

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

Get parameters for this estimator.

```APIDOC
## LGBMRegressor.get_params

### Description
Get parameters for this estimator.

### Parameters
- **deep** (bool, default=True) - If True, will return the parameters for this estimator and contained subobjects that are estimators.

### Returns
- **params** (dict) - Parameter names mapped to their values.
```

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

### LightGBM Model Initialization and Data Preparation

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

This snippet illustrates the initialization of a LightGBM predictor, handling different input types for the initial model (string path, Booster object). It also details the preparation of training and validation datasets, including updating parameters and setting up reference datasets for validation. Callbacks, including early stopping, are processed and sorted based on their execution order.

```python
predictor: Optional[_InnerPredictor] = None
if isinstance(init_model, (str, Path)):
    predictor = _InnerPredictor.from_model_file(model_file=init_model, pred_parameter=params)
elif isinstance(init_model, Booster):
    predictor = _InnerPredictor.from_booster(booster=init_model, pred_parameter=dict(init_model.params, **params))

if predictor is not None:
    init_iteration = predictor.current_iteration()
else:
    init_iteration = 0

train_set._update_params(params)._set_predictor(predictor)

is_valid_contain_train = False
train_data_name = "training"
reduced_valid_sets = []
name_valid_sets = []
if valid_sets is not None:
    if isinstance(valid_sets, Dataset):
        valid_sets = [valid_sets]
    if isinstance(valid_names, str):
        valid_names = [valid_names]
    for i, valid_data in enumerate(valid_sets):
        # reduce cost for prediction training data
        if valid_data is train_set:
            is_valid_contain_train = True
            if valid_names is not None:
                train_data_name = valid_names[i]
            continue
        reduced_valid_sets.append(valid_data._update_params(params).set_reference(train_set))
        if valid_names is not None and len(valid_names) > i:
            name_valid_sets.append(valid_names[i])
        else:
            name_valid_sets.append(f"valid_{i}")
# process callbacks
if callbacks is None:
    callbacks_set = set()
else:
    for i, cb in enumerate(callbacks):
        cb.__dict__.setdefault("order", i - len(callbacks))
    callbacks_set = set(callbacks)

if callback._should_enable_early_stopping(params.get("early_stopping_round", 0)):
    callbacks_set.add(
        callback.early_stopping(
            stopping_rounds=params["early_stopping_round"],  # type: ignore[arg-type]
            first_metric_only=first_metric_only,
            min_delta=params.get("early_stopping_min_delta", 0.0),
            verbose=_choose_param_value(
                main_param_name="verbosity",
                params=params,
                default_value=1,
            ).pop("verbosity")
            > 0,
        )
    )

callbacks_before_iter_set = {cb for cb in callbacks_set if getattr(cb, "before_iteration", False)}
callbacks_after_iter_set = callbacks_set - callbacks_before_iter_set
callbacks_before_iter = sorted(callbacks_before_iter_set, key=attrgetter("order"))
callbacks_after_iter = sorted(callbacks_after_iter_set, key=attrgetter("order"))

# construct booster
try:
    booster = Booster(params=params, train_set=train_set)
    if is_valid_contain_train:
        booster.set_train_data_name(train_data_name)
    for valid_set, name_valid_set in zip(reduced_valid_sets, name_valid_sets):
        booster.add_valid(valid_set, name_valid_set)
finally:
    train_set._reverse_update_params()
    for valid_set in reduced_valid_sets:
        valid_set._reverse_update_params()
booster.best_iteration = 0

# start training
for i in range(init_iteration, init_iteration + num_boost_round):
    for cb in callbacks_before_iter:
        cb(
            callback.CallbackEnv(
                model=booster,
                params=params,
                iteration=i,
                begin_iteration=init_iteration,
                end_iteration=init_iteration + num_boost_round,
                evaluation_result_list=None,
            )
        )

    booster.update(fobj=fobj)
```

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

### LightGBM CLI Configuration (Socket Version)

Source: https://lightgbm.readthedocs.io/en/stable/_sources/Parallel-Learning-Guide.rst.txt

Example configuration file content for running LightGBM in distributed mode using the socket version. Specifies parallel algorithm, number of machines, machine list file, and local listen port.

```text
tree_learner=your_parallel_algorithm
num_machines=your_num_machines
machine_list_file=mlist.txt
local_listen_port=12345
```

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

### Examples

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

Example of how to use lgb.plot.importance with a trained LightGBM model.

```R
# \donttest{ 
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)

params <- list(
    objective = "binary"
    , learning_rate = 0.1
    , 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.000747 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] [binary:BoostFromScore]: pavg=0.482113 -> initscore=-0.071580
#> [LightGBM] [Info] Start training from score -0.071580
#> [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_imp <- lgb.importance(model, percentage = TRUE)
lgb.plot.importance(tree_imp, top_n = 5L, measure = "Gain")

# }

```

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

### Install older Matrix package for R

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

If you are using an R version older than 4.4.0 and encounter issues with the Matrix package dependency during LightGBM installation, manually install an older version of Matrix.

```r
install.packages('https://cran.r-project.org/src/contrib/Archive/Matrix/Matrix_1.6-5.tar.gz', repos = NULL)

```

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

### LightGBM CLI Configuration (MPI Version)

Source: https://lightgbm.readthedocs.io/en/stable/_sources/Parallel-Learning-Guide.rst.txt

Example configuration file content for running LightGBM in distributed mode using MPI. Specifies parallel algorithm and number of machines.

```text
tree_learner=your_parallel_algorithm
num_machines=your_num_machines
```

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

### Example of setting a field

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

Example of setting the 'label' field of an lgb.Dataset object.

```R
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
lgb.Dataset.construct(dtrain)

labels <- lightgbm::get_field(dtrain, "label")
lightgbm::set_field(dtrain, "label", 1 - labels)

labels2 <- lightgbm::get_field(dtrain, "label")
stopifnot(all.equal(labels2, 1 - labels))
# }
```

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

### Configure LightGBM for GPU Training

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

Creates a configuration file for LightGBM, enabling GPU training by setting 'device=gpu'. It also configures training parameters and dynamically sets the number of threads based on available processors.

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

```

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

### Example of lgb.plot.interpretation

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

An example demonstrating the usage of lgb.plot.interpretation with a trained LightGBM model.

```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.000739 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.interprete(
  model = model
  , data = agaricus.test$data
  , idxset = 1L:5L
)
lgb.plot.interpretation(
  tree_interpretation_dt = tree_interpretation[[1L]]
  , top_n = 3L
)

# }

```

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

### Run Distributed Learning (Socket Version - Linux)

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

Executes a LightGBM distributed learning job on Linux using socket communication. Requires a configuration file and mlist.txt.

```bash
./lightgbm config=your_config_file
```

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

### Example Usage

Source: https://lightgbm.readthedocs.io/en/stable/R/reference/lgb.model.dt.tree.html

Example of how to use lgb.model.dt.tree to parse a LightGBM model into a data.table.

```R
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)

params <- list(
  objective = "binary"
  , learning_rate = 0.01
  , num_leaves = 63L
  , max_depth = -1L
  , min_data_in_leaf = 1L
  , min_sum_hessian_in_leaf = 1.0
  , num_threads = 2L
)
model <- lgb.train(params, dtrain, 10L)
#> [LightGBM] [Info] Number of positive: 3140, number of negative: 3373
#> [LightGBM] [Info] Auto-choosing row-wise multi-threading, the overhead of testing was 0.000726 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] [binary:BoostFromScore]: pavg=0.482113 -> initscore=-0.071580
#> [LightGBM] [Info] Start training from score -0.071580
#> [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
#> [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_dt <- lgb.model.dt.tree(model)
# }
```

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

### Initialize and Construct Dataset

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

This snippet illustrates the internal logic for initializing a LightGBM Dataset, handling cases where a reference dataset is provided for alignment or creating a new training dataset from scratch. It manages parameters, data, labels, weights, and other associated information.

```python
if self._handle is None:
            if self.reference is not None:
                reference_params = self.reference.get_params()
                params = self.get_params()
                if params != reference_params:
                    if not self._compare_params_for_warning(
                        params=params,
                        other_params=reference_params,
                        ignore_keys=_ConfigAliases.get("categorical_feature"),
                    ):
                        _log_warning("Overriding the parameters from Reference Dataset.")
                    self._update_params(reference_params)
                if self.used_indices is None:
                    # create valid
                    self._lazy_init(
                        data=self.data,
                        label=self.label,
                        reference=self.reference,
                        weight=self.weight,
                        group=self.group,
                        position=self.position,
                        init_score=self.init_score,
                        predictor=self._predictor,
                        feature_name=self.feature_name,
                        categorical_feature="auto",
                        params=self.params,
                    )
                else:
                    # construct subset
                    used_indices = _list_to_1d_numpy(self.used_indices, dtype=np.int32, name="used_indices")
                    assert used_indices.flags.c_contiguous
                    if self.reference.group is not None:
                        group_info = np.array(self.reference.group).astype(np.int32, copy=False)
                        _, self.group = np.unique(
                            np.repeat(range(len(group_info)), repeats=group_info)[self.used_indices], return_counts=True
                        )
                    self._handle = ctypes.c_void_p()
                    params_str = _param_dict_to_str(self.params)
                    _safe_call(
                        _LIB.LGBM_DatasetGetSubset(
                            self.reference.construct()._handle,
                            used_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
                            ctypes.c_int32(used_indices.shape[0]),
                            _c_str(params_str),
                            ctypes.byref(self._handle),
                        )
                    )
                    if not self.free_raw_data:
                        self.get_data()
                    if self.group is not None:
                        self.set_group(self.group)
                    if self.position is not None:
                        self.set_position(self.position)
                    if self.get_label() is None:
                        raise ValueError("Label should not be None.")
                    if (
                        isinstance(self._predictor, _InnerPredictor)
                        and self._predictor is not self.reference._predictor
                    ):
                        self.get_data()
                        self._set_init_score_by_predictor(
                            predictor=self._predictor, data=self.data, used_indices=used_indices
                        )
            else:
                # create train
                self._lazy_init(
                    data=self.data,
                    label=self.label,
                    reference=None,
                    weight=self.weight,
                    group=self.group,
                    init_score=self.init_score,
                    predictor=self._predictor,
                    feature_name=self.feature_name,
                    categorical_feature=self.categorical_feature,
                    params=self.params,
                    position=self.position,
                )
            if self.free_raw_data:
                self.data = None
            self.feature_name = self.get_feature_name()
        return self
```

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

### Example usage of lgb.Dataset.create.valid

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

Example of creating a validation dataset using lgb.Dataset.create.valid

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

# parameters can be changed between the training data and validation set,
# for example to account for training data in a text file with a header row
# and validation data in a text file without it
train_file <- tempfile(pattern = "train_", fileext = ".csv")
write.table(
  data.frame(y = rnorm(100L), x1 = rnorm(100L), x2 = rnorm(100L)) \
  , file = train_file
  , sep = ","
  , col.names = TRUE
  , row.names = FALSE
  , quote = FALSE
)

valid_file <- tempfile(pattern = "valid_", fileext = ".csv")
write.table(
  data.frame(y = rnorm(100L), x1 = rnorm(100L), x2 = rnorm(100L)) \
  , file = valid_file
  , sep = ","
  , col.names = FALSE
  , row.names = FALSE
  , quote = FALSE
)

dtrain <- lgb.Dataset(
  data = train_file
  , params = list(has_header = TRUE)
)
dtrain$construct()
#> [LightGBM] [Info] Construct bin mappers from text data time 0.00 seconds

dvalid <- lgb.Dataset(
  data = valid_file
  , params = list(has_header = FALSE)
)
dvalid$construct()
#> [LightGBM] [Info] Construct bin mappers from text data time 0.00 seconds
# }
```

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

### Initialize Dataset from PyArrow Table

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

Creates a LightGBM Dataset from a PyArrow table. Requires 'pyarrow' and 'cffi' to be installed. Only supports integer, floating point, and boolean datatypes.

```python
        if not (PYARROW_INSTALLED and CFFI_INSTALLED):
            raise LightGBMError("Cannot init Dataset from Arrow without 'pyarrow' and 'cffi' installed.")

        # Check that the input is valid: we only handle numbers (for now)
        if not all(arrow_is_integer(t) or arrow_is_floating(t) or arrow_is_boolean(t) for t in table.schema.types):
            raise ValueError("Arrow table may only have integer or floating point datatypes")

        # Export Arrow table to C
        c_array = _export_arrow_to_c(table)
        self._handle = ctypes.c_void_p()
        _safe_call(
            _LIB.LGBM_DatasetCreateFromArrow(
                ctypes.c_int64(c_array.n_chunks),
                ctypes.c_void_p(c_array.chunks_ptr),
                ctypes.c_void_p(c_array.schema_ptr),
                _c_str(params_str),
                ref_dataset,
                ctypes.byref(self._handle),
            )
        )
        return self
```

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

### Standard Installation from CRAN Package

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

Command to install the R package after building it.

```sh
R CMD install lightgbm_*.tar.gz
```

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

### Initialize Dataset from Various Data Formats

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

This method handles the initialization of a LightGBM Dataset object from diverse input data types such as file paths, sparse matrices (CSR, CSC), NumPy arrays, PyArrow tables, lists of arrays, and sequences. It also manages optional parameters like labels, weights, groups, and initial scores.

```python
        params_str = _param_dict_to_str(params)
        self.params = params
        # process for reference dataset
        ref_dataset = None
        if isinstance(reference, Dataset):
            ref_dataset = reference.construct()._handle
        elif reference is not None:
            raise TypeError("Reference dataset should be None or dataset instance")
        # start construct data
        if isinstance(data, (str, Path)):
            self._handle = ctypes.c_void_p()
            _safe_call(
                _LIB.LGBM_DatasetCreateFromFile(
                    _c_str(str(data)),
                    _c_str(params_str),
                    ref_dataset,
                    ctypes.byref(self._handle),
                )
            )
        elif isinstance(data, scipy.sparse.csr_matrix):
            self.__init_from_csr(data, params_str, ref_dataset)
        elif isinstance(data, scipy.sparse.csc_matrix):
            self.__init_from_csc(data, params_str, ref_dataset)
        elif isinstance(data, np.ndarray):
            self.__init_from_np2d(data, params_str, ref_dataset)
        elif _is_pyarrow_table(data):
            self.__init_from_pyarrow_table(data, params_str, ref_dataset)
        elif isinstance(data, list) and len(data) > 0:
            if _is_list_of_numpy_arrays(data):
                self.__init_from_list_np2d(data, params_str, ref_dataset)
            elif _is_list_of_sequences(data):
                self.__init_from_seqs(data, ref_dataset)
            else:
                raise TypeError("Data list can only be of ndarray or Sequence")
        elif isinstance(data, Sequence):
            self.__init_from_seqs([data], ref_dataset)
        elif isinstance(data, dt_DataTable):
            _emit_datatable_deprecation_warning()
            self.__init_from_np2d(data.to_numpy(), params_str, ref_dataset)
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                self.__init_from_csr(csr, params_str, ref_dataset)
            except BaseException as err:
                raise TypeError(f"Cannot initialize Dataset from {type(data).__name__}") from err
        if label is not None:
            self.set_label(label)
        if self.get_label() is None:
            raise ValueError("Label should not be None")
        if weight is not None:
            self.set_weight(weight)
        if group is not None:
            self.set_group(group)
        if position is not None:
            self.set_position(position)
        if isinstance(predictor, _InnerPredictor):
            if self._predictor is None and init_score is not None:
                _log_warning("The init_score will be overridden by the prediction of init_model.")
            self._set_init_score_by_predictor(predictor=predictor, data=data, used_indices=None)
        elif init_score is not None:
            self.set_init_score(init_score)
        elif predictor is not None:
            raise TypeError(f"Wrong predictor type {type(predictor).__name__}")
        # set feature names
        return self.set_feature_name(feature_name)
```

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

### Example of using lgb.interprete

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

Example demonstrating the usage of lgb.interprete with a binary classification model.

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

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 = 3L
)
#> [LightGBM] [Info] Number of positive: 3140, number of negative: 3373
#> [LightGBM] [Info] Auto-choosing row-wise multi-threading, the overhead of testing was 0.000789 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

tree_interpretation <- lgb.interprete(model, test$data, 1L:5L)
# }
```

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

### Example of using lgb.importance

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

Example demonstrating how to compute feature importance using lgb.importance.

```R
# \donttest{
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)

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.000769 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] [binary:BoostFromScore]: pavg=0.482113 -> initscore=-0.071580
#> [LightGBM] [Info] Start training from score -0.071580
#> [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_imp1 <- lgb.importance(model, percentage = TRUE)
tree_imp2 <- lgb.importance(model, percentage = FALSE)
# }
```

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

### Python Parameter Example with Aliases

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

Demonstrates how to use primary parameter names and aliases in Python. The primary name is always preferred.

```python
lgb.train(
   params={
      "learning_rate": 0.07,
      "shrinkage_rate": 0.12
   },
   train_set=dtrain
)
```

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

### lgb.cv Example

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

An example of using lgb.cv for cross-validation with regression objective and L2 metric.

```R
data(agaricus.train, package = "lightgbm")
train <- agaricus.train
dtrain <- lgb.Dataset(train$data, label = train$label)
params <- list(
  objective = "regression"
  , metric = "l2"
  , min_data = 1L
  , learning_rate = 1.0
  , num_threads = 2L
)
model <- lgb.cv(
  params = params
  , data = dtrain
  , nrounds = 5L
  , nfold = 3L
)
```

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

### Python Parameter Example with Alias Preference

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

Illustrates LightGBM's preference for specific aliases when the primary parameter name is not provided. 'shrinkage_rate' is preferred over other aliases.

```python
lgb.train(
   params={
      "eta": 0.19,
      "shrinkage_rate": 0.12
   },
   train_set=dtrain
)
```