Module 1b, Learning the basic concepts of GeoDMS, understanding units

learning objective: understanding units and how to use them in the GeoDMS

introduction

In the previous module, we learned that every data item has a values unit and, if it is an attribute, also a domain unit. These are not two separate worlds — they are the same concept playing two different roles. This module explains both roles in detail.

We use a running example throughout: an attribute describing the surface area of each province in the Netherlands.

values unit

A values unit defines how to interpret the values of a data item. For our surface area attribute, the values unit is square metres (or a similar unit such as hectares or km²). Without the values unit, a number like 5100 is meaningless — with the values unit it becomes 5100 m².

A values unit has two components:

1. Value type (required)

The value type describes the kind of data: is it an integer, a floating-point number, a string, a boolean, or a coordinate pair? For numeric types, it also specifies whether the number is signed or unsigned, and how many bits are used to store each value.

Examples of numeric value types: uint8, uint32, int32, float32, float64. See value types for the full list.

2. Metric (optional)

The metric captures the physical unit of a value — think of units from physics class: metres, seconds, euros. Starting from a set of base units, derived units are built by combining them:

// Define base units:
unit<float32> meter   := baseunit('m', float32);
unit<float32> second  := baseunit('s', float32);

// Derive units from base units:
unit<float32> m2      := meter * meter;
unit<float32> km      := 1000.0 * meter;
unit<float32> km_per_h := km / second * 3600.0;

With these definitions, the surface area attribute would be:

attribute<m2> surface (province);

And calculating population density becomes unit-safe:

unit<float32> inh_per_m2 := nr_inhabitants / m2;

attribute<inh_per_m2> pop_density (province) := inhabitants / surface;

The GeoDMS uses the metric to check your calculation logic. If you accidentally divide inhabitants by meter instead of m2, the GeoDMS can detect that the resulting unit does not match the declared values unit and will give an error. This is one of the key advantages of the metric system.

Range

The values unit also implicitly or explicitly defines the range of allowed values. Each value type has a default minimum and maximum (see the value type table). You can explicitly narrow this range — for example, surface area cannot be negative:

unit<float32> m2 := baseunit('m2', float32);  // default range
unit<float32> m2_positive := range(m2, 0.0, max_value(float32));  // non-negative

Configuring a range allows the GeoDMS to check for model inconsistencies at runtime.

Reading tip: for more information and examples, see values unit

domain unit

A domain unit defines the set of entities to which an attribute belongs: how many there are and in what order. For our example, the domain unit is province — a set of 12 elements, one per Dutch province.

The domain unit determines the number of rows in the attribute. This is usually configured explicitly using the nrofrows property, or derived from a data source:

// Explicitly configured:
unit<uint32> province : nrofrows = 12;

// Derived from a data source (covered in Module 2):
unit<uint32> province 
: StorageName = "%ProjDir%/data/provinces.shp"
, StorageType = "gdal.vect"
, StorageReadOnly = "True";

Not every value type can serve as a domain unit — only types that can index elements (typically unsigned integers and some spatial types). See the column CanBeDomainUnit in the value type table.

Reading tip: for more information and examples, see domain unit

try it yourself!

In this exercise, you will configure units and use them in expressions.

  • Download the project here and unzip it to a project folder such as C:/prj/GeoDMSAcademy.
  • Open exercise.dms (in the GeoDMS_Academy/basics_understanding_units/cfg subfolder) in a text editor. The configuration already includes an OSM highway dataset for Amsterdam.
  • Configure the units and attributes needed to calculate the travel time along each highway segment, assuming a travel speed of 100 km/h. Tip: calculate the road length using the arc_length function.

Note: the province shapefile in the data subfolder can also be used to configure a domain unit based on a data source — but reading shapefiles is covered in Module 2. If you want to try this now, take a look at ESRI Shapefile for a hint; otherwise skip this part and come back after completing Module 2.

Try to solve the travel time exercise yourself first. The reference solution is in result.dms in the same cfg subfolder.

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

Go to next module: Module 1c, Learning the basic concepts of GeoDMS, calculations over multiple domains