MNL prediction functionality

We need to build out prediction functionality for multinomial models. (Updated 5/17/2018 to reflect helpful discussions with @waddell and @janowicz.) Most of this functionality already exists in some form in UrbanSim, but will need to be cleaned up and reorganized.

Requirements

We want to be able to take parameter estimates from a fitted model and apply them to new choice scenarios to produce (a) probability distributions among alternatives and (b) simulated choices.

Approach

Generating probabilities for new choice scenarios should be a feature of a model's results class, I think. In an interactive session, users would fit a model and then use the results object to generate predictions. Libraries like UrbanSim Templates will want to generate predictions from saved parameters, so we should make sure the results constructor supports this well.

Simulated choices should be implemented separately from the individual models, I think, because the same logic can be used with probabilities from any multinomial model.

We need to be able to handle multiple types of choice simulation for different empirical contexts:

Choosers make independent choices from non-exclusive alternatives (e.g. travel mode choice, travel destination choice). This is the most straightforward case. In the current UrbanSim codebase it's referred to as probability_mode = 'full_product' and choice_mode = 'individual', and ChoiceModels can implement it the same way.

Choosers are being allocated to alternatives that have fixed capacity (e.g. home location choice at a unit or zonal level). This has been implemented in the UrbanSim zone model, where it's called "lottery choices". Choices can either proceed one by one, or in larger batches where agents whose choices exceed capacity have to choose again in the next round.

https://github.com/UDST/zone_model/blob/master/zone_model/utils.py#L117-L140

Special case of fixed-capacity allocation where each agent has the same probability distribution over alternatives (e.g. home location choice without any attributes of the chooser in the utility function). This is very efficient to compute because it can be done in a single step. This is implemented in the core UrbanSim codebase, where it's referred to as probability_mode = 'single_chooser' and choice_mode = 'aggregate'. The outcome should be equivalent to "lottery choice", so for simplicity I think we should only keep this if it has a big performance advantage.

Special considerations

Price/demand equilibration. In some cases we need to intervene in the choice simulation process, for example checking the aggregate attractiveness of neighborhoods and raising their prices until demand falls below supply everywhere. I think this could be done through a separate module that feeds its final parameters into the "lottery choice" module.

More code examples

Getting probabilities from PyLogit:

https://github.com/UDST/urbansim_templates/blob/master/urbansim_templates/models/small_multinomial_logit.py#L357

Getting probabilities and choices using core UrbanSim MNL functions:

https://github.com/UDST/choicemodels/blob/master/notebooks/MNL-prediction-demo-02.ipynb

Dependencies

After building this out, we'll need to:

write and update unit tests
update UrbanSim Templates to use the new functionality

UDST / choicemodels