Metadata-Version: 2.1
Name: sgwr
Version: 0.5
Summary: Serial SGWR, MPI-enhanced FastSGWR, and multiscale MSGWR
Home-page: https://github.com/Lessani252/FastSGWR
Author: M. Naser Lessani (GIBD)
Author-email: naserlessani252@gmail.com
License: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: click
Requires-Dist: mpi4py
Requires-Dist: scipy
Requires-Dist: spglm
Requires-Dist: spreg
Requires-Dist: matplotlib

# SGWR 0.5

The package contains serial SGWR, MPI-enabled FastSGWR, and multiscale SGWR (MSGWR).

## MSGWR usage

```python
from sgwr import MSGWR, Sel_BW

# coords: (n, 2) projected coordinates; y: (n, 1) Gaussian response
# X: (n, p) numeric predictors; data: (n, p) similarity attributes
# Keep data columns aligned with the corresponding predictors in X.
# Supply X and data without an intercept; constant=True adds it.
selector = Sel_BW(coords, y, X, data, multi=True)
selector.search(multi_bw_min=[20])  # choose bounds suitable for your sample
results = MSGWR(coords, y, X, data, selector).fit(n_chunks=1)
print(results.summary())
# results.summary(as_str=False) prints directly and returns None.
# results.summary(as_str=True) returns text (the default).
```

Use identical coordinates, response, predictors, similarity data, and model
settings for selection and fitting. For fixed Gaussian weights, pass
`fixed=True` to both classes. Defaults select adaptive bisquare weights.
Explicit mismatched kernel options and spherical distances raise an error.
MSGWR currently supports Gaussian responses and projected coordinates only.
The existing serial SGWR and FastSGWR APIs remain available.

The MSGWR summary includes per-variable bandwidths, spatial mixing alphas,
effective parameter counts, adjusted 95% significance levels and critical
t values, global OLS results, model diagnostics, and coefficient statistics.
`alpha=1` means purely geographic weighting; this mixing parameter is distinct
from the adjusted significance alpha. The intercept uses spatial weights only.

Standard errors and diagnostics replay the complete selection history,
including initialization. They condition on the selected bandwidths and
alphas; they do not account for uncertainty from selecting these quantities.
`sigma2_v1=True` divides RSS by `n - trace(S)`; `False` uses
`n - 2*trace(S) + trace(S.T @ S)`. Both work without retaining the full hat
matrix. `hat_matrix=True` retains `results.S` and `results.R` for inspection.
Chunking reduces inference memory, and `fit(pool=pool)` supports a
`multiprocessing.Pool` (use an `if __name__ == '__main__':` guard on Windows).

`exact_fit()` solves the converged equations at the final selected weights.
It can differ from `fit()` when selection has not converged and uses much more
memory. Increase `max_iter_multi` or tighten `tol_multi` as appropriate and
inspect `selector.bw[2]` for convergence scores.

Install from the project folder with `python -m pip install .`.
Run the numerical checks with `python -m pytest -q tests`.
See `MSGWR_REVIEW.md` for the changes and validation scope.

---

FastSGWR: "Enhancing the Computational Efficiency of the SGWR Model and Introducing Its Software Implementation." This article along the python packages (parallel & sequential), and a Graphic User Interface (GUI) tool named 'SGWR Model' is developed based on this article :SGWR: similarity and geographically weighted regression (https://doi.org/10.1080/13658816.2024.2342319).  

Author info
------------
- Code Author: M. Naser Lessani (GIBD)
- Realeased Year: 2026
- Affiliation: Geoinformation and Big Data Research Laboratory (GIBD), Department of Geography, The Pennsylvania State University, University Park, PA, USA

Overview
--------
The SGWR (Similarity and Geographically Weighted Regression) model is a novel local spatial regression model that extends the conventional GWR by incorporating both geographical proximity and attribute similarity into a composite spatial weight matrix. The  combination of spatial and attribute-based weights is governed by a parameter alpha, which is optimized based on AICc measure.

This Python package includes:
- MPI-enabled parallel implementations of the SGWR
- Serial version of the SGWR model
- Support for Gaussian and bi-square kernels
- Also, supports a combination of adaptive bisquare and gaussian

Key Features
------------
- Parallel Computation with MPI: Achieve substantial runtime reductions using multiple CPU cores.
- Alpha Optimization: Automatically tune the contribution of similarity and spatial proximity.
- Kernel Flexibility: Choose between Gaussian (default) and bi-square kernels.
- Also, users have the ability to either chose standardize or don't standardize their data
- Evaluation Metrics: Outputs include R², adjusted R², AICc, and other metrics
- Also, users can run the GWR model in both parallel and serial version of this library

Installation Requirements
-------------------------
Ensure the following dependencies are installed:

Standard Python Libraries:
- os
- argparse
- datetime
- math
- copy
- typing (Optional)
- itertools (combinations)

MPI and CLI:
- mpi4py
- click

Numerical and Data Handling:
- numpy
- pandas
- scipy (stats, linalg, spatial.distance)

Machine Learning and Metrics:
- scikit-learn (metrics)

Specialized Geospatial Modeling:
- spglm (family, glm, iwls, utils)


Data Format
-----------
Input data must be a CSV file with the following column order:

longitude, latitude, dependent_variable, independent_variable_1, ..., independent_variable_n

Categorical variables must be pre-processed into dummy variables.
Example: For a 3-class variable ("urban", "peri-urban", "rural"), create:
- urban_dummy: 1 if urban, else 0
- peri_urban_dummy: 1 if peri-urban, else 0
- Rural becomes the reference class (excluded)

Usage
-----
After preparing your dataset and ensuring all dependencies are installed, the model can be run via the command line:

MPI Commands (parallel):
----------------------------
- fastsgwr run -np x -data path_to_data (by default the kernel is Gaussian function, and doesn't standardize the data)
- fastsgwr run -np x -data path_to_data -standardize (using Gaussian function and standardize the input data)
- fastsgwr run -np x -data path_to_data -bisquare 
- fastsgwr run -np x -data path_to_data -bisquare -standardize
- fastsgwr run -np x -data path_to_data -biga (adaptive bisquare and gaussian)
- fastsgwr run -np x -data path__to_data -gwr (run gwr as well in parallel)
- x: Number of cores
- path_to_data: Path to the CSV dataset

The output will be a CSV file saved in the same input directory, and containing local coefficients and performance metrics.
PI Commands (parallel):

Serial commands:
----------------------------
- selector = ALPHA(g_coords, g_y, g_x, data, fixed=True, kernel='gaussian') ## for fixed bandwidth and gaussian kernel
- bw, alpha = selector.fit()
- sgwr_model = SGWR(g_coords, g_y, g_x, bw, data, alpha, fixed=True, kernel='gaussian') ## after bandwidth and alpha optimizationi
- result = sgwr_model.fit()
- selector = ALPHA(g_coords, g_y, g_x, data) ## for adaptive bandwidth and bisquare kernel
- bw, alpha = selector.fit()
- sgwr_model = SGWR(g_coords, g_y, g_x, bw, data, alpha) 
- result = sgwr_model.fit()

Parameter extraction when running in serial mode:
----------------------------
- result.R2
- result.adj_R2
- result.aicc
- result.aic
- result.params
- result.bse
- result.localR2
- result.filter_tvals()
- result.filter_tvals(alpha=0.05) ### t values with 95% confidence interval
- result.summary()

Citation
--------
If you use this package in your work, please cite the following articles:

1. Lessani, M.N. and Li, Z., 2024. SGWR: similarity and geographically weighted regression. International Journal of Geographical Information Science, 38(7), pp.1232-1255.
2. Lessani, M.N. and Li, Z., 2025. Enhancing the computational efficiency of the SGWR model and introducing its software implementation. Annals of GIS, 31(4), pp.635-650.
3. Lessani, M.N., Li, Z., Yu, M., Greatrex, H. and Shen, C., 2026. M-SGWR: Multiscale Attribute-Similarity and Geographically Weighted Regression. Geographical Analysis.
