Module 1a, Learning the basic concepts of GeoDMS, naming items and namespaces

learning objective: learning how to name items in the GeoDMS and understanding namespaces

modelling elements

In programming languages, variables are often named A, B, C or i. In a spreadsheet, cells are addressed by row and column, such as A1. This is fine for small models, but as models grow, abstract names make them hard to understand, maintain and share.

In the GeoDMS, which focuses on transparent and reproducible modelling, we address this in two ways:

  • meaningful tree item names
  • using a namespace structure

tree item names

Use clear, meaningful and unambiguous names for tree items. An attribute with the number of inhabitants of a province should be named inhabitants or nr_inhabitants, not i or v.

The following syntax rules apply to all tree item names:

  1. May only contain (alpha)numeric characters and underscores (a-z, A-Z, 0-9, _).
  2. May not start with a digit.

Examples of invalid and valid names:

// invalid names:
attribute<float32> 1st_value    (province);  // starts with digit
attribute<float32> surface area (province);  // contains space
attribute<float32> surface-area (province);  // contains hyphen

// valid names:
attribute<float32> first_value  (province);
attribute<float32> surface_area (province);
attribute<float32> surfaceArea  (province);

The syntax rules above are required — violations cause errors. Most other naming guidance is a convention.

Reading tip: for more information, see naming conventions

namespace

An attribute name like nr_inhabitants always needs context to be meaningful. Does it apply to a country or a region? For which year? For the actual situation or a modelled scenario? Space, time, and scenario are potential modelling dimensions that may need to be reflected in the full name.

The full name of a tree item is the item’s own name combined with the names of all its parent items. This full name should contain all the context needed to interpret the item unambiguously.

The namespace concept relates to this idea of context. A set of parent items defines a specific context. Within that context, names need to be clear and unique, but should not repeat information already captured by the parents.

This matters when items refer to each other. Within the same context (subitems of the same parent), it is sufficient to use the item name alone. If an item in one context refers to an item in a different context, you need to include the relevant part of the path.

Reading tip: for more information on how items refer to each other, see namespace

try it yourself!

In this exercise, you will learn how to name tree items correctly and how to resolve reference errors.

  • Download the project here and unzip it to a project folder such as C:/prj/GeoDMSAcademy.
  • Open exercise.dms (in the GeoDMS_Academy/basics_naming_items/cfg subfolder) in both a text editor (to read and edit the configuration) and the GeoDMS GUI (to see the results and errors).
  • In the GeoDMS GUI, open the items under Results/province. You will notice that some items appear in red. Red items indicate a configuration error — usually that an item refers to another item that cannot be found. Hover over a red item, check the Detail Pages on the right, or look in the event log at the bottom of the GUI for the error message.

Reading tip: reading error messages and debugging systematically is covered in depth in Module 1e, Learning the basic concepts of GeoDMS, reading errors and debugging

The errors are intentional. You are asked to fix the following two issues:

  1. Naming errors: some tree item names in the configuration do not follow the naming rules. Identify and correct them.
  2. Reference errors: some items refer to other items using incorrect paths or names. Resolve the red items by correcting the references.

Try to solve these yourself first. The reference solution is available in result.dms in the same cfg subfolder — it shows one possible correct implementation. Other valid solutions exist.

Go to previous module: Module 1, Learning the basic concepts of GeoDMS

Go to next module: Module 1b, Learning the basic concepts of GeoDMS, understanding units