Getting started¶

Intro¶

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 (UDST).

The library currently focuses on tools to help integrate discrete choice models into larger workflows, drawing on other packages such as the excellent PyLogit for most estimation of models. 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.

ChoiceModels is hosted on Github with a BSD 3-Clause open source license. The code repository includes some material not found in this documentation: a change log, a contributor’s guide, and instructions for running the tests, updating the documentation, and creating a new release. Another useful resource is the issues and pull requests on Github, which include detailed feature proposals and other discussions.

ChoiceModels was created in 2016, with contributions from Sam Maurer (maurer@urbansim.com), Timothy Brathwaite, Geoff Boeing, Paul Waddell, Max Gardner, Eddie Janowicz, Arezoo Besharati Zadeh, Jacob Finkelman, Catalina Vanoli, and others. It includes earlier code written by Matt Davis, Fletcher Foti, and Paul Sohn.

Installation¶

ChoiceModels is tested with Python 2.7, 3.5, 3.6, 3.7, and 3.8. It should run on any platform.

Production releases¶

ChoiceModels can be installed using the Pip or Conda package managers. We recommend Conda because it resolves dependency conflicts better.

pip install choicemodels

conda install choicemodels --channel conda-forge

When new production releases of ChoiceModels come out, you can upgrade like this:

pip install choicemodels --upgrade

conda update choicemodels --channel conda-forge

Developer pre-releases¶

Developer pre-releases of ChoiceModels can be installed using the Github URL. Additional information about the developer releases can be found in Github pull requests.

pip install git+git://github.com/udst/choicemodels.git

You can use the same command to upgrade.

Cloning the repository¶

You can also install ChoiceModels by cloning the Github repository, which is the best way to do it if you’ll be modifying the code. The main branch contains the latest developer release.

git clone https://github.com/udst/choicemodels.git
cd choicemodels
python setup.py develop

Update it with git pull.

Basic usage¶

You can use components of ChoiceModels individually, or combine them together to streamline model estimation and simulation workflows. Other UDST libraries like UrbanSim Templates use ChoiceModels objects as inputs and outputs.

If you have choosers and alternatives as Pandas DataFrames, you can prepare them for model estimation like this:

mct = choicemodels.tools.MergedChoiceTable(obs, alts, chosen_alternatives='chosen',
                                           sample_size=10, ..)

Then, you can estimate a Multinomial Logit model like this:

results = choicemodels.MultinomialLogit(mct, model_expression='x1 + x2 + x3')

This provides a choicemodels.MultinomialLogitResults object, from which you can obtain probability distributions for out-of-sample choice scenarios in order to generate simulated choices.

mct2 = choicemodels.tools.MergedChoiceTable(obs2, alts, sample_size=10, ..)
probs = results.probabilities(mct2)
choices = choicemodels.tools.monte_carlo_choices(probs)