synthicity/urbansim — pull request #134 by jiffyclub (2014-12-09 01:07:12+00:00)
Title: Discrete Choice Models

This is a big set of changes associated with synthicity/activitysim#3.

The goal here is to generalize our existing location choice model classes into discrete choice models with varying capabilities. The LCMs had baked in some assumptions that made them inappropriate for something like automobile ownership, even though the underlying MNL code is fully compatible with general discrete choice modeling. These some of the assumptions:

- only one chooser was used for calculating probabilites
- choices were made for choosers in aggregate because all choosers had the same probabilities, locations are unavailable once chosen, and it results in better performance
- locations were removed from the alternatives pool at the group level because those locations were no longer available to others once chosen

To support LCMs we need to keep those capabilities, but we also need to be able to calculate probabilities and make choices on a per-chooser basis, as well as not modify alternatives between making choices for different segments.

In this PR I've changed all class names from "LocationChoice" to "DiscreteChoice" and cleaned up docstrings and variable names that referred to locations. I've also add some new options: `probability_mode` (can be `single_chooser` or `full_product`) and `choice_mode` (can be `individual` or `aggregate`) for controlling how probabilities are calculated and choices are made. At the group level there's a new option `remove_alts` that controls whether alternatives are filtered after performing prediction for a segment.

The defaults are `full_product`, `individual`, and `False` for `probability_mode`, `choice_mode`, and `remove_alts`, respectively. These are the settings you'd use for something like automobile ownership.

For something like LCMs you'd set those to `single_chooser`, `aggregate`, and `True`.

The Travis runs are failing right now because these changes are breaking [sanfran_urbansim](https://github.com/synthicity/sanfran_urbansim). I'll make a PR on there shortly.