Refinement Model (RM)

Objective

The RefinementModel can be used for post-processing UrbanSim results to incorporate expert knowledge about the regional distribution of agents. It moves agents from one location to others, as specified by its inputs.

Algorithm

The model operates on agents (e.g. households, jobs) that satisfy a given condition, i.e. for which the agent_expression is True. It performs a given transaction (such as subtract or add) within locations that satisfy a given condition formulated as a location_expression. We will further call such locations active locations; agents located in them and satisfying agent_expression will be called active agents. The transactions are specified for a given year. (A transaction is defined as a collection of actions.) They are sorted by transaction_id and executed in an ascending order. If for a particular year multiple actions are given the same transaction id, they are executed in the following order: subtract, add, target, set_value, delete.

Subtract

If the given amount of agents to be subtracted is smaller or equal to the number of active agents, all active agents are removed from their locations. Otherwise, the agents to be re-located are sampled (without replacement) from the set of active agents. The relocating agents are added to a so called agents_pool. If the location_capacity_attribute is given, its values are decreased accordingly.

Add

Sample (with replacement) the given amount of active locations where active agents are placed and marked those agents for cloning. If there are no active agents, the locations are sampled from all active locations. Assemble the set of additional agents by first assigning the sampled locations to agents from the agents_pool while removing them from the pool. If the required amount is larger than the size of agents_pool, agents that were marked for cloning are added to the set of active agents. If the location_capacity_attribute is given, its values are increased accordingly.

Target

The function determines the current number of active agents and compares it to the given target amount. It then calls either the 'subtract' transaction or the 'add' transaction passing the difference between the two measures.

Set Value

This transaction is used for setting a specific value to a given attribute. All agents located in active locations get the value (given by 'amount') set in its attribute given by agent_expression (thus, agent_expression has a different meaning here).

Delete

The delete transaction is the same as the 'subtract' transaction, except that the deleted agents are not collected in agents_pool. They are physically removed from the set of agents. If the location_capacity_attribute is given, its values are decreased accordingly.

Note on Inputs

The inputs in this model are given mainly through the refinements table (see Section Data below). The location expression determines the level of geography on which the model operates - there is no carrying over to lower geographies. For example, if the location expression is defined on a zonal level, only zone identifiers are modified in the agents set; the building identifiers stay untouched.

The location_capacity_attribute is used to update the resulting capacity attribute, e.g. residential_units or job_capacity. It is not used for any capacity restrictions during the processing.

Configuration

OPUS path to model code

urbansim.models.refinement_model

It can also be invoked as a stand-alone tool, using the script urbansim/tools/do_refinement.py

Model Parameters

The configuration of the RM in the zone model system is summarized in the following table:

Element	Setting
Dataset	Refinements
Model Type	User specified, rule-based

Data

Refinements table is used by the Refinement Model. Below is a sample refinements table that demonstrates the functions of refinement model. The optional notes column explains what each refinement does.

refinement_id	year	transaction_id	action	amount	agent_dataset	agent_expression	location_expression	location_capacity_attribute	__notes_do_not_require__
1	2021	1	subtract	2	job	job.sector_id==13	building.raz_id==3		unplace 2 jobs with sector_id 13 from raz_id 3;not adjust building capacity (empty string)
2	2021	1	subtract	1	job	numpy.logical_and(job.sector_id==13, job.disaggregate(building.raz_id)==4)			unplace 1 jobs with sector_id 13 and raz_id 4 - note this is an alternative to specify location_expression as above; not adjust building capacity (empty string)
3	2021	1	add	4	job		(building.raz_id==5) * (building.disaggregate(parcel.generic_land_use_type_id)==4)	non_residential_sqft	add 4 jobs with sector_id 13 to buildings in raz_id 5 with generic_land_use_type_id 4; first place the 3 jobs unplaced above in this transaction, then clone 1 more from existing jobs with specified conditions; expand building capacity attribute non_residential_sqft by a factor of (1 + newly placed jobs / N ), N is the number of jobs in a building before this refinement action
4	2022	2	target	7	household	household.household_id>0	building.raz_id==6	residential_units	set the number of any households (household_id>0) in raz_id 6 to a target of 7; the refinement will determine whether to add or subtract households from the raz according to existing number of households in the raz; expand or shrink building capacity attribute residential units by a factor of (1 + newly placed households/N) or (1 - newly unplaced households/N) respectively
5	2023	3	add	1	household	household.persons>5	building.raz_id==6	residential_units	add 1 households with more than 5 persons to raz_id 6; if no such household already exists with specified profile, the action will fail with a warning message
6	2024	1	add	1	household	household.persons==3	building.raz_id==6		add 1 households with 3 persons to raz_id 6
7	2024	1	set_value	-1	person	person.job_id	household.refinement_id==6		set job_id to -1 for persons in households affected by refinement 6 (above)
8	2024	4	delete	-1	household	household.building_id<=0

-- LimingWang - 25 Jan 2010