Metadata-Version: 2.4
Name: choicemodels
Version: 0.3
Summary: Python library for discrete choice modeling
Author: UDST
License-Expression: BSD-3-Clause
Project-URL: Documentation, https://udst.github.io/choicemodels/
Project-URL: Repository, https://github.com/UDST/choicemodels
Project-URL: Issues, https://github.com/UDST/choicemodels/issues
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: licenses/PYLOGIT_LICENSE.txt
License-File: PYLOGIT_ATTRIBUTION.md
License-File: PYLOGIT_CONTRIBUTORS.txt
Requires-Dist: numpy>=1.21
Requires-Dist: pandas<4,>=1.5
Requires-Dist: patsy>=0.5
Requires-Dist: scipy>=1.7
Requires-Dist: statsmodels>=0.13
Requires-Dist: tqdm>=4.64
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=2; extra == "docs"
Dynamic: license-file

# ChoiceModels

[![CI](https://github.com/UDST/choicemodels/actions/workflows/ci.yml/badge.svg)](https://github.com/UDST/choicemodels/actions/workflows/ci.yml)

ChoiceModels is a Python library for discrete choice modeling, with utilities for sampling, simulation, and other ancillary tasks. It's part of the [Urban Data Science Toolkit](https://docs.udst.org) (UDST).

### Project scope

**Status:** Active

**Mission:** ChoiceModels provides reusable tools for specifying, estimating,
sampling, and simulating discrete-choice models within larger analytical
workflows.

**Architecture:** ChoiceModels provides portable Python implementations and
interfaces for discrete-choice workflows and conventional estimation. Its
reference implementations target conventional CPU-based execution, while
estimator interfaces allow alternative execution engines to interoperate with
the library.

The project maintains and develops:

- construction and manipulation of choice tables;
- sampling of alternatives;
- discrete-choice model specifications and interfaces;
- conventional model estimation and estimator integrations;
- Monte Carlo choice simulation;
- capacity-constrained choice algorithms; and
- interoperable representations of estimated choice models.

ChoiceModels is designed as a general-purpose discrete-choice library and as
an integration layer between model specifications, estimation engines, and
simulation workflows.

Development of choice-model methods and estimator integrations is welcome
within this mission and architecture. Material changes to the project's
mission or execution architecture are considered through UDST's
organization-level governance process.

See the [UDST Project Directory](https://github.com/UDST/.github/blob/main/PROJECTS.md)
for organization-wide project status and policy.


### Features

The library focuses mainly on tools to help integrate discrete choice models into larger workflows. 

ChoiceModels can automate the creation of choice tables for estimation or simulation, using uniform or weighted random sampling of alternatives, as well as interaction terms or cartesian merges. 

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

ChoiceModels includes a custom engine for Multinomial Logit estimation that's optimized for fast performance with large numbers of alternatives, as well as a flexible MNL implementation compatible with [PyLogit](https://github.com/timothyb0912/pylogit) model specifications.


### Installation

ChoiceModels requires Python 3.10 or later, and can be installed using the Pip or Conda package managers:

```
pip install choicemodels
```

```
conda install choicemodels --channel conda-forge
```


### Documentation

See the online documentation for much more: https://udst.github.io/choicemodels

Some additional documentation is available within the repo in `CHANGELOG.md`, `CONTRIBUTING.md`, `/docs/README.md`, and `/tests/README.md`.

There's discussion of current and planned features in the [Pull requests](https://github.com/udst/choicemodels/pulls?utf8=✓&q=is%3Apr) and [Issues](https://github.com/udst/choicemodels/issues?utf8=✓&q=is%3Aissue), both open and closed.
