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.

Since GeoDMS 20.24.0 combine_data is an operator that 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)) is a_rel again.
• A null in any relation gives null, and so does a value outside the range of its factor.

Until then combine_data was a function in the prelude that computed the index from the values units of its arguments alone, without looking at the factors of combined_domain. A relation of another value type than its factor was accepted, and so was a number of relations that differed from the number of factors; both now stop with an error at the item that calls combine_data. A value outside the range of its factor gave the index of another combination, and now gives null.

When combined_domain is not made by a combine function, for instance a unit read from a storage, combine_data still computes as before, 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

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

Since GeoDMS 20.24.0 combine_data takes one relation per factor directly:

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);

Since GeoDMS 20.24.2 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.

In 20.24.0 and 20.24.1 only one relation per factor was accepted, or one per factor after unfolding the combines among the factors, and a relation to a combine of some of the factors stopped with is a combine of 3 factors, but 2 relations were given. The prelude function before 20.24.0 computed the same index from it without a check.

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

Until October 2026 the column NHCityYear_rel of the first table read 0, 3, 4, 2, 5, a numbering in which the first factor varies fastest. combine_data has the last factor varying fastest, as the table of NHCityYear shows.

see also

• combine_rel, for the relations back to the factors
• full configuration example: Overlay versus Combine data