locpick 0.0.0__tar.gz

locpick-0.0.0/.coveragerc

@@ -0,0 +1,8 @@
+# .coveragerc
+[run]
+source = locpick
+concurrency = multiprocessing
+parallel = true
+omit =
+    tests/*
+    */tests/*

locpick-0.0.0/.github/release.yml

@@ -0,0 +1,22 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+    authors:
+      - dependabot
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking
+    - title: New Features
+      labels:
+        - enhancement
+    - title: Bug Fixes
+      labels:
+        - bug
+    - title: Documentation
+      labels:
+        - documentation
+    - title: Other Changes
+      labels:
+        - "*"

locpick-0.0.0/.github/workflows/build_docs.yml

@@ -0,0 +1,106 @@
+---
+name: Build Docs
+
+on:
+  push:
+    branches: [dev]
+    tags:
+        - "v*"
+  pull_request:
+    branches:
+      - "*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Manual Doc Build
+        default: run-doc-build
+        required: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: Build & push docs
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      matrix:
+        os: ["ubuntu-latest"]
+        environment-file: [docs/docs_env.yml]
+        experimental: [false]
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup micromamba
+        uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-file: ${{ matrix.environment-file }}
+          micromamba-version: "latest"
+
+      - name: Install package
+        run: pip install . --no-deps
+
+      - name: Make docs
+        run: cd docs; make html
+        env:
+          CENSUS: ${{ secrets.CENSUS }}
+
+      - name: Zip documentation
+        if: ${{ github.event_name == 'pull_request' }}
+        run: zip docs_artifact.zip docs/build/html -r
+
+      - name: Upload artifact
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs_artifact
+          path: docs_artifact.zip
+
+      - name: Publish to Github Pages on dev (dev)
+        if: ${{ github.ref == 'refs/heads/dev' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html/
+          destination_dir: dev
+          keep_files: false
+
+      - name: Publish to Github Pages on release (versioned)
+        if: ${{ github.ref_type == 'tag' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html/
+          destination_dir: ${{ github.ref_name }}
+
+      - name: Publish to Github Pages on release (stable)
+        if: ${{ github.ref_type == 'tag' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html/
+          destination_dir: stable
+          keep_files: false
+
+      - name: Update the versions switcher
+        if: ${{ github.ref_type == 'tag' }}
+        run: |
+          git checkout gh-pages
+          git fetch
+          git pull
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          python docs/update_version_json.py --version ${{ github.ref_name }}
+          git add versions.json
+          git commit -m "Update versions switcher"
+          git push
+          git checkout dev

locpick-0.0.0/.github/workflows/lint.yml

@@ -0,0 +1,22 @@
+---
+name: Lint
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches:
+      - "*"
+  workflow_dispatch:
+
+jobs:
+  ruff:
+    name: Ruff (lint + format check)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          version: "0.15.11"
+      - run: ruff check .
+      - run: ruff format --check .

locpick-0.0.0/.github/workflows/spec1.yml

@@ -0,0 +1,126 @@
+name: SPEC 1 Compliance
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches:
+      - "*"
+  workflow_dispatch:
+
+jobs:
+  spec1:
+    name: Check SPEC 1 (lazy loading)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Check SPEC 1 compliance
+        run: |
+          python - <<'SCRIPT'
+          import re
+          import sys
+          from pathlib import Path
+
+          # ── Auto-detect package name from pyproject.toml ────────────────
+          pyproject = Path("pyproject.toml")
+          if not pyproject.is_file():
+              sys.exit("❌ No pyproject.toml found in repo root")
+          pyproject_text = pyproject.read_text()
+          m = re.search(r'^name\s*=\s*"([^"]+)"', pyproject_text, re.MULTILINE)
+          if not m:
+              sys.exit("❌ Could not find [project] name in pyproject.toml")
+          pkg_name = m.group(1).replace("-", "_")
+
+          # ── Auto-detect package directory (flat or src layout) ─────────
+          PKG = None
+          for candidate in [Path(pkg_name), Path("src") / pkg_name]:
+              if candidate.is_dir() and (candidate / "__init__.py").is_file():
+                  PKG = candidate
+                  break
+          if PKG is None:
+              sys.exit(f"❌ Could not find package directory for '{pkg_name}'")
+
+          print(f"Package: {pkg_name}  →  {PKG}/\n")
+          errors = []
+          warnings = []
+
+          # ── 1. lazy_loader is a dependency ──────────────────────────────
+          if "lazy_loader" not in pyproject_text:
+              errors.append("lazy_loader not found in pyproject.toml dependencies")
+
+          # ── 2. Scan every __init__.py under the package ─────────────────
+          has_any_pyi = False
+
+          for init in sorted(PKG.rglob("__init__.py")):
+              rel = init.relative_to(PKG.parent)
+              src = init.read_text()
+
+              # Skip test directories
+              if any(part == "tests" or part.startswith("test_") for part in init.parts):
+                  continue
+
+              uses_stub = "attach_stub" in src
+              uses_attach = bool(re.search(r"\.attach\s*\(", src)) and not uses_stub
+              uses_lazy = uses_stub or uses_attach
+
+              # 2a. If using lazy_loader, must set __getattr__, __dir__, __all__
+              if uses_lazy:
+                  for attr in ("__getattr__", "__dir__", "__all__"):
+                      if attr not in src:
+                          errors.append(f"{rel}: lazy_loader used but {attr} not assigned")
+
+              # 2b. If using attach_stub, must have a .pyi sibling
+              if uses_stub:
+                  pyi = init.with_suffix(".pyi")
+                  has_any_pyi = True
+                  if not pyi.is_file():
+                      errors.append(f"{rel}: uses attach_stub but {pyi.name} is missing")
+
+              # 2c. No eager submodule imports alongside lazy loading
+              if uses_lazy:
+                  for line in src.splitlines():
+                      stripped = line.strip()
+                      if stripped.startswith("#") or not stripped:
+                          continue
+                      if re.match(r"^from\s+\.\w+\s+import\s+", stripped):
+                          if any(allow in stripped for allow in
+                                 ["lazy_loader", "contextlib", "importlib"]):
+                              continue
+                          errors.append(
+                              f"{rel}: eager import alongside lazy_loader: {stripped}"
+                          )
+
+          # ── 3. If .pyi stubs exist, check py.typed and package-data ────
+          if has_any_pyi:
+              py_typed = PKG / "py.typed"
+              if not py_typed.is_file():
+                  warnings.append(
+                      f"{PKG}/py.typed is missing — required by PEP 561 when "
+                      "shipping .pyi stubs"
+                  )
+              if "*.pyi" not in pyproject_text:
+                  warnings.append(
+                      "pyproject.toml [tool.setuptools.package-data] should "
+                      "include '*.pyi' and '**/*.pyi' for .pyi stubs to ship"
+                  )
+
+          # ── Report ─────────────────────────────────────────────────────
+          if warnings:
+              print("⚠️  Warnings:")
+              for w in warnings:
+                  print(f"  • {w}")
+              print()
+
+          if errors:
+              print("❌ SPEC 1 compliance check FAILED:\n")
+              for e in errors:
+                  print(f"  • {e}")
+              sys.exit(1)
+          else:
+              print("✅ SPEC 1 compliance check passed")
+          SCRIPT

locpick-0.0.0/.github/workflows/unittests.yml

@@ -0,0 +1,82 @@
+---
+name: Continuous Integration
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches:
+      - "*"
+  schedule:
+    - cron: "59 23 * * *"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Manual CI Run
+        default: test
+        required: false
+
+jobs:
+  tests:
+    name: ${{ matrix.os }}, ${{ matrix.environment-file }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        environment-file: [
+           ci/312-oldest.yml,
+           ci/312-latest.yml,
+           ci/313-latest.yml,
+           ci/314-latest.yml,
+        ]
+        include:
+          - environment-file: ci/314-latest.yml
+            os: macos-13  # Intel
+          - environment-file: ci/314-latest.yml
+            os: macos-latest  # Apple Silicon
+          - environment-file: ci/314-latest.yml
+            os: windows-latest
+      fail-fast: false
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: setup micromamba
+        uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-file: ${{ matrix.environment-file }}
+          micromamba-version: "latest"
+
+      - name: environment info
+        run: |
+          micromamba info
+          micromamba list
+
+      - name: install package
+        run: pip install -e . --no-deps
+
+      - name: run tests
+        run: |
+          pytest tests/ -m '' \
+            -n auto \
+            -v \
+            -r a \
+            --color yes \
+            --cov locpick \
+            --cov-append \
+            --cov-report term-missing \
+            --cov-report=xml .
+
+      - name: codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml

locpick-0.0.0/.github/workflows/upload_package.yml

@@ -0,0 +1,51 @@
+---
+name: Release & Publish
+
+on:
+  push:
+    # Sequence of patterns matched against refs/tags
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Manual Release
+        default: test
+        required: false
+
+jobs:
+  build:
+    name: Create release & publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MANDATORY for trusted publishing to PyPI
+      contents: write  # MANDATORY for the Github release action
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check --strict dist/*
+
+      - name: Create Release Notes
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            await github.request(`POST /repos/${{ github.repository }}/releases`, {
+              tag_name: "${{ github.ref }}",
+              generate_release_notes: true
+            });
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

locpick-0.0.0/.gitignore

@@ -0,0 +1,95 @@
+benchmarks/
+ref/
+
+.copilot
+.serena/
+.cache
+.ruff_cache
+.pytest_cache
+.vscode
+refpy
+
+
+# Jupyter checkpoints
+**/.ipynb_checkpoints
+.pytest_cache/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+bin/
+build/
+develop-eggs/
+dist/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+.idea/
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Rope
+.ropeproject
+
+# Django stuff
+*.log
+*.pot
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+docs/source/generated/
+# Added by code-review-graph
+.code-review-graph/
+
+# macOS
+.DS_Store
+
+# AI assistant configs and scratch (local, per-developer)
+.claude/
+.codebuddy/
+.gemini/
+.kiro/
+.qoder/
+.serena/
+.cursorrules
+.windsurfrules
+.mcp.json
+opencode.jsonc
+AGENTS.md
+CLAUDE.md
+CODEBUDDY.md
+GEMINI.md
+QODER.md
+.github/code-review-graph.instruction.md

locpick-0.0.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format
+        language: system
+        types: [python]

locpick-0.0.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, eli knaap
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

locpick-0.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+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.