[Top] [Prev] [Next] [Bottom]

10.2 The Annotation Data Model

When working with different data types, it is often convenient to identify the contents of a file by adding a short text description or annotation. An annotation serves as the label for a file or data element, as in "COLLECTED 12/14/90" or "BLACK HOLE SIMULATION". For example, if the data originated as satellite data, the description might include the source of the data, pertinent environmental conditions, or other relevant information. In the case of a hypothetical black hole simulation, the description might contain source code for the program that produced the data.

As they are implemented as variable-length strings, HDF annotations are designed to accommodate a wide variety of information including titles, comments, variable names, parameters, formulas, and source code. In fact, HDF annotations can encompass any textual information regarding the collection, meaning, or intended use of the data.

10.2.1 Labels and Descriptions

Annotations come in two forms; labels and descriptions. Labels are short annotations used for assigning things like titles or time stamps to a file or its data objects. Longer annotations are called descriptions, and they typically contain more extensive information such as a source code module or mathematical formulae.

Labels are defined as a null-terminated string of characters except NULL. Descriptions may contain any sequence of ASCII characters including NULL.

In addition to the distinction made between labels and descriptions, HDF distinguishes between file annotations and object annotations.

10.2.2 File Annotations

File annotations are text strings which describe the origin, meaning, or intended use of its data. Any HDF file can be annotated with a label, description, or combination of both. (See Figure 10a.) The number of labels or descriptions an HDF file may contain is limited to the maximum number of tag/reference number pairs. File annotations may be assigned in any order and at any time after a file is created.

FIGURE 10a File and Object Annotations

Although it may seem convenient to use a file annotation to describe one data object in a file, this practice is not recommended because any additional objects added to the file will obscure the implicit link between the original object and its annotation.

10.2.3 Object Annotations

Object annotations are text strings assigned to individual data objects to explain their origin, meaning, or intended use. Because object annotations are assigned to individual objects, their use requires an understanding of HDF tags and reference numbers.

The annotation interface takes advantage of this identification scheme by including the object's tag/reference number pair with the text of the annotation. Consider a scientific data set identified by the tag DFTAG_NDG and the reference number 1. (See Figure 10b.) All object annotations assigned to this particular data set must be prefaced with the tag DFTAG_NDG followed by the reference number 1.

FIGURE 10b Object Annotations with Tag/Reference Number Pairs



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.