Console/terminal pipeline for time-series regression with XGBoost and SHAP explainability, supporting Windows 11 and Ubuntu Linux 24.04. A sliding lag window (12 steps by default) turns each series into tabular rows for an XGBRegressor, with RMSE and R² reported. Two example datasets ship with trained models: sales-forecast-airline and stock. CPU only — no GPU needed.

 

Jupyter-Data-XGBoost-Regression-Time-Series-inference.png

 

[Prerequisites]

  • Python 3.10 or newer on PATH.
  • 01_venv_create installs pandas, numpy, matplotlib, scikit-learn, xgboost and shap.
  • macOS only: brew install libomp (Windows and Ubuntu need nothing extra).
  • Windows 11 uses the .bat launchers; Ubuntu 24.04 uses the .sh launchers.

[Instructions]

1. 01_venv_create.bat / 01_venv_create.sh

Recreate the venv 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). Optional — steps 03 to 06 activate it automatically.

 

3. 03_prepare_train_data.bat / 03_prepare_train_data.sh

Build the lagged training CSV. Arguments: --dataset, --time-seq.

 

4. 04_train.bat / 04_train.sh

Train: fits the scaler and the XGBRegressor, prints RMSE and R², and writes the model, scaler, predictions and plots. Arguments: --dataset, --estimators, --shap-index.

 

5. 05_prepare_inference_data.bat / 05_prepare_inference_data.sh

Build the lagged inference CSV. Arguments: --dataset, --time-seq.

 

6. 06_inference.bat / 06_inference.sh

Inference: applies the saved scaler and model, prints RMSE and R², and writes the predictions and plots. Arguments: --dataset, --shap-index.

 

7. 99_venv_clear.bat / 99_venv_clear.sh

Delete the venv/ folder.

 

[Quick Start]

Windows 11

src\01_venv_create.bat

src\03_prepare_train_data.bat --dataset sales-forecast-airline

src\04_train.bat --dataset sales-forecast-airline

src\05_prepare_inference_data.bat --dataset sales-forecast-airline

src\06_inference.bat --dataset sales-forecast-airline

 

Ubuntu Linux 24.04

bash src/01_venv_create.sh

bash src/03_prepare_train_data.sh --dataset sales-forecast-airline

bash src/04_train.sh --dataset sales-forecast-airline

bash src/05_prepare_inference_data.sh --dataset sales-forecast-airline

bash src/06_inference.sh --dataset sales-forecast-airline

 

For the stock example, pass --dataset stock to every step.

 

[CSV Convention]

For the raw *_data.csv files: the first column is a date or row ID (dropped), the last column is the regression target, and every other column is a numeric feature; thousands separators such as 1,234 are stripped automatically. Any empty or non-numeric cell aborts the run with its position printed. Steps 03 and 05 stack --time-seq consecutive rows side by side (the lags are named {name}.1 through {name}.11) and align the target to the window's last step.

 

[Files and Folders]

  • CLAUDE.md / AGENT.md: the program specification. The two files are kept identical.
  • CHANGELOG.md: change log.
  • copyright.txt: copyright notice.
  • data/{dataset}/: the raw series (train_data.csv, inference_data.csv), the lagged CSVs (*_time_series.csv, written by steps 03 and 05) and the prediction CSVs (*_prediction.csv, written by steps 04 and 06).
  • model/{dataset}/: model.sav (XGBRegressor), scaler.pkl (MinMaxScaler) and plots/ (PNG files; inference runs use an inference_ prefix).
  • src/prepare_data.py, src/train.py, src/inference.py: the console entry points; src/requirements.txt lists the dependencies.
  • src/Data-XGBoost-Regression-Time-Series-Python-1.html: this usage page.
  • venv/: the virtual environment created by 01_venv_create and removed by 99_venv_clear.

[Outputs]

  • data/{dataset}/*_prediction.csv: the lagged input rows plus a prediction column; RMSE and R² are printed to the terminal.
  • model/{dataset}/plots/: true_vs_predicted_line.png, true_vs_predicted_scatter.png, feature_importance.png, and the SHAP waterfall, force, summary, bar, dependence and scatter plots. The feature names in the dependence and scatter plots are picked dynamically (the first base feature plus its deepest lag), so any dataset works. Inference runs use an inference_ prefix.

[Using Your Own Dataset]

Create data/{name}/train_data.csv and inference_data.csv following the CSV convention, then run steps 03 → 04 → 05 → 06 with --dataset {name}. The artifacts land in model/{name}/. Use the same --time-seq for steps 03 and 05 as the model was trained with.

 

[Troubleshooting]

SHAP TypeError: The passed model is not callable...

The installed shap release cannot auto-detect the installed XGBoost version. The scripts fall back to shap.TreeExplainer automatically and, failing that, skip the explanation plots with a warning (the model and the prediction CSV are already saved). Permanent fix: run pip install -U shap xgboost inside the venv.

 

[References]

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.