Geographical-XGBoost documentation
An implementation of XGBoost for Geographical Analysis.
Geoxgboost is a Python library that implements the Geographical-XGBoost (G-XGBoost) algorithm for spatially local regression. G-XGBoost belongs to the family of Spatial Machine Learning algorithms and modifies the standard XGBoost algorithm (extreme gradient boosting trees) to handle spatial data and spatial heterogeneity.
G-XGBoost:
Applies the concept of geographically varying models in XGBoost: This means it creates local models that analyze data within a specified neighborhood using spatial weights.
Creates an ensemble of the global and local models: It utilizes both global and local models for training, validation, and prediction, leading to improved model accuracy.
Calculates local feature importance using spatial weights through the gain function.
Beyond being a predictive tool, G-XGBoost is also a valuable exploratory tool for identifying spatial heterogeneity. It evaluates how spatially weighted feature importance varies across different locations, enhancing the model’s interpretability. The theoretical presentation, mathematical formulation, and experimental results of G-XGBoost, across six regression models and six benchmark datasets, can be found in Grekousis 2025 paper.
Figure: G-XGBoost ensemble for spatially local regression. A different sub-model is built for every spatial unit (i), including only its neighboring units. The optimal bandwidth value (either distance or number of nearest neighbors) is defined by minimizing the cross validation criterion. Hyperparameters are selected using grid search through nested cross validation of the global model. G-XGBoost results from the ensemble (y_ens) of global (y_gl) and local (y_loc) models using the alpha weight (α) regularization hyperparameter. Feature importance is produced for the local models.
Installation
pip install geoxgboost
Tutorial
A comprehensive tutorial is available on GitHub, guiding users through the entire process, from project setup in PyCharm to running the demo. No prior Python knowledge is required.
The tutorial provides step-by-step instructions on how to:
Download and install PyCharm to create the Demo project.
Download the necessary data and install the geoxgboost library.
Run the geoxgboost algorithm.
Extract outputs in Excel format.
Understand the content of each output file.
Like any machine learning algorithm, G-XGBoost requires hyperparameter tuning. Guidelines for tuning are provided in the accompanying paper.
The demo utilizes predefined hyperparameter values for convenience. However, users are encouraged to experiment with different hyperparameter combinations to optimize model performance.
Geoxgboost facilitates hyperparameter tuning through a built-in function called create_param_grid, enabling efficient grid search.
The functions, parameters, and examples of the geoxgboost package are available in https://geoxgboost.readthedocs.io/en/latest/
Demo data
Boston housing dataset
Download data from: https://github.com/geogreko/DemoGXGBoost/tree/main
The following files are included in the GitHub repository:
Coords.csv: Coordinates of the spatial units.
Data.csv: Dependent and independent variables.
DataDescription.xlsx: Data description.
GXGB_call_demo.py: Python script to analyze the Boston housing dataset.
PredictCoords.csv: Coordinates of the spatial units for prediction.
PredictData.csv: Values of the independent variables for the spatial units where predictions will be made.
Tutorial_geoxgboost.pdf: A guide for using the demo.
How to cite
Grekousis G, (2025). Geographical-XGBoost: A new ensemble model for spatially local regression based on gradient-boosted trees. Journal of Geographical Systems. https://doi.org/10.1007/s10109-025-00465-4
Geoxgboost is freely available provided the above paper is cited.