Location Choice Model

The LocationChoiceModel class implemented in urbansim is a special case of the ChoiceModel class (see Section 8.4.4 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 load this dataset using the class GridcellDataset which takes the same arguments as HouseholdDataset:

>>> from urbansim.datasets.gridcell_dataset import GridcellDataset
>>> locations = GridcellDataset(in_storage = storage,
        in_table_name = 'locations', id_name='location')

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_creator import \
                               HouseholdLocationChoiceModelCreator
>>> hlcm = HouseholdLocationChoiceModelCreator().get_model(
                               location_set = locations,
                               sampler=None,
                               compute_capacity_flag=False)

The household location choice model (HLCM) creator returns an instance of class AgentLocationChoiceModel with some useful default settings for models where agents are households and locations are gridcells. 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. The optional argument debuglevel controls the amount of outputs during the computation.

>>> seed(1)
>>> result = hlcm.run(specification, coefficients, agent_set=households,
                                                            debuglevel=1)
Running Household Location Choice Model
                        (from urbansim.models.agent_location_choice_model):
                                         started on Mon Mar 19 20:04:26 2007
    Total number of individuals: 10
    HLCM chunk 1 out of 1.: started on Mon Mar 19 20:04:26 2007
        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.agent_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([7, 2, 5, 5, 5, 7, 7, 2, 5, 2])

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 second, fifth and seventh location than there are units available (which corresponds to the fact that those are the most 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:

>>> from opus_core.resources import Resources
>>> number_of_agents = "gridcell.number_of_agents(household)"
>>> hlcm2 = HouseholdLocationChoiceModelCreator().get_model(
                         location_set = locations,
                         sampler=None,
                         choices="urbansim.lottery_choices",
                         compute_capacity_flag=True,
                         run_config=Resources({
                                "capacity_string":"capacity",
                                "number_of_agents_string":number_of_agents,
                                "number_of_units_string":"capacity",
                                "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 7.5.3) and have a method run(). The argument run_config is expected to be of type Resources and contains parameters for the simulation. These are in our example the name of the capacity attribute, name of the variable that computes number of agents in each location (more about variable names in Section 7.3.1), name of the variable/attribute that determines the total number of units for each location and 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.agent_location_choice_model):
                                        started on Mon Mar 19 21:09:28 2007
    Total number of individuals: 10
    HLCM chunk 1 out of 1.: started on Mon Mar 19 21:09:28 2007
        Number of agents in this chunk: 10
        Number of unplaced agents: 0 (in 4 iterations)
    HLCM chunk 1 out of 1.: completed....................................0.4 sec
    gridcell.number_of_agents(household).................................0.0 sec
Running Household Location Choice Model
        (from urbansim.models.agent_location_choice_model): completed...0.4 sec
>>> hlcm2.plot_choice_histograms(capacity=locations.get_attribute("capacity"))

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

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 and their creators. Figure 8.1 in Section 8.4 shows the hierarchical structure of models.