modelutil: Metadata for Field Objects

Index

• Attributes of Field
• Rules For Selected Field Attribute Values
• Checking Metadata with an InterfaceMeta Definition
• Copying and Replacing Metadata
• Example
• Notes

Attributes of Field

The Field object is a container object holding the field's data; the data are accessible via the special methods for containers and array slicing. Field objects have the following attributes:

• id: Unique name of the field. String.
• long_name: Description of the field. String.
• units: Units of the field. String.
• extra_meta: Object containing all metadata associated with the field besides id, long_name, and units. Instance of class ExtraMeta.

The id, long_name, and units attributes are referred to as "key metadata". All other metadata are attributes of the ExtraMeta object stored as Field attribute extra_meta.

Keep in mind when you make use of information stored in ExtraMeta objects that by default ExtraMeta objects are initialized empty; they only will contain values if you add them in by keyword at instantiation or by setting them after instantiation.

Rules For Selected Field Attribute Values

id: String must have no blank spaces or punctuation marks besides underscores or hyphens. Alphabetic or numeric values are allowed.

long_name: Any Python legal string is allowed. Since there are no conventions for this attribute, no tests should be made on its content.

units: SI units without prefixes are preferred, though a few exceptions are common (e.g. hPa). String values follow the following rules:

• Operators are *, /, and ** for multiplication, division, and exponentiation, respectively. Braces ({}) are used for parenthetical expressions.
• Operators follow standard evaluation precedence: parenthetical statements first, followed by exponentiation, and multiplication/division last. Evaluation of operators of the same precedence is done left to right.
• Parenthetical notation is used only if needed. If units can be expressed without resorting to parenthetical statements, the version without is chosen; this is done even if the units read more awkwardly. Thus, radiative fluxes should be given as W/m**2 instead of W*m**{-2}, and thermal conductivity is W/m/K instead of W/{m*K}.
• Unitless variables are denoted "unitless".

Metadata in extra_meta generally do not follow any conventions. There are, however, a few attributes of extra_meta whose meanings are rigidly defined. Note that the default for all extra_meta attributes is to be undefined:

• axis: List of strings, each of which gives the id of the Field variable that is the corresponding axis of the data array in the Field object the extra_meta attribute is attached to. For instance, latitude (Field id lat) is also a Field variable itself. Note: axis (and its related attributes) should not be defined if the Field object itself is an axis. This attribute should not exist for scalar Field objects.
• axis_long_name: List of strings, each giving an extended description of each of the axis of the data array. This attribute should not exist for scalar Field objects.
• axis_units: List of strings, each denoting the units of each of the axis of the data array. This attribute should not exist for scalar Field objects.
• isaxis: Is True if Field object is an axis for other Field objects; False otherwise. If this attribute is True, it is expected that all data values in this Field variable are unique.
• istend1: Is True if Field object is a time differential (tendency) multiplied by one timestep; False otherwise (i.e. when the value is a full field).

While the Field metadata are not forced to follow a convention, feel free to define your Field variables to follow any convention of your choosing. The Field metadata framework should be flexible enough to accomodate any convention you wish to use. My own preferences for the axis attribute, for instance, are a personal amalgam of the CDC and GDT netCDF conventions.

Checking Metadata with an InterfaceMeta Definition

One common problem in modeling is ensuring that one variable calculated in one subroutine is the same as another variable of the same name in another subroutine. How do we prevent procedure foo from calculating precipitation in mm/day and passing it to procedure goo which assumes precipitation is in mm/mo? This is the purpose of the meta_ok_to_interface method present in the Field class (and in State and StateSet).

InterfaceMeta objects are used by the method meta_ok_to_interface, which is found in Field (and State and StateSet) objects. The InterfaceMeta object is passed in as an argument, and all comparisons by the method is to the definitions given in that InterfaceMeta instance. For a Field variable to return True when meta_ok_to_interface is called, the variable does not have to be one defined in the InterfaceMeta definition,¹ but if it is defined, it has to have the same metadata and pass certain consistency checks. For meta_ok_to_interface in State and StateSet to return True, all Field objects in those states that have ids given in the InterfaceMeta object must return True when each of those Field meta_ok_to_interface methods are called.

The pydoc documentation for meta_ok_to_interface has details as to what checks the method executes. See the description of the InterfaceMeta class for details as to the contents of objects of the class.

Copying and Replacing Metadata

Field objects have a variety of methods for managing and manipulating metadata. The two primary methods used to copy and replace metadata from and in Field objects are copymeta, which returns a copy of the metadata of the entire object, and replace_all_meta which sets metadata to the values in the Field object passed in as an argument. These and additional Field object metadata management methods are described here.

There is a special metadata copying function in the field module, copymeta_largest, which returns a Field object that contains a copy of the metadata for the "largest" Field object of a set of Field objects (where "largest" can roughly be described as the Field object with the largest array; the pydoc documentation for copymeta_largest provides the detailed algorithm that specifies how "largest" is defined). The primary use of this function is to help solve the problem of how to write a model that has the maximum flexibility in whether variables are configued as uniform constants or spatially and temporally varying prognostic variables. See the section on how to code a flexible model for further discussion on the use of copymeta_largest.

Example

Example of a Field object with some metadata:

>>> from modelutil.field import Field
>>> import Numeric as N
>>> data = N.array([1., 2., 5., -3., -4.4])
>>> a = Field(data, id='u', axis=['Latitude'])
>>> print a
array([ 1. ,  2. ,  5. , -3. , -4.4])
>>> print a.id
u
>>> print a.extra_meta.axis[0]
Latitude

The latitude of a is a Field object with id of "latitude" and of the same size as a. Below is an example of a variable that fits the criteria (the latitude values are evenly space in the example, but there is no requirement for axes to be formatted this way). Note that since lat is an axis, the isaxis attribute is set to True:

>>> lat = Field( N.array([-10., -5., 0., 5., 10.]) \
               , id='latitude', isaxis=True )
>>> print lat.id
latitude
>>> print lat.extra_meta.isaxis
True

Notes

1. The exception is if the Field object is an axis, in which case it must be defined in the InterfaceMeta object for the check to pass. Likewise, if extra_meta.axis and related attributes are set, they must be defined in the InterfaceMeta object for the check to pass.