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)) is a_rel again.
  • 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