Console / terminal pipeline for training and running a LightGBM regressor on tabular CSV data, with SHAP explainability plots, supporting Windows 11 and Ubuntu Linux 24.04. The example dataset housing (Boston housing: 13 features, predicting the median home value medv) ships with a trained model. The booster is trained with the native lgb.train API (objective regression, metrics l1 and l2), and RMSE and R² are reported for both training and inference.

 

CSV convention: the first column is a row ID (dropped), the last column is the regression target, and every other column is a numeric feature (thousands separators like "1,234" are stripped automatically). Any empty or non-numeric cell aborts the run with its position printed.

 

Data-LightGBM-Regression-inference-Jupyter.png

 

[Folder Structure]

  • CLAUDE.md / AGENT.md: program specification, the two files are kept identical.
  • CHANGELOG.md: change log.
  • copyright.txt: copyright notice.
  • NIPS-2017-lightgbm-...-Paper.pdf: the LightGBM reference paper.
  • data/housing/: the inputs train_input.csv and inference_input.csv, plus train_output.csv and inference_output.csv written by the scripts (the input rows plus a prediction column).
  • model/housing/: model.sav (the trained booster), scaler.pkl (the fitted MinMaxScaler) and plots/ (true-vs-predicted, feature importance and SHAP; inference runs use an inference_ prefix).
  • tool/tools.py: shared helpers, project_root and delete_ipynb_checkpoints.
  • src/: source code, the launcher scripts and this document.
  • venv/: Python virtual environment, created by step 01.

[Instructions]

Every step exists as a Windows batch file (.bat) and a Linux shell script (.sh) with identical behavior. All launchers switch to the project root first, so they can be run from any directory.

 

1. 01_venv_create.bat / 01_venv_create.sh

Delete the old venv/, create a fresh one, and install src/requirements.txt. Aborts loudly if pip fails.

 

2. 02_venv_activate.bat / 02_venv_activate.sh

Activate the venv. On Linux, source it: source src/02_venv_activate.sh.

 

3. 03_train.bat / 03_train.sh

Train the regressor. Extra arguments are forwarded to train.py.

 

4. 04_inference.bat / 04_inference.sh

Run inference with the trained model. Extra arguments are forwarded to inference.py.

 

5. 99_venv_clear.bat / 99_venv_clear.sh

Delete the venv/ folder.

 

[Python Entry Points]

src/train.py

  • --dataset housing: the dataset folder name
  • --iterations 2000: the number of iterations
  • --num-leaves 31: the number of leaves
  • --learning-rate 0.05: the learning rate
  • --shap-index 1: the row index explained by the SHAP waterfall / force plots

The remaining notebook parameters are fixed: gbdt, objective regression, metrics l1 and l2, feature_fraction 0.9, bagging_fraction 0.8 and bagging_freq 5. It fits a MinMaxScaler, trains via lgb.train, prints RMSE and R², and writes model.sav, scaler.pkl, train_output.csv and the plot set: the true-vs-predicted line and scatter plots, feature importance (by gain), the SHAP waterfall and force plots (for the row given by --shap-index), summary, bar, plus dependence and scatter on the two most important features (picked dynamically by gain; rm and lstat for housing).

 

src/inference.py

  • --dataset housing: the dataset folder name
  • --shap-index 1: the row index explained by the SHAP waterfall / force plots

It applies the saved scaler and booster to inference_input.csv, prints RMSE and R² against the target column, and writes inference_output.csv plus the same plot set with an inference_ prefix.

 

Both scripts run headless (the matplotlib Agg backend), so every figure is saved under model/{dataset}/plots/.

[Quick Start]

Windows 11

src\01_venv_create.bat

src\03_train.bat --dataset housing

src\04_inference.bat --dataset housing

 

Ubuntu 24.04

bash src/01_venv_create.sh

bash src/03_train.sh --dataset housing

bash src/04_inference.sh --dataset housing

 

Training the housing example takes a few seconds on CPU. No GPU or CUDA is needed. macOS only: run brew install libomp first.

[Using Your Own Dataset]

  1. Create data/{name}/train_input.csv and data/{name}/inference_input.csv following the CSV convention (ID first, target last, numeric features).
  2. Run 03_train --dataset {name}; the model, scaler and plots land in model/{name}/.
  3. Run 04_inference --dataset {name}.

The SHAP dependence and scatter feature names are chosen dynamically from the booster's gain importance, so no code change is needed. For parameter tuning, see LightGBM Parameters-Tuning.

[Troubleshooting]

  • libomp error on macOS: run brew install libomp.
  • 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]

 

After execution, you can see the results of the LightGBM regression.

 

This SDK is built in AppForAI - AI Dev Tools.

 

Purchase license separately: USD 600, permanent authorization, single APP authorization, single machine authorization, one-year activation, one-year download, one-year update, one-year email technical support.