AllocationModel Class

The AllocationModel allocates given quantity for a dataset according to weights while meeting capacity restrictions (see Section 14.1.3).

The run() method takes the following arguments:

dataset

- an object of class Dataset for which the allocation is done.

outcome_attribute

- name of the resulting attribute.

weight_attribute

- an attribute/variable/expression of dataset which determines weights for the allocation.

control_totals

- an object of class Dataset holding data with the total amount of quantity to be allocated.

current_year

- integer value used for filtering out control totals for the current year.

control_total_attribute

- name of the attribute in control_totals that specifies the total amount to be allocated. If it is not given, the value of outcome_attribute is taken.

year_attribute

- name of the attribute in control_totals on which the filtering of the current year is done. Default is 'year'.

capacity_attribute

- name of the attribute/variable/expression in dataset specifying capacity for each member. Default is None which means there are no capacity restrictions.

add_quantity

- if True and the outcome_attribute exists in dataset, the resulting values are added to the current values of outcome_attribute. Default is False.

dataset_pool

- pool of datasets used in the computation. Default is None.

In addition to the year_attribute and control_total_attribute, the control_totals dataset can contain other attributes that must be known to the dataset (such as a geography), here called 'common' attributes. For each row of the control_totals that matches the current year, the total amount is distributed among members of dataset that have the same values of all common attributes as the row. The distribution is done using the given weights. If the capacity_attribute is given, the algorithm removes any allocations that exceeds the capacity and re-distributes it among remaining members. The resulting values are appended to dataset as outcome_attribute which is marked as primary. If add_quantity is True, the resulting values are added to the current values of outcome_attribute if it exists. The outcome_attribute is then flushed to cache and the values are returned.