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

introduction

In Module 0 you installed the GeoDMS and opened a configuration file. Now it is time to understand what is actually in such a file and how to write your own calculations.

A GeoDMS configuration file describes your entire model in plain text: which data to read, how to calculate results from it, and how to visualise those results. Everything is written as tree items in a hierarchical structure. When you open a configuration file in the GUI, this hierarchy appears in the tree view on the left.

This module introduces the three building blocks that appear in every GeoDMS configuration:

  • data items: the items that hold actual values (numbers, strings, coordinates)
  • structuring items: containers and units that organise data items into a logical tree
  • expressions: the calculation rules that derive new values from existing ones

Modules 1a through 1d build on these concepts and go deeper into naming conventions, units, multi-domain calculations, and visualisation. You do not need to read them in order, but if this is your first time with the GeoDMS, working through them front to back is recommended.

data items

Data items in the GeoDMS are either attributes or parameters.

An attribute describes a property of a set of entities. Think of a table: the rows represent the entities, and each column is an attribute. Each attribute therefore has:

  • a domain unit: the entity set (the table). For example, a dataset of the 12 Dutch provinces. This domain unit defines how many rows there are and their order. Each attribute of this domain unit describes a property of each province — its name, population, surface area, or geometry.
  • a values unit: defines how to interpret the values of the attribute — the value type (e.g. integer, string, coordinates) and optionally a metric (e.g. metres, euros).

A parameter is a data item with exactly one value — in effect a domain unit of one row. No domain unit needs to be configured for a parameter.

The following example shows four attributes for a province domain unit. Note that nr_inh and m2 are user-defined values units (covered in detail in Module 1b):

attribute<string>  name         (province);
attribute<nr_inh>  inhabitants  (province);
attribute<m2>      surface      (province);
attribute<rdc>     geometry     (poly, province);

The keyword poly in the last line tells the GeoDMS that the coordinates in geometry should be interpreted as polygon boundaries.

structuring items

GeoDMS configurations quickly grow to include many data items. To keep them organised, the GeoDMS uses containers and units as structuring items — comparable to folders on disk.

When you open the GeoDMS GUI, the tree view on the left shows all items in this hierarchical structure, much like Windows Explorer.

Attributes that belong to the same domain unit are typically grouped together. There are two common patterns:

// Pattern 1: using a container as parent
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);
}

// Pattern 2: using the unit itself as parent
unit<uint32> province : nrofrows = 12
{
   attribute<string>  name;
   attribute<nr_inh>  inhabitants;
   attribute<m2>      surface;
   attribute<rdc>     geometry     (poly);
}

In pattern 2, the province unit is the parent item of the attributes. Because it is also the domain unit, the GeoDMS derives the domain unit for each attribute from the parent and it does not need to be specified again.

Some basic syntax rules:

  • Values units are written between <> in front of the item name.
  • Domain units are written between () after the item name.
  • Subitems are configured between {}.
  • Tree items end with ; unless they act as a parent item (i.e. they have subitems).

Reading tip: for more information, see configuration basics

expressions

Data items refer to actual data. This data can be read from a data source or calculated with an expression. An expression is configured after :=:

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

The := notation indicates that an expression (a calculation rule) follows. A few examples:

// Reading data from a source, with unit conversion:
attribute<nr_inh> inhabitants (province) := sourcedata/provinces/inhabitants[nr_inh];

// A constant value for each element in the domain:
attribute<nr_inh> inhabitants_const (province) := const(100[nr_inh], province);

// A parameter: a single calculated value:
parameter<float32> population_density_max := max(inhabitants / surface);

In the first example, [nr_inh] is a shorthand for the value function — it converts the source attribute to the values unit nr_inh. This kind of unit conversion is explained in detail in Module 1b.

In the second example, const(100[nr_inh], province) produces the value 100 nr_inh for every province.

Arithmetic and conditions

The GeoDMS supports standard arithmetic operators and a conditional (if-then-else) expression using ? and ::

attribute<float32> area_km2          (province) := surface_m2 / 1000000f;
attribute<bool>    is_large_province (province) := inhabitants > 1000000[nr_inh];
attribute<nr_inh>  capped_pop        (province) := inhabitants > 1000000[nr_inh] ? 1000000[nr_inh] : inhabitants;

In the conditional expression, the condition before ? is evaluated. If true, the result is the value after ?; otherwise the value after :.

Note the f suffix on numeric literals: 1000000f means the value is of type float32. Without a suffix, the GeoDMS assumes uint32 for values without a decimal separator and float64 for values with one. It is good practice to always specify the value type explicitly. See the value type page for all available types and shorthand notations.

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

try it yourself!

In this exercise, you will make calculations on attributes of the same domain.

  • Download the project here and unzip it to a project folder such as C:/prj/GeoDMSAcademy.
  • Open exercise.dms (in the GeoDMS_Academy/basics_single_domain/cfg subfolder) in a text editor.
  • Note that you do not need to understand how the source data is read yet — this is covered in Module 2.

  • In the Results container, add the following attributes:

    1. The number of capitals per province — always the value 1 for each province.
    2. A province code: the first two characters of each province name, in uppercase. Tip: see string functions.
    3. A boolean indicating whether a province has more than 1 million inhabitants.
    4. The population density per province in inhabitants per km². Tip: use the area function.
  • Open the GeoDMS GUI, load your configuration and make a table view of all the new attributes to verify your results.

First try to figure it out yourself. The reference solution is available in result.dms in the same cfg subfolder.

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

Table of contents