Overlay

Relational functions overlay

syntax

• overlay(a, domainunit, container)
• overlay32(a, domainunit, container)

definition

• overlay(a, domainunit, container) results in a new uint16 domain unit
• overlay32(a, domainunit, container) results in a new uint32 domain unit

The first argument a contains the names of the source attributes. These attributes need to be configured in the container argument. Argument domainunit is the domain unit of the source and the resulting attributes.

The overlay(32) function results in the following subitems:

• a subitem UnionData is generated for this domain unit, containing different index numbers of this domain unit for each unique combination of the occurring values in the source attributes.
• subitems for each name of the source attributes from the argument a. These subitems contain relations to the domain unit of the attributes configured in the container argument.

description

The overlay(32) function is for example used to create unique regions in the discrete allocation function. In the GeoDMS the unique function is used to find the unique values of one attribute, the overlay32 function can be used for multiple attributes.

applies to

• attribute a with string value type
• domain unit domainunit with value type from group CanBeDomainUnit
• container container with as subitems the attributes to be overlayed. For each entry in the argument a an attribute with the same name needs to be configured with a uint8 or uint16 value type and with the domainunit argument as their domain unit.

conditions

The domain units of all attributes to be overlayed need to match. Null values are not allowed in the source attributes.

since version

5.51

performance

O(n * k) where n = number of elements in the domain and k = number of overlay attributes. Single pass identifying unique combinations. Memory usage depends on number of unique combinations found.

example

unit<uint8> OverlayRegios: nrofrows = 2
{
   attribute<string> names: ['NoordZuid', 'OostWest'];
}
container OverlayGrids
{
  attribute<uint8> NoordZuid (GridDomain): StorageName = "%projdir%/data/overlayNZ.tif";
  attribute<uint8> OostWest  (GridDomain): StorageName = "%projdir%/data/overlayOW.tif";
}

unit<uint16> NoordZuidOostWest := overlay(OverlayRegios/names, GridDomain, OverlayGrids);

NoordZuid:

0	0	0	0	0
0	0	0	0	0
1	1	1	1	1
1	1	1	1	1
1	1	1	1	1

GridDomain, nr of rows = 5, nr of cols = 5

OostWest:

0	0	0	1	1
0	0	0	1	1
0	0	0	1	1
0	0	0	1	1
0	0	0	1	1

GridDomain, nr of rows = 5, nr of cols = 5

NoordZuidOostWest/UnionData:

0	0	0	2	2
0	0	0	2	2
1	1	1	3	3
1	1	1	3	3
1	1	1	3	3

GridDomain, nr of rows = 5, nr of cols = 5

see also

• full configuration example: Overlay versus Combine data
• overlay32
• overlay64