Combine_data
Relational functions combine_data
syntax
- combine_data (combined_domain, a_rel, b_rel, …)
definition
combine_data(combined_domain, a_rel, b_rel, …) results in an Attribute with Index numbers to the combined_domain Argument, combining the values of the data items a_rel, b_rel and further: one relation per factor of combined_domain.
description
The first argument combined_domain is usually made with a Combine function.
The combine_data function results in an attribute with an index to combined_domain for each element of the domain of a_rel, b_rel and further, with as Values unit the first Argument of the function (combined_domain) and as Domain unit the domain unit of the relations.
The last relation varies fastest, as in the numbering of Combine: for combined_domain := combine(A, B, C), relations with the index numbers a, b and c give ((a × #B) + b) × #C + c. combine_rel and first_rel(x_rel) to sixteenth_rel(x_rel) compute the relations back.
combine_data knows the factors of the combine that made combined_domain, and uses them:
- Each relation is checked against the factor it stands for: its values unit must have the value type, metric, projection and spatial reference of that factor. A literal, such as the 0 in
combine_data(X, 0, id(P)), passes. Which factor a relation stands for when combines are nested is described under combining multiple indices below. - That check compares value types, not which unit it is. Two factors of the same value type, such as two uint32 domains without a metric, can still be swapped without notice, so keep the relations in the order of the factors.
- The index numbers are taken within the ranges of the factors, so
first_rel(combine_data(X, a_rel, b_rel))isa_relagain. - A null in any relation gives null, and so does a value outside the range of its factor.
A relation of another value type than its factor is an error, and so are relations that do not cover the factors exactly; the error is reported at the item that calls combine_data.
When combined_domain is not made by a combine function, for instance a unit read from a storage, combine_data computes the index from the values units of the relations, without a check.
applies to
- Unit combined_domain with value type from the group CanBeDomainUnit.
- attributes a_rel, b_rel, … with value type from group CanBeDomainUnit.
conditions
- The domain units of the relations must match (or be Void, as that of a Parameter).
- One relation per factor of combined_domain. A factor that is itself a combine may instead get one relation per factor of its own, and a relation to a combine of consecutive factors may take the place of those factors, see below.
- The values unit of each relation must match the factor, or the factors, that it stands for in the combine with which combined_domain has been defined.
since version
7.131; a relation to a combine in the place of the factors of that combine since 20.24.2.
performance
O(n) where n = number of elements in the domain of the relations. Single pass computing the combined index from the input relations.
combining multiple indices
combine_data takes one relation per factor:
unit<uint32> ABC := combine_unit(A, B, C);
attribute<ABC> ABC_rel (domain) := combine_data(ABC, domain/A_rel, domain/B_rel, domain/C_rel);
A combine of combines takes one relation per factor, or one per factor of the inner combines; both give the same result:
unit<uint32> BC := combine_unit(B, C);
unit<uint32> A_BC := combine_unit(A, BC);
attribute<A_BC> A_BC_rel (domain) := combine_data(A_BC, domain/A_rel, combine_data(BC, domain/B_rel, domain/C_rel));
attribute<A_BC> same_rel (domain) := combine_data(A_BC, domain/A_rel, domain/B_rel, domain/C_rel);
A relation to a combine may also take the place of the factors of that combine, on either side, since (AB)C, A(BC) and ABC number their elements alike:
unit<uint32> AB := combine_unit(A, B);
unit<uint32> ABC := combine_unit(A, B, C);
attribute<AB> AB_rel (domain) := combine_data(AB, domain/A_rel, domain/B_rel);
attribute<ABC> ABC_rel (domain) := combine_data(ABC, AB_rel, domain/C_rel); // the same as combine_data(ABC, domain/A_rel, domain/B_rel, domain/C_rel)
attribute<A_BC> A_BC_from_AB (domain) := combine_data(A_BC, AB_rel, domain/C_rel); // (AB)C for A(BC)
combine_data pairs the factors of combined_domain with the values units of the relations, from the left. Two units that are the same are a pair. Where they are not, a combine on either side stands for its own factors. Two units that are neither the same nor a combine must match as values, as described above. The relations must cover the factors exactly: a relation to combine(A, B, C) for a combined_domain of A and B alone is an error, and so is a relation to combine(A, D) in the place of A and B when D does not have as many elements as B.
Relations that do not cover the factors stop with an error such as is a combine of 3 factors, but 2 relations were given, followed by the factor or the relation that is left without a partner.
A one-dimensional index into a grid factor, such as row × number of columns + column in a uint32 relation, does not stand for the grid: the grid is a two-dimensional unit with its own value type and projection. Either give the relation to the grid itself, or combine with a one-dimensional unit of as many elements as the grid, such as range(uint32, 0, #Grid), and give the index to that.
example
unit<uint32> NHCityYear := combine(NHCity, YearDomain);
attribute<NHCityYear> NHCityYear_rel (Adomain) := combine_data(NHCityYear, NHCity_rel, YearDomain_rel);
| NHCity_rel | YearDomain_rel | NHCity | Year | NHCityYear_rel |
|---|---|---|---|---|
| 0 | 0 | Amsterdam | 1995 | 0 |
| 0 | 1 | Amsterdam | 2005 | 1 |
| 1 | 1 | Haarlem | 2005 | 3 |
| 2 | 0 | Alkmaar | 1995 | 4 |
| 2 | 1 | Alkmaar | 2005 | 5 |
ADomain, nr of rows = 5
| nr_1 | nr_2 | NHCityName | Year |
|---|---|---|---|
| 0 | 0 | Amsterdam | 1995 |
| 0 | 1 | Amsterdam | 2005 |
| 1 | 0 | Haarlem | 1995 |
| 1 | 1 | Haarlem | 2005 |
| 2 | 0 | Alkmaar | 1995 |
| 2 | 1 | Alkmaar | 2005 |
domain NHCityYear, nr of rows = 6
| NHCity/name |
|---|
| Amsterdam |
| Haarlem |
| Alkmaar |
domain NHCity, nr of rows = 3
| YearDomain/Year |
|---|
| 1995 |
| 2005 |
Yeardomain, nr of rows = 2
combine_data has the last factor varying fastest, here YearDomain, as the table of NHCityYear shows.
see also
- combine_rel, for the relations back to the factors
- full configuration example: Overlay versus Combine data