PreferentialAttachment

Applies an attachment to the sum of a group of records that share equal values in the columns specified by erode_by_columns. It is applied incrementally in to steps to groups of records that share same values in the columns specified by span_columns. In first step attachment is applied to the preferred records that have matching preferred_values in the preferred_column. Then attachment applies to the non-matched records. In both steps once the attachment is applied, the result is proportionally allocated to all matching (preferred or non-preferred) records.

Structure

{
    "_schema": "PreferentialAttachment_1.0",
    "attachment": 1000,
    "span_columns": ["Time", "OccurrenceKey"],
    "erode_by_columns": ["Time", "OccurrenceKey"],
    "currency":"GBP",
    "preferred_column": ["Region"],
    "preferred_values": ["NAM"],
    "invert": false
}

Parameters

Parameter Name	Required	Type	Description
attachment	Yes	double	The attachment value in currency units. Cannot be negative.
span_columns	No	string list	List of column names. Adjacent records with the same values in the provided columns will share the same eroding attachment. Supported columns: OccurrenceKey, Time. If left empty, all records share the same attachment.
erode_by_columns	No	string list	List of column names. Specifies the grouping of records the attachment will apply to. Supported columns: OccurrenceKey, Time. Always implicitly contains the values in span_columns.
currency	No	string	The currency in which attachment is defined.
preferred_column	No	string	Name of the metadata field that stores preferred values (OccurrenceKey, Time and Trial columns are not allowed).
preferred_values	No	string list	List of values. If record has any of the listed values in preferred column, such record is treated as preferred.
invert	No	bool	Specifies if the preferential order should be inverted.

Behaviour

Records given to preferential attachment have their attachment applied according to how they are grouped by span_columns and erode_by_columns, and what value records have in the preferred_column. All adjacent records with matching values in the columns specified by span_columns are placed within a span group. All adjacent records with matching values in the columns specified by erode_by_columns within a span group are further placed in an erode group. Records in erode group are also separated into preferred and non preferred subgroups. Inside erode group attachment is applied to the preferred records first and to the non-preferred records after that. Order of the preferred and non-preferred records within erode group is not important. They may or may not be adjacent. Preferred column can be only one of the metadata columns.

Within each erode group, the attachment is applied first to the sum of the preferred records’ Value fields (sum) with the function new_sum = min(sum + attachment, 0). This value is then proportionally allocated to the Value field of each preferred record within the group with the function record.value = new_sum / sum. If sum is 0, then each records’ Value field is instead set to 0. In either case, the attachment is eroded with the function attachment = max(attachment + sum, 0). Then same calculations are applied to the non-preferred records in the erode group.

Within each span group, the value of the attachment is reset to the original attachment specified in the arguments.