Module 1, Learning the basic concepts of GeoDMS

learning objective: learning key concepts of the GeoDMS and working with expressions on attributes of the same domain

key concepts

We start with key concepts fundamental to understanding the GeoDMS. The GeoDMS structures all elements for modelling in a hierarchical structure (a tree). Therefore, all items are called tree items. Each tree item has a name. Tree items can have different roles; we will discuss them in the modules. Items that refer to data with which calculations can be made are called data items.

data item

Data items in the GeoDMS can be parameters or attributes.

Each attribute has:

• a domain unit, which defines the entity (the table). For example, we have a data set with provinces in the Netherlands. As the Netherlands has 12 provinces, the domain unit has 12 rows, one row for each province. For this domain unit, we have data about each province: for example, name, number of inhabitants, surface, and geometry. In the GeoDMS, these are different attributes for the same domain unit: province.

So, if we see a data set as a table, the number of rows (and its fixed order) is the domain unit, and the columns represent an attribute of that domain unit.

Except for attributes, a data item can also be a parameter. A parameter is a data item with a domain unit of just one row (one value). For a parameter, no domain unit has to be configured.

Data items refer to data, which can be numbers, text, booleans or coordinates. To inform the GeoDMS about the kind of data, each data item also has:

• a values unit, which defines the value type and the metric. The value type defines the type of values (string, integer, boolean), the metric, and the semantics of the values (meter, second, euro).

examples:

attribute<string> name           (province);
attribute<nr_inh> inhabitants    (province);
attribute<m2>     surface        (province);
attribute<rdc>    geometry (poly, province); //poly indicates coordinates need to be interpreted as a polygon.

structuring items

GeoDMS configurations tend to have many data items. To structure a configuration, we use structuring tree items.

Attributes with the same domain unit are often grouped together using containers or units. They can be compared to folders on your disk to group files together in a hierarchical structure.

When you open the GeoDMS GUI, you'll see in the tree view at the left, where all items are structured hierarchically, comparable to folders and files in the Windows Explorer.

examples:

unit<uint32> province: nrofrows = 12 
container region
{
   attribute<string> name             (province);
   attribute<nr_inh> inhabitants      (province);
   attribute<m2>     surface          (province);
   attribute<rdc>    geometry   (poly, province);
}

unit<uint32> province: nrofrows = 12 
{
   attribute<string> name;
   attribute<nr_inh> inhabitants;
   attribute<m2>     surface;
   attribute<rdc>    geometry (poly);
}

The first example uses a generic structuring element, the container. In the second example, the unit is the domain unit for the attribute but also has a similar structuring function. As the unit is the parent item and the domain unit of all the configured attributes, the GeoDMS derives the domain unit for these attributes from the parent item and does not have to be configured.

Some basic syntax rules:

• Attributes are configured with values units between <> characters in front of the name and domain units between $()$ characters after the name.
• Subitems are configured between ${ }$ characters.
• Tree items end with a $;$ character unless they are used as parent items.

Reading tip: for more information, see the section: configuration basics

expression

Data items refer to actual data. This data can be read from a data source or calculated with an expression. To configure an expression for an attribute, use the following syntax:

attribute<ValuesUnit> name (DomainUnit) := expression;

We already learned that attributes have a values unit, a name, and a domain unit. After the colon (:), a tree item can be configured with more properties.

The calculation rule or expression is an often configured property. The '=' sign means after the colon indicates an expression is configured; see the following examples:

attribute<nr_inh> inhabitants       (province) := sourcedata/provinces/inhabitants[nr_inh];
attribute<nr_inh> inhabitants_const (province) := const(100[nr_inh], province);

parameter<float32> some_calculation := 2f * 9f^2f + 3f * sqrt(4f);
parameter<float32> some_condition   := A == 1f ? B : C;

The expression for the inhabitants example refers to another item (sourcedata/provinces/inhabitants), for instance, where data is read from a source file. The [nr_inh] part of the expression is a short notation of the value function, used to convert the source attribute to the requested value's unit: nr_inh.

The expression for the inhabitants_const example results in a value of 100 for each value of the attribute: inhabitants_const in the domain unit provincie.

The expression for the first parameter some_calculation shows some basic operators and arithmetic functions. The f character after each number is shorthand for value type float32. See the value type table for all shorthand notations.

It is necessary to configure the value type of each numeric value; otherwise, the default value type uint32 is assumed for values without a decimal separator and float64 with a decimal separator. In the expression of the second parameter some_condition, a condition is used in an $iif$ operator, with the advised syntax $?$ and $:$. Before the $?$, a condition is configured to determine whether the outcome is true or false. The $?$ says then this, and the$ :$ says and else this.

Reading tip: for an overview of all operators and functions, see the section operators and functions

try it yourself!

In this exercise, you will learn to make calculations with the GeoDMS on attributes of the same domain:

• Download the project here and unzip the downloaded project file to a projDir like C:/prj/GeoDMSAcadamy.

• Open the file exercise.dms (in the GeoDMS_Academy\basics_single_domain\cfg subfolder of your downloaded project) with a text editor.

• Note that at this point you don't have to understand every aspect of the .dms file, for instance, reading of SourceData will be explained in Module 2, Loading and storing data sources.

• Try to create the following attributes in the Results container:

  • the number of capitals per province (always the value 1 for each province);
  • a province code, the first two characters of each province name, in uppercases (tip: look at the String functions);
  • a true or false value indicating if a province has more than 1 million inhabitants;
  • to find out which province has the largest population density (tip: use the Geometric function: area).

• Start the GeoDMS GUI, open your configuration and make a table of all the new attributes.

First, try to figure it out yourself. The configuration with the results is also available in the downloaded project; just open the result.dms file with the GeoDMS GUI in the cfg subfolder of your downloaded project.

• In case you are familiar with Python, see GeoDMS through Python: Module 1.

---

Go to previous module: Module 0, Install GeoDMS GUI and setup a configuration

Go to next module: Module 1a, Learning the basic concepts of GeoDMS, naming items and namespaces