- Version: 20261019
- Source Code Copyright: Unknown
- Redistribution Restriction: This source code is integrated by LEADERG INC. Please use it privately. Please DO NOT distribute it to internet.
Console/terminal pipeline for training and running a LightGBM classifier on tabular CSV data, with SHAP explainability plots, supporting Windows 11, Ubuntu Linux 24.04 and macOS 14+ (Apple Silicon or Intel). The example dataset titanic (4 features: Pclass/Age/Fare/Sex, predicting Survived) ships with a trained model. The booster is trained with the native lgb.train API; its scores are thresholded (default 0.5) into 0/1 class decisions, and accuracy is reported for both training and inference.
GPU: on Windows and Linux, training runs on a GPU through LightGBM's OpenCL GPU tree learner when one is usable (an NVIDIA GPU is preferred; AMD and Intel GPUs also work), with automatic CPU fallback. Prediction and the SHAP values always run on the CPU (LightGBM's GPU support covers training only). On macOS everything runs on the CPU (LightGBM has no Apple GPU / Metal backend).
CSV convention: the first column is a row ID (dropped), the last column is the class label; every other column is a numeric feature (thousands separators like "1,234" are stripped automatically). Any empty/non-numeric cell aborts with its position printed.
[Folder Structure]
- CLAUDE.md / AGENTS.md: Program specification (identical content).
- CHANGELOG.md: Change log.
- copyright.txt: Copyright notice.
- Data-LightGBM-Classification-Python.html: This document (usage page).
- NIPS-2017-lightgbm-...-Paper.pdf: LightGBM reference paper.
- data/titanic/: train_input.csv, inference_input.csv (inputs); train_output.csv, inference_output.csv (written by the scripts: input rows + prediction column, 0/1).
- model/titanic/: model.sav (trained booster), scaler.pkl (fitted MinMaxScaler), plots/ (feature importance, SHAP; inference_ prefix for inference runs).
- tool/tools.py: Shared helpers: project_root, delete_ipynb_checkpoints.
- src/: Source code and launcher scripts.
- src/01_python_install_windows.bat / 01_python_install_linux.sh / 01_python_install_mac.sh: Install Python 3.14 (winget / apt / Homebrew).
- src/02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh: Create venv/ and install src/requirements.txt (the macOS script also installs libomp).
- venv/: Python virtual environment, created by 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh; removed by 99_venv_clean.
[Prerequisites]
- Python 3.14, installed by 01_python_install_windows.bat (winget), 01_python_install_linux.sh (apt; adds the deadsnakes PPA when needed; needs sudo) or 01_python_install_mac.sh (Homebrew).
- The 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh scripts install pandas, numpy, matplotlib, scikit-learn, lightgbm (pinned to 4.6.0), shap. No PyTorch is used.
- GPU (Windows / Linux): the lightgbm 4.6.0 PyPI wheel includes LightGBM's OpenCL GPU tree learner; no CUDA toolkit is needed. It needs a GPU with an OpenCL runtime, which the NVIDIA, AMD and Intel graphics drivers install (on Linux, clinfo lists the OpenCL devices). Without a usable GPU training falls back to the CPU automatically. lightgbm is pinned to 4.6.0 because the 4.7.0 Windows wheel was published without the GPU tree learner.
- macOS: CPU only (LightGBM has no Apple GPU / Metal backend). 02_venv_create_mac.sh installs the OpenMP runtime LightGBM needs (brew install libomp).
- Prediction, the SHAP values, pandas, scikit-learn and matplotlib run on the CPU on every OS (no GPU backend).
- Windows 11 uses the .bat launchers; Ubuntu 24.04 and macOS use the .sh launchers.
[Launcher Scripts]
Every step exists as a Windows batch file (.bat) and a shell script (.sh, shared by Linux and macOS) with identical behavior. All launchers switch to the project root first, so they can be run from any directory.
1. 01_python_install_windows.bat / 01_python_install_linux.sh / 01_python_install_mac.sh
Install Python 3.14 (winget / apt + deadsnakes PPA / Homebrew). Does nothing if it is already installed.
2. 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh
Delete the old venv/, create a fresh one with Python 3.14, install src/requirements.txt (aborts loudly if pip fails) and print the LightGBM version. The macOS script also installs libomp.
3. 03_venv_activate.bat / 03_venv_activate.sh
Activate the venv. On Linux/macOS, source it: source src/03_venv_activate.sh. If the project folder was renamed after the venv was created, re-create the venv with 02_venv_create_windows/linux/mac first; the other launchers do not need activation.
4. 04_train.bat / 04_train.sh
Train the classifier. Extra args are forwarded to train.py.
5. 05_inference.bat / 05_inference.sh
Run inference with the trained model. Extra args are forwarded to inference.py.
6. 99_venv_clean.bat / 99_venv_clean.sh
Delete the venv/ folder.
7. 99_venv_deactivate.bat / 99_venv_deactivate.sh
Deactivate the venv in the current shell. On Linux/macOS, source it: source src/99_venv_deactivate.sh (bash or zsh).
[Python Entry Points]
src/train.py
--dataset titanic --iterations 2000 --num-leaves 20 --max-depth -1 --threshold 0.5 --shap-index 1 --device auto. Fits a MinMaxScaler, trains via lgb.train on the selected device, thresholds the scores into 0/1, prints the accuracy, writes model.sav, scaler.pkl, train_output.csv, and the plot set: feature importance (gain), SHAP waterfall/force (for --shap-index), summary, bar, plus dependence/scatter on the two most important features (picked dynamically by gain).
src/inference.py
--dataset titanic --threshold 0.5 --shap-index 1. Applies the saved scaler + booster to inference_input.csv, prints the accuracy against the label column, writes inference_output.csv and the SHAP plot set with an inference_ prefix. Runs on the CPU on every OS (LightGBM has no GPU prediction; a GPU-trained model loads and predicts without a GPU).
--device (train.py): auto (default) checks the GPU with a one-tree test fit and trains with device_type="gpu" when it works, else on the CPU; gpu (or its alias cuda: OpenCL drives the same NVIDIA GPU) forces the GPU and stops with LightGBM's error when it is not usable; cpu forces the CPU; mps maps to cpu. The selected device is printed at startup, e.g. Device: gpu (OpenCL: Quadro RTX 5000, NVIDIA Corporation). Only GPU devices are used and an NVIDIA GPU is preferred; set BOOST_COMPUTE_DEFAULT_DEVICE to part of a GPU's name to pick another one. GPU training uses single-precision histograms, so results can differ slightly from a CPU run (titanic accuracy is the same, 97.08%). The GPU pays off on large datasets; for small data such as titanic the CPU is faster (2000 iterations: about 19 s on a Quadro RTX 5000 vs. about 1.3 s on the CPU), so use --device cpu there.
Both scripts run headless (matplotlib Agg backend): every figure is saved under model/{dataset}/plots/. SHAP values are in the booster's raw-score space.
[Quick Start]
Windows 11
src\01_python_install_windows.bat
src\02_venv_create_windows.bat
src\04_train.bat --dataset titanic
src\05_inference.bat --dataset titanic
Open a new terminal after 01_python_install_windows.bat before running 02_venv_create_windows.bat.
Ubuntu 24.04
bash src/01_python_install_linux.sh
bash src/02_venv_create_linux.sh
bash src/04_train.sh --dataset titanic
bash src/05_inference.sh --dataset titanic
macOS 14+
bash src/01_python_install_mac.sh
bash src/02_venv_create_mac.sh
bash src/04_train.sh --dataset titanic
bash src/05_inference.sh --dataset titanic
Training the titanic booster takes about 1 s on the CPU (--device cpu) and about 20 s on the GPU; the SHAP plots add a few seconds.
[Using Your Own Dataset]
- Create data/{name}/train_input.csv and data/{name}/inference_input.csv following the CSV convention (ID first, label last, numeric features — encode categorical features as numbers, like Sex 0/1 in the example).
- 04_train --dataset {name} — the model/scaler/plots land in model/{name}/.
- 05_inference --dataset {name}.
The SHAP dependence/scatter feature names are chosen dynamically from the booster's gain importance, so no code change is needed. Parameter tuning: LightGBM Parameters-Tuning.
[Troubleshooting]
- libomp error on macOS: brew install libomp (02_venv_create_mac.sh does this when Homebrew is installed).
- Device: cpu (no usable OpenCL GPU: ...) although the PC has a GPU: the message shows LightGBM's reason. No OpenCL device found: install or update the graphics driver (it includes the OpenCL runtime; on Ubuntu check clinfo) and make sure CUDA_VISIBLE_DEVICES is not -1 (it hides NVIDIA GPUs from OpenCL too). GPU Tree Learner was not enabled in this build: a CPU-only lightgbm (e.g. 4.7.0 on Windows) is installed; re-run 02_venv_create_windows.bat / 02_venv_create_linux.sh to get the pinned 4.6.0. Force --device gpu to stop with the error instead of falling back.
- 1 warning generated. lines on the first GPU run: printed by the NVIDIA OpenCL compiler while LightGBM builds its GPU kernels; harmless, and later runs are silent (the driver caches the kernels).
- InconsistentVersionWarning with the shipped model: model/titanic/scaler.pkl was pickled with an older scikit-learn release. Harmless (inference still reports 97.08% accuracy); run 04_train once to regenerate the files.
- SHAP errors: the scripts skip the explanation plots with a warning instead of aborting (the model and prediction CSV are already saved) and print the installed shap version. Fix with pip install -U shap inside the venv.
[References]
- LightGBM paper (NIPS 2017, shipped as PDF): papers.nips.cc
- LightGBM docs: https://lightgbm.readthedocs.io/en/latest/
- LightGBM GPU tutorial: https://lightgbm.readthedocs.io/en/latest/GPU-Tutorial.html
- LightGBM source: https://github.com/microsoft/LightGBM
- Gradient boosting overview: machinelearningmastery.com
- SHAP: https://github.com/shap/shap
After execution, you can see the result of LightGBM inference.
This SDK is built in AppForAI - AI Dev Tools.