Metadata-Version: 2.4
Name: neighbayes
Version: 0.0.0
Summary: Bayesian spatial econometric regression models in Python
Author: eli knaap
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/knaaptime/neighbayes
Project-URL: Repository, https://github.com/knaaptime/neighbayes
Project-URL: Issues, https://github.com/knaaptime/neighbayes/issues
Keywords: bayesian,spatial econometrics,spatial statistics,regression,mcmc,gibbs sampling,pymc,spatial analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pymc>=5.16
Requires-Dist: pytensor>=2.25
Requires-Dist: arviz<1,>=0.18
Requires-Dist: libpysal>=4.9
Requires-Dist: formulaic>=1.0
Requires-Dist: lazy_loader>=0.4
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.1
Requires-Dist: polyagamma>=2.0
Requires-Dist: scikit-sparse>=0.5
Provides-Extra: viz
Requires-Dist: graphviz; extra == "viz"
Provides-Extra: backend
Requires-Dist: dm-tree; extra == "backend"
Requires-Dist: blackjax; extra == "backend"
Requires-Dist: numpyro; extra == "backend"
Requires-Dist: nutpie; extra == "backend"
Requires-Dist: equinox; extra == "backend"
Requires-Dist: sparsax; extra == "backend"
Requires-Dist: pgjax; extra == "backend"
Provides-Extra: cv
Requires-Dist: spml; extra == "cv"
Dynamic: license-file

# neighbayes

[![Continuous Integration](https://github.com/knaaptime/neighbayes/actions/workflows/unittests.yml/badge.svg)](https://github.com/knaaptime/neighbayes/actions/workflows/unittests.yml)
[![codecov](https://codecov.io/gh/knaaptime/neighbayes/branch/main/graph/badge.svg?token=XO4SilfBEb)](https://codecov.io/gh/knaaptime/neighbayes)

`neighbayes` is a Python package for Bayesian estimation of spatial econometric models. Every model is a class, and specified with a Wilkinson formula via
[`formulaic`](https://matthew.wardrop.casa/formulaic/latest/) and a PySAL
[`Graph`](https://pysal.org/libpysal/stable/generated/libpysal.graph.Graph.html)
(or any `scipy.sparse` matrix) for the spatial weights $W$; `fit()` returns an
`arviz.InferenceData`, so the standard posterior tooling (`az.plot_trace`,
`az.compare`, `az.loo`) works without translation (though exercise caution as WAIC/LOO diagnostics aren't valid for spatial models).

```python
import libpysal
from neighbayes.dgp import simulate_sar
from neighbayes.models import OLS, SAR

gdf = simulate_sar(n=400, beta=[1, 0.4, 2.5], rho=0.6, create_gdf=True)
G = libpysal.graph.Graph.build_contiguity(gdf).transform("r")
form = "y ~ -1 + X_0 + X_1 + X_2"

# start with a baseline OLS and test the residuals for spatial dependence
ols = OLS(formula=form, W=G, data=gdf)
ols.fit()
print(ols.spatial_diagnostics_decision(format="ascii"))

# the diagnostics point to SAR here, so fit it and decompose the spillovers
sar = SAR(formula=form, W=G, data=gdf)
sar.fit(draws=2000, chains=4, random_seed=42)
sar.summary()
sar.spatial_effects()
```

`neighbayes` provides roughly fifty model classes behind one formula interface, each
with a matching simulator in `neighbayes.dgp`. Every fit comes with Bayesian LM
diagnostics (with a decision tree for specification search) and posterior decompositions
of direct, indirect, and total effects. Every model (almost) has a custom Gibbs sampler
for [better mixing](https://onlinelibrary.wiley.com/doi/abs/10.1111/gean.12135) (with both numby and jax implementations), but can fall back to PyMC if requested.

## Installation

```bash
conda install -c conda-forge neighbayes   # or: pip install neighbayes
```

Requires Python 3.12+. The [installation guide](https://pysal.org/neighbayes/installation.html)
covers development installs and the optional JAX backend.

## Documentation

Model-by-model user guides, the diagnostics battery, effects interpretation, and the
API reference are at [pysal.org/neighbayes](https://pysal.org/neighbayes).

## Validation

Every model includes thorough parameter recovery tests, and samplers have been validated
against maximum likelihood estimators as well as published results (see docs).
