The Run Method

Input:

year

- an integer indicating the simulated year.

household_set

- an instance of Dataset that contains some specific attributes (see description of the algorithm bellow).

control_totals

- an instance of ControlTotalDataset initiated for the dataset ``household''. It must have at least attributes ``total_number_of_households'' and ``year'' which give the control totals for specific years. Optionally, it can contain other attributes whose combinations determine groups for the control totals. These are e.g. ``age_of_head'', ``income'', ``persons'', ``cars'', ``children'', ``race_id'', ``workers''. Each value of such attribute is the corresponding group index (starting from zero) for this characteristics from the argument characteristics (see below). The unique identifier of this dataset should consist of all attributes but the ``total_number_of_households'' (for details see Section ``annual_household_control_totals'' in 9.11.1).

characteristics

- an instance of class HouseholdCharacteristicDataset that specifies grouping of characteristics. It must have three attributes: ``characteristic'', ``min'' and ``max''. Values of the ``characteristic'' attribute should match the names of the existing optional attributes of control_totals, but they can be also other names. ``min'' and ``max'' determine group boundaries for each characteristics (for details see Section ``household_characteristics_for_ht'' in 9.11.4). If there is a characteristics missing that is contained in control_totals, the grouping is assumed to be $[0,1), [1,2), [2,3)$, etc.

resources

- additional Resources for controlling the simulation run. The argument is not used in this version of the model.

Algorithm: 
The optional attributes in control_totals are called 'marginal' characteristics, the remaining characteristics from the dataset characteristics are called 'scaled' characteristics. The given household_set must contain the union of the marginal and scaled characteristics as its primary attributes.

The combination of all marginal characteristics and the grouping within each of them determines distinct marginal bins. The method iterates over those bins. In each iteration the number of households is determined whose properties match the characteristics of the bin. This number is compared to the control total for this bin. If the difference $d$ is positive, new households are created, if it is negative, households are removed, if it is zero, nothing is done.

When creating households, the method samples $d$ bins from the scaled characteristics bins that this marginal bin applies to. These represent categories to which the $d$ new households belong to. For each new household the value of each characteristics is randomly sampled between the category minimum and maximum (as an integer value). There are two exceptions: characteristics ``age_of_head'' is never smaller than 15. Sampled values of the characteristics ``income'' are rounded to the nearest 10.

To remove households, first unplaced households from the bin are removed. If the number $n_u$ of those unplaced households is larger than $d$, only $d$ households are randomly sampled for deletion. If $n_u$ is smaller than $d$, then $d-n_u$ households from the set of placed households of that bin are randomly sampled and deleted. Households are considered as unplaced if their attribute given by the class property location_id_name (which is by default ``grid_id'') is smaller equal zero.

Output: 
The method returns the total difference between the sizes of the household dataset after and before the model run. Thus, a positive value means that in total there were more households added than removed, a negative value means the opposite.