locpick 0.0.0__py3-none-any.whl

locpick/__init__.py

@@ -0,0 +1,27 @@
+"""LocPick: modern location and destination choice modeling.
+
+The package exposes data assembly, model specification, estimation,
+and inference tools for discrete choice models with large alternative sets.
+
+Submodules and attributes are loaded lazily following SPEC 1
+(https://scientific-python.org/specs/spec-0001/) so that ``import locpick``
+is cheap and does not eagerly import JAX, Numba, or Optimistix. The public API
+surface is declared in the sibling ``__init__.pyi`` stub for static type
+checkers and IDE autocomplete.
+
+Examples
+--------
+Import a model class directly from the package namespace::
+
+    from locpick import ChoiceModel, ChoiceTable
+"""
+
+import contextlib
+from importlib.metadata import PackageNotFoundError, version
+
+import lazy_loader as _lazy
+
+__getattr__, __dir__, __all__ = _lazy.attach_stub(__name__, __file__)
+
+with contextlib.suppress(PackageNotFoundError):
+    __version__ = version("locpick")

locpick/__init__.pyi

@@ -0,0 +1,153 @@
+"""Public API stub for locpick.
+
+The top-level namespace exposes only user-facing symbols. Internal
+subpackages (jax, kernels, sampling, solvers) remain importable directly
+for advanced use but are not advertised as public API.
+"""
+
+from . import data as data
+from . import dgp as dgp
+from . import models as models
+from . import results as results
+from . import spec as spec
+from ._sampling.kernels import sample_alternatives as sample_alternatives
+from .data import (
+    ChoiceArrays as ChoiceArrays,
+)
+from .data import (
+    ChoiceTable as ChoiceTable,
+)
+from .data import (
+    EstimationProblem as EstimationProblem,
+)
+from .data import (
+    distance_bands as distance_bands,
+)
+from .data import (
+    distance_matrix as distance_matrix,
+)
+from .data import (
+    euclidean_distance_matrix as euclidean_distance_matrix,
+)
+from .data import (
+    format_coefficient_table as format_coefficient_table,
+)
+from .data import (
+    format_fit_statistics as format_fit_statistics,
+)
+from .data import (
+    format_side_by_side as format_side_by_side,
+)
+from .data import (
+    great_circle_distance_matrix as great_circle_distance_matrix,
+)
+from .data import (
+    nearest_neighbors as nearest_neighbors,
+)
+from .data import (
+    pairwise_distance as pairwise_distance,
+)
+from .dgp import (
+    MixedMNLDataset as MixedMNLDataset,
+)
+from .dgp import (
+    MixedNestedMNLDataset as MixedNestedMNLDataset,
+)
+from .dgp import (
+    MNLDataset as MNLDataset,
+)
+from .dgp import (
+    MNSCLDataset as MNSCLDataset,
+)
+from .dgp import (
+    MSCLDataset as MSCLDataset,
+)
+from .dgp import (
+    NestedMNLDataset as NestedMNLDataset,
+)
+from .dgp import (
+    NestedSCLDataset as NestedSCLDataset,
+)
+from .dgp import (
+    SARMNLDataset as SARMNLDataset,
+)
+from .dgp import (
+    SCLDataset as SCLDataset,
+)
+from .dgp import (
+    simulate_mixed_logit as simulate_mixed_logit,
+)
+from .dgp import (
+    simulate_mixed_nested_logit as simulate_mixed_nested_logit,
+)
+from .dgp import (
+    simulate_mnl as simulate_mnl,
+)
+from .dgp import (
+    simulate_mnscl as simulate_mnscl,
+)
+from .dgp import (
+    simulate_mscl as simulate_mscl,
+)
+from .dgp import (
+    simulate_nested_logit as simulate_nested_logit,
+)
+from .dgp import (
+    simulate_nested_scl as simulate_nested_scl,
+)
+from .dgp import (
+    simulate_sar_mnl as simulate_sar_mnl,
+)
+from .dgp import (
+    simulate_scl as simulate_scl,
+)
+from .models import (
+    ChoiceModel as ChoiceModel,
+)
+from .models import (
+    NestingTree as NestingTree,
+)
+from .models import (
+    NestSpec as NestSpec,
+)
+from .models import (
+    ParamDistribution as ParamDistribution,
+)
+from .models import (
+    naturalize_nest_params as naturalize_nest_params,
+)
+from .results import (
+    FitResult as FitResult,
+)
+from .results import (
+    HausmanTest as HausmanTest,
+)
+from .results import (
+    LikelihoodRatioTest as LikelihoodRatioTest,
+)
+from .results import (
+    WaldTest as WaldTest,
+)
+from .results import (
+    hausman_test as hausman_test,
+)
+from .results import (
+    lr_test as lr_test,
+)
+from .results import (
+    wald_test as wald_test,
+)
+from .spec import (
+    InteractionTerm as InteractionTerm,
+)
+from .spec import (
+    ModelSpec as ModelSpec,
+)
+from .spec import (
+    ScopedTerm as ScopedTerm,
+)
+from .spec import (
+    interaction as interaction,
+)
+
+__version__: str

locpick/_jax/__init__.py

@@ -0,0 +1,55 @@
+"""JAX-accelerated backend for locpick choice models.
+
+This package provides:
+
+- :class:`ChoiceDataJAX` — JAX-ready estimation data container
+- :class:`EdgeDataJAX` — JAX-ready spatial edge structure
+- :class:`Objective` — unified optimization objective (LL + gradient + Hessian)
+- :class:`ParamTransform` — parameter transformation utilities
+- Pure JAX probability kernels (:func:`mnl_log_probs`, :func:`mnl_probs`, :func:`scl_log_probs`,
+  :func:`nested_log_probs`, :func:`mixed_logit_ll`)
+- Objective builders (:func:`build_mnl_objective`, :func:`build_scl_objective`,
+  :func:`build_mscl_objective`, :func:`build_nested_objective`,
+  :func:`build_mixed_logit_objective`)
+
+The kernels are standalone, testable, composable JAX functions that can be
+JIT-compiled and vmap'd independently of any model class.
+"""
+
+from .builders import (
+    build_mixed_logit_objective,
+    build_mnl_objective,
+    build_mscl_objective,
+    build_nested_objective,
+    build_scl_objective,
+)
+from .data import ChoiceDataJAX, EdgeDataJAX
+from .kernels import (
+    mixed_logit_ll,
+    mnl_log_probs,
+    mnl_probs,
+    nested_log_probs,
+    scl_log_probs,
+)
+from .objective import Objective
+from .transforms import Identity, ParamTransform, Sigmoid, SoftPlus
+
+__all__ = [
+    "ChoiceDataJAX",
+    "EdgeDataJAX",
+    "Objective",
+    "ParamTransform",
+    "Sigmoid",
+    "SoftPlus",
+    "Identity",
+    "mnl_log_probs",
+    "mnl_probs",
+    "scl_log_probs",
+    "nested_log_probs",
+    "mixed_logit_ll",
+    "build_mnl_objective",
+    "build_scl_objective",
+    "build_mscl_objective",
+    "build_nested_objective",
+    "build_mixed_logit_objective",
+]

locpick/_jax/__init__.pyi

@@ -0,0 +1,62 @@
+from . import builders as builders
+from . import data as data
+from . import kernels as kernels
+from . import objective as objective
+from . import transforms as transforms
+from .builders import (
+    build_mixed_logit_objective as build_mixed_logit_objective,
+)
+from .builders import (
+    build_mnl_objective as build_mnl_objective,
+)
+from .builders import (
+    build_mscl_objective as build_mscl_objective,
+)
+from .builders import (
+    build_nested_objective as build_nested_objective,
+)
+from .builders import (
+    build_scl_objective as build_scl_objective,
+)
+from .data import (
+    ChoiceDataJAX as ChoiceDataJAX,
+)
+from .data import (
+    EdgeDataJAX as EdgeDataJAX,
+)
+from .kernels import (
+    compute_ll as compute_ll,
+)
+from .kernels import (
+    compute_utilities as compute_utilities,
+)
+from .kernels import (
+    mixed_logit_ll as mixed_logit_ll,
+)
+from .kernels import (
+    mnl_log_probs as mnl_log_probs,
+)
+from .kernels import (
+    mnl_probs as mnl_probs,
+)
+from .kernels import (
+    nested_log_probs as nested_log_probs,
+)
+from .kernels import (
+    scl_log_probs as scl_log_probs,
+)
+from .objective import (
+    Objective as Objective,
+)
+from .transforms import (
+    Identity as Identity,
+)
+from .transforms import (
+    ParamTransform as ParamTransform,
+)
+from .transforms import (
+    Sigmoid as Sigmoid,
+)
+from .transforms import (
+    SoftPlus as SoftPlus,
+)