Location Choice Model

The LocationChoiceModel class implemented in urbansim is a special case of the ChoiceModel class (see Section 25.4.5 for details). The choice set is a set of locations that agents choose from. A set of locations can be sampled to each agent.

Suppose that in addition to the set of 10 households, we have a set of 9 locations with the attributes cost of living and capacity, respectively, stored in a file locations.tab:

location  cost  capacity
1        500    1
2        200    1
3        600    2
4       1000    3
5        100    1
6       2000    3
7        300    1
8        400    1
9        800    2

One can represent this dataset using again the Dataset class:

>>> locations = Dataset(in_storage = storage,
                        in_table_name = 'locations', 
                        id_name='location',
                        dataset_name='gridcell')

We use here the storage object created on page , since the table is stored in the same directory.

Suppose, we wish to simulate a process of agents choosing locations. As a first example, suppose our only predictor is the location attribute cost with a coefficient value of $-0.01$ (modeling a negative effect of cost on the choice preferences). (For simplicity, we skip the estimation process and consider the coefficient value as given.) As in the previous section, we create a coefficient object, a specification object and a choice model object, respectively:

>>> coefficients = Coefficients(names=("costcoef", ), values=(-0.01,))
>>> specification = EquationSpecification(variables=("gridcell.cost", ),
                                          coefficients=("costcoef", ))
>>> from urbansim.models.household_location_choice_model import \
                               HouseholdLocationChoiceModel
>>> hlcm = HouseholdLocationChoiceModel(
                               location_set = locations,
                               sampler=None,
                               compute_capacity_flag=False)

The household location choice model (HLCM) is a child of LocationChoiceModel with some useful default settings. The argument sampler specifies a module to be used for sampling locations to each agent. If it is None, all locations are considered as a possible alternative for each agent. The argument compute_capacity_flag specifies if the procedure should take capacity of locations into account.

We can run the HLCM by using the method run() which takes as obligatory arguments specification, coefficients and the set of agents for which the model runs.

>>> seed(1)
>>> result = hlcm.run(specification, coefficients, agent_set=households)
Running Household Location Choice Model 
                 (from urbansim.models.household_location_choice_model): 
                                     started on Wed Nov  5 12:53:11 2008
    Total number of individuals: 10
    HLCM chunk 1 out of 1.: started on Wed Nov  5 12:53:11 2008
        Number of agents in this chunk: 10
    HLCM chunk 1 out of 1.: completed....................................0.0 sec
Running Household Location Choice Model 
      (from urbansim.models.household_location_choice_model): completed...0.0 sec

The results of the HLCM run determine locations that agents have chosen. The model modifies values of the attribute `location' of the agent set or adds this attribute to the dataset, if it doesn't exist:

>>> households.get_attribute("location")
array([5, 5, 5, 5, 5, 7, 7, 2, 5, 5])

One way of visualizing results of the HLCM run is to plot a histogram of the choices, including the capacity of each location (requires matplotlib library):

>>> hlcm.plot_choice_histograms(capacity=locations.get_attribute("capacity"))

In our case, more agents decided for the fifth and seventh location than there are units available (which corresponds to the fact that those are two of the three cheapest locations).

In the above example, the discrete choice model consists of steps such as computing utilities via the opus_core.linear_utilities class, computing probabilities via the opus_core.mnl_probabilities class and computing choices via the opus_core.random_choices class. These components (default values) can be easily exchanged by other implementations. For example, the class urbansim.lottery_choices for computing choices takes into account capacity and forces agents to re-decide, if there is an overflow in the locations capacity:

>>> number_of_agents = "gridcell.number_of_agents(household)"
>>> hlcm2 = HouseholdLocationChoiceModel(
                         location_set = locations,
                         sampler=None,
                         choices="urbansim.lottery_choices",
                         compute_capacity_flag=True,
                         capacity_string="capacity",
                         number_of_agents_string=number_of_agents,
                         number_of_units_string="capacity",
                         run_config={"lottery_max_iterations":10})

The argument choices is the full name of the module in which the choice class is implemented. This module must contain a class of the same name, i.e. lottery_choices in this case, be a child of opus_core class Choices (see Section 24.5.3) and have a method run(). Further arguments define the name of the capacity attribute, name of the variable that computes number of agents in each location (more about variable names in Section 24.3.1), name of the variable/attribute that determines the total number of units for each location. The argument run_config is a dictionary that contains parameters for the simulation. In this example it contains a value of how many times the households can re-decide if there is an overflow.

We run the above model:

>>> seed(1)
>>> result = hlcm2.run(specification, coefficients, households)
Running Household Location Choice Model 
                     (from urbansim.models.household_location_choice_model): 
                                            started on Wed Nov  5 18:18:58 2008
    Total number of individuals: 10
    HLCM chunk 1 out of 1.: started on Wed Nov  5 18:18:58 2008
        Number of agents in this chunk: 10
        Available capacity: 15.0 units.
        Number of unplaced agents: 0 (in 4 iterations)
    HLCM chunk 1 out of 1.: completed....................................0.0 sec
    gridcell.number_of_agents(household).................................0.0 sec
Running Household Location Choice Model 
     (from urbansim.models.household_location_choice_model): completed...0.0 sec
>>> hlcm2.plot_choice_histograms(capacity=locations.get_attribute("capacity"))

>>> households.get_attribute("location")
array([9, 3, 9, 5, 4, 3, 7, 2, 8, 1])

Now there is no overflow. Moreover, fourth and sixth locations still have free units available, since they are the most expensive places. The agents were `forced' to re-decide three times (i.e. 4 iterations in total). If the maximum number of iterations given in run_config would be reached without placing all agents, the whole model would run automatically again. It would not be very useful in this simple example, but the model is set-up for more complex situations, including sampling of locations. Therefore in a new run, agents would sample different locations which could solve the collision from the previous run.

Finally, agents that were not placed have values smaller equal zero in the ``location'' attribute.

urbansim implements several location choice models. Figure 25.1 in Section 25.4 shows a hierarchical structure of the models.