Annotation

For models of physical systems, annotating the implementation is a way to make the results more intelligeable. For example simply making numeric output available in a table is only useful if there is some way to know what the values mean, what quantity they represent and in what units. It is helpful to have longer, more descriptive names for things as well so that some amount of automatic presentation can be done by tools that support it.

In the mois software, athe main entities may be annotated, anything deriving from BaseProcess, or Var. It is done by simply calling the annotate method (defined in the Annotation trait) with a key and a value. The key must be a string but the value can be anything.

For example,

import uk.ac.ed.inf.mois.ODE

class P extends ODE("Some Process") {
  annotate("title", "A process that calculates things")
  annotate("author", "Jane R Hacker")

  val x = Double("x")
  x.annotate("long_name", "The X value")
  x.annotate("units", "cm")
  ...
}

The recommendation is to use the Climate and Forecast Metadata Conventions as a starting point because, when using the NetCDF output facility many of the standard programs for reading such files will be able to make sense of them. In general they are quite generic and not specific to the geosciences. Clearly the usage in biology will be slightly different, but it is better to use established concepts like “long_name” and “units” than to re-invent them.

Units require some thought. There is a set of basic and compound standard SI units. Where possible these should be used, again because other software understands them. These may be freely built upon.