Metadata-Version: 2.4
Name: locpick
Version: 0.0.0
Summary: Modern location and destination choice modeling
Author: eli knaap
License: BSD-3-Clause
Project-URL: Homepage, https://knaaptime.github.io/locpick
Project-URL: Documentation, https://knaaptime.github.io/locpick
Project-URL: Source, https://github.com/knaaptime/locpick
Project-URL: Tracker, https://github.com/knaaptime/locpick/issues
Project-URL: Changelog, https://github.com/knaaptime/locpick/releases
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: xarray>=2022.06
Requires-Dist: formulaic>=0.5
Requires-Dist: scipy>=1.9
Requires-Dist: numba>=0.59
Requires-Dist: lazy_loader>=0.4
Requires-Dist: jax>=0.4
Provides-Extra: optax
Requires-Dist: optax>=0.1; extra == "optax"
Provides-Extra: optimagic
Requires-Dist: optimagic>=0.5; extra == "optimagic"
Provides-Extra: optimistix
Requires-Dist: optimistix>=0.0.6; extra == "optimistix"
Provides-Extra: spatial
Requires-Dist: libpysal>=4.0; extra == "spatial"
Requires-Dist: geopandas>=0.13; extra == "spatial"
Requires-Dist: scikit-learn>=1.2; extra == "spatial"
Provides-Extra: sparse
Requires-Dist: sparsax>=0.7; extra == "sparse"
Requires-Dist: scikit-sparse>=0.4; extra == "sparse"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: formulaic>=0.5; extra == "test"
Provides-Extra: docs
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-autodoc2; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-immaterial; extra == "docs"
Requires-Dist: watermark; extra == "docs"
Provides-Extra: all
Requires-Dist: locpick[optax]; extra == "all"
Requires-Dist: locpick[optimagic]; extra == "all"
Requires-Dist: locpick[optimistix]; extra == "all"
Requires-Dist: locpick[spatial]; extra == "all"
Requires-Dist: locpick[sparse]; extra == "all"
Provides-Extra: dev
Requires-Dist: locpick[all]; extra == "dev"
Requires-Dist: locpick[test]; extra == "dev"
Requires-Dist: locpick[docs]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# LocPick

`locpick` is a Python library for estimating **discrete choice models of location decisions** — where individuals, households, or firms choose among *spatially-defined* alternatives (neighborhoods, jobs, housing units, transit stops). These methods have broad applicability but are common in regional land-use and housing market modeling. The package is designed for:

- **Large-scale urban models**: 100K+ choosers, 1K+ alternatives
- **Sampling-based estimation**: Most alternatives are irrelevant; only a sampled subset is evaluated per chooser
- **Spatial dependence**: Nearby alternatives can affect each other or share unobserved attributes (via `graph=` on any model)
- **Heterogeneous preferences**: Mixed logit for random taste variation
- **Nested structure**: Nested logit for hierarchical choice (e.g., county → tract → block)
- **JAX-native computation**: JIT-compiled kernels, GPU acceleration, automatic differentiation

The package is **not** a general-purpose ML library. It is specifically for structural econometric models of choice where the likelihood has a closed form (or simulated approximation) and parameters have behavioral interpretations. For more transportation-oriented problems, see [larch](https://github.com/driftlesslabs/larch)

## Features

LocPick can automate the creation of choice tables for estimation or simulation, using census choice sets, uniform or weighted random sampling of alternatives, generated interaction terms, and cartesian merges. A unique feature is the implementation of *spatial* choice models, which take one of two forms.

- The [Bhat et al](https://linkinghub.elsevier.com/retrieve/pii/S0191261503000055) approach is similar to a spatial error model, assuming that nearby alternatives are more similar (closer substitutes). 
- The SAR style approach assumes that the structural utility of each alternative $V$ has a simultaneous autoregressive structure, and is estimated with either [PML](http://dx.doi.org/10.1016/j.regsciurbeco.2009.09.004) or [GMM](https://www.sciencedirect.com/science/article/pii/S0166046217300625)

It also provides tools for Monte Carlo simulation of choices given probability distributions from fitted models, with fast algorithms for independent or capacity-constrained choices.

LocPick includes estimators for classic, spatially-correlated, and simultaneous autoregressive:

- Multinomial Logit
- Nested Logit
- Mixed Logit and 
- Mixed/Nested 

models, and an internal data pipeline designed around pandas inputs, xarray-backed alignment, and NumPy/JAX-ready arrays.
