Union_data - ObjectVision/GeoDMS GitHub Wiki

Relational functions union_data

• union_data(domain unit, a, b, .. n)

union_data(domain unit, a, b, .. n) results in a new attribute with as domain unit the first argument: domainunit.

The resulting attribute contains the values of the data items a, b, .., n.

The first argument domainunit, is often made with the union_unit function.

The union_data function results in an attribute with as values unit the values units of data items a, b, ..n and as domain unit the first argument of the function (domainunit). In other words, it appends b to a and then c to a and b, etc.

union_data(newdomain, att_old_domain) can be used to convert attributes from a source to a target domain unit.

union_data is a concatenating relabel. The only requirement is that the number of elements of domainunit equals the sum of the numbers of elements of the domain units of a, b, .., n; nothing forces those domain units to have any relation to domainunit, which is what makes the conversion use above possible.

A consequence is that swapping or repeating arguments of equal size is not an error. To still catch the most common form of that mistake, the GeoDMS looks at how domainunit itself was made. In two cases its calculation rule states the intended division into parts, and every data item is then checked against the part it lands in. A mismatch is reported as a warning that names the item being calculated; the calculation itself continues, and no data is read to perform the check. Only the first mismatching data item is reported, with a count of the others, and the warning states the finding rather than the remedy: messages are cut off at 256 characters, and two full item names of a deeply nested configuration already take half of that.

domainunit made with union_unit. When domainunit := union_unit(u₁, .., uₖ) and the number of data items equals k, the domain unit of the i-th data item must be uᵢ:

unit<uint32> HollandCity := union_unit(NHCity, ZHCity);

attribute<string> right (HollandCity) := union_data(HollandCity, NHCity/name, ZHCity/name);
attribute<string> wrong (HollandCity) := union_data(HollandCity, NHCity/name, NHCity/name);

Both are accepted when NHCity and ZHCity have the same number of elements, but the second one reports:

[[/City/wrong]] union_data: argument 3 has domain [[/NHCity]], but part 2 of the result domain is [[/ZHCity]].

domainunit made with combine or combine_unit_uint8_16_32_64. These enumerate their arguments with the first varying slowest, so combine(a, b) falls apart into as many consecutive blocks as a has elements, each running over b. When domainunit := combine(a, b) and two or more data items are given, the domain unit of every data item must therefore be b. Writing the factors in the wrong order is the usual mistake:

unit<uint32> pointset := combine(link, bool);
attribute<rdc> point (pointset) := union_data(pointset, link/from, link/to);

[[/net/point]] union_data: argument 2 has domain [[/net/link]], but the result domain splits into blocks of [[/bool]]; swap the factors of its combine.

Swapping the factors is what that advice means here: combine(bool, link) splits into two blocks that each run over link, which is what the two arguments are.

combine_unit_uint8_16_32_64 is the better choice in this idiom anyway, since the first_rel and second_rel subitems that combine adds are not used here.

What is not checked. A single data item is a plain relabel and is never judged. Neither are a domainunit whose calculation rule is neither of the two forms above, a union_unit whose number of arguments differs from the number of data items, a combine of three or more factors, and any data item whose domain unit is not (yet) known. A parameter fits any part, so filling a domain unit with parameters — the = 'union_data(' + asItemList(..) + ')' idiom — never warns.

• unit domainunit with value type from the group CanBeDomainUnit
• data items a, b, ... n with Numeric, Point, uint2, uint4, bool or string value type

• The values unit of data items a, b, ... n must match.
• The number of elements of domainunit must equal the sum of the numbers of elements of the domain units of a, b, ... n; this is verified when the result is calculated.
• When domainunit is made with union_unit, combine or combine_unit_uint8_16_32_64, the domain units of a, b, ... n should match the parts that decomposition states, see checked decompositions above; a mismatch is reported as a warning.

O(n₁ + n₂ + ... + nₖ) where nᵢ = number of elements in data item i. Single pass copying data from each source.

unit<uint32> HollandCity := union_unit(NHCity, ZHCity)
{
   attribute<string> name := union_data(., NHCity/name, ZHCity/name);
}

domain HollandCity, nr of rows = 8

domain NHCity, nr of rows = 3

domain ZHCity, nr of rows = 5

• union_unit
• ordered_union_data - the variant with which is stated that all unioned values are non-decreasing
• combine and combine_unit_uint8_16_32_64 - the other way of making a domain unit whose decomposition union_data checks