[Top] [Prev] [Next]

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 explanation for a file or data object, as in "COLLECTED 12/14/90" or "BLACK HOLE SIMULATION". The annotation can be as short as a name or as long as a portion of source code. For example, if the data originated as satellite data, the annotation might include the source of the data, pertinent environmental conditions, or other relevant information. In the case of a hypothetical black hole simulation, the annotation might contain source code for the program that produced the data.

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.

Annotations can be attached to files or data objects, and are themselves data objects identifiable by a tag/reference number pair. Refer to Chapter 2, HDF Fundamentals, for a description of tag/reference number pairs.

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 typically contain more extensive information, such as a source code module or mathematical formulae.

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

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 assigned to a file to 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 is possible to use a file annotation to describe a data object in a file, this practice is not recommended. Each data object should be described by its own data object annotation as it is added to the file.

10.2.3 Object Annotations

Object annotations are 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 (see Chapter 2, HDF Fundamentals).

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 10. (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 10.

FIGURE 10b - Object Annotations with Tag/Reference Number Pairs

10.2.4 Terminology

The following pairs of terms are used interchangeably in the following discussions: data object annotation and data annotation; data object label and data label; data object description and data description.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.