ISTP/IACG Variable Attributes

Variable attributes are linked with each individual variable, and provide additional information about each variable. A standard set of these attributes is very important, for this is where the information can be stored in a commonly defined manner. Note that CDF attributes are case-sensitive and must exactly follow what is shown here. The variable attributes can be listed in any order.

The following table lists all the attributes and the type of variables for which they are needed. If a type of variable is not listed, then that attribute need not be defined for that particular variable. However, if a given variable has an attribute that is not needed, it will be ignored in most ISTP/IACG compliant applications. (RV is record or time varying)

See Alphabetical list of Variable Attribute Definitions.

Attribute Need Notes
CATDESC Required All
DEPEND_0 Required data, RV support_data, and RV metadata
DEPEND_1 Required data of the following form:
  • 1D spectrogram
  • 1D stack_plot
  • 2D spectrogram
  • image
DEPEND_2 Required data of the following form:
  • 2D spectrogram
  • image
DEPEND_3 Required data of the following form:
  • 3D spectrogram
DISPLAY_TYPE Required data
FIELDNAM Required All
FILLVAL Required data, RV support_data, and RV metadata
FORMAT Required all not using FORM_PTR
FORM_PTR Required 1D data, support_data, and metadata not using FORMAT
LABLAXIS Required data of the following form:
  • image
  • scalar time_series
  • 1D spectrogram
Also needed for support_data that does not utilize LABL_PTR_X
LABL_PTR_1 Required data of the following form:
  • 1D time_series
  • 2D spectrogram
Also needed for 1D and 2D support_data without a LABLAXIS
LABL_PTR_2 Required data of the following form:
  • 2D spectrogram
  • 3D spectrogram
Also needed for 2D support_data without a LABLAXIS
LABL_PTR_3 Required data of the following form:
  • 3D spectrogram
UNITS Required data and support_data not using UNIT_PTR
UNIT_PTR Required 1D data and support_data not using UNITS
VALIDMIN Required data and RV support_data
VALIDMAX Required data and RV support_data
VAR_TYPE Required all
SCALETYP Recommended data not using SCALE_PTR and support_data
SCAL_PTR Recommended multidimensional data not using SCALETYP
VAR_NOTES Recommended all
AVG_TYPE Optional data or RV support_data
DELTA_PLUS_VAR Optional data
DELTA_MINUS_VAR Optional data
DICT_KEY Optional All
MONOTON Optional Epoch data
SCALEMIN Optional data and RV support_data
SCALEMAX Optional data and RV support_data
V_PARENT Optional data
DERIVN cluster required for derived variables
sig_digits cluster recommended data
SI_conv cluster recommended data

Variable Attribute Definitions in alphabetical order

AVG_TYPE --- optional

sets up useful default conditions: different techniques appropriate to averaging different types of data. If this attribute is not present, standard average, i.e., simple arithmetic mean, is assumed. The value of this attribute can be used with application software. The valid options are listed below.

CATDESC --- required for all variables

(catalog description) is an approximately 80-character string which is a textual description of the variable and includes a description of what the variable depends on. This information needs to be complete enough that users can select variables of interest based only on this value. (see CDAWeb www-based interface via URL http: cdaweb.gsfc.nasa.gov/space/). Examples :

DELTA_PLUS_VAR and DELTA_MINUS_VAR --- optional

are included to point to a variable (or variables) which stores the uncertainty in (or range of) the original variable's value. The uncertainty (or range) is stored as a (+/-) on the value of the original variable. For many variables in ISTP/IACG, the original variable will be at the center of the interval so that only one value (or one set of values) of uncertainty (or range) will need to be defined. In this case, DELTA_PLUS_VAR, and DELTA_MINUS_VAR will point to the same variable. See example. The value of the attribute must be a variable in the same CDF data set.

DEPEND_0 --- required for time-varying variables

explicitly ties a data variable to the time variable on which it depends. All variables which change with time must have a DEPEND_0 attribute defined. The value of DEPEND_0 is 'Epoch', the time ordering parameter for ISTP/IACG. Different time resolution data can be supported in a single CDF data set by defining the variables Epoch, Epoch_1, Epoch_2, etc. each representing a different time resolution. These are "attached" appropriately to the variables in the CDF data set via the attribute DEPEND_0. The value of the attribute must be a variable in the same CDF data set. See example.

DEPEND_1, DEPEND_2, etc --- required for dimensional variables as shown in table above. (1D time series data variables do not need a DEPEND_1 defined.)

ties a dimensional data variable to a support_data variable on which the i-th dimension of the data variable depends. The number of DEPEND attributes must match the dimensionality of the variable, i.e., a one-dimensional variable must have a DEPEND_1, a two-dimensional variable must have a DEPEND_1 and a DEPEND_2 attribute, etc. The value of the attribute must be a variable in the same CDF data set. See example.

DERIVN --- Cluster required for derived variables

A text string identifying the derivation of the variable, possibly including a function/algorithm name or journal reference. Most derived variables will not be unique, and this information is essential if the product is to be compared/validated elsewhere.

DICT_KEY --- optional

comes from a data dictionary keyword list and describes the variable to which it is attached. The ISTP/IACG standard dictionary keyword list is described in ISTP/IACG Dictionary Keywords.

DISPLAY_TYPE --- required for data variables

tells automated software what type of plot to make and what associated variables in the CDF are required in order to do so. Some valid values are listed below:

FIELDNAM --- required for all variables

holds a character string (up to 30 characters) which describes the variable. It can be used to label a plot either above or below the axis, or can be used as a data listing heading. Therefore, consideration should be given to the use of upper and lower case letters where the appearance of the output plot or data listing heading will be affected.

FILLVAL --- required for time varying variables

is the number inserted in the CDF in place of data values that are known to be bad or missing. Fill data are always non-valid data. The ISTP standard fill values are listed below. Fill values are automatically supplied in the ISTP CDHF ICSS environment (ICSS_KP_FILL_VALUES.INC) for key parameters produced at the CDHF. For key parameters produced outside of the CDHF, the values below should be used.

FORMAT --- required if not using FORM_PTR

is the output format used when extracting data values out to a file or screen (using CDFlist). The magnitude and the number of significant figures needed should be carefully considered. A good check is to consider it with respect to the values of VALIDMIN and VALIDMAX attributes. The output format can be in Fortran or C, but Fortran is preferred.

FORM_PTR --- required if not using FORMAT

has as its value a variable which stores the character strings (up to 20 characters per character string) representing the desired output format for the original variable. FORM_PTR is used instead of FORMAT. The value of the attribute must be a variable in the same CDF data set.

LABLAXIS --- required if not using LABL_PTR_1

should be a short character string (approximately 10 characters, but preferably 6 characters - more only if absolutely required for clarity) which can be used to label a y-axis for a plot or to provide a heading for a data listing.

LABL_PTR_1, LABL_PTR_2, etc. --- required if not using LABLAXIS

is used to label a dimensional variable when one value of LABLAXIS is not sufficient to describe the variable or to label all the axes. LABL_PTR_i is used instead of LABLAXIS, where i can take on any value from 1 to n where n is the total number of dimensions of the original variable. The value of LABL_PTR_1 is a variable which will contain the short character strings which describe the first dimension of the original variable. The actual labels should be short as described above for LABLAXIS. The value of the attribute must be a variable in the same CDF data set. See example.

MONOTON --- optional

indicates whether the variable is monotonically increasing or monotonically decreasing. Use of MONOTON is strongly recommended for the Epoch time variable, and can significantly increase the performance speed on retrieval of data. Valid values: INCREASE, DECREASE.

SCALEMIN and SCALEMAX --- optional

are values which can be based on the actual values of data found in the CDF data set or on the probable uses of the data, {\em e.g.}, plotting multiple files at the same scale. Visualization software can use these attributes as defaults for plotting. The values must match the data type of the variable.

SCALETYP --- recommended for non-linear scales if not using SCAL_PTR

indicates whether the variable should have a linear or a log scale as a default. If this attribute is not present, linear scale is assumed.

SCAL_PTR --- recommended for non-linear scales if not using SCALETYP

is used for dimensional variables when one value of SCALTYP is not sufficient. SCAL_PTR is used {\em instead of} SCALTYP, and will point to a variable which will be of the same dimensionality as the original variable. The allowed values are linear and log. The value of the attribute must be a variable in the same CDF data set.

sig_digits --- Cluster recommended

This attribute provides the number of significant digits or other measure of data accuracy in a TBD manner. It is to allow compression software to optimise the number of digits to retain, and users to assess the accuracy of products. This operation is subject to the deliberations of the `network traffic report' Task Group, DS-CFC-TN-0001, on compression algorithms and implementation. Restrictions on data compression may also influence the format and choice of data type used by the CDF generation software.

SI_conversion --- Cluster recommended

The conversion factor to SI units. This is the factor that the variable must be multiplied by in order to turn it to generic SI units. It will copntain two text fields separated by the delimiter >. The first is the conversion and the second is the standard unit that it converts to. For example the magnetic field for FGM will be in nT, and to convert to Tesla the value of SI_conv will be `1.0e-9>Tesla'. The use of text allows this attribute to be parsed and the value must be extracted in software.

UNITS --- required if not using UNIT_PTR

is a character string (no more than 20 characters, but preferably 6 characters) representing the units of the variable, e.g., nT for magnetic field. If the standard abbreviation used is short then the units value can be added to a data listing heading or plot label. Use a blank character, rather than "None" or "unitless", for variables that have no units (e.g., a ratio or a direction cosine).

UNIT_PTR --- required if not using UNITS

has as its value a variable which stores the character strings (up to 20 characters per character string) representing the units of the original variable, which can be added to a data listing heading or plot label. Use a blank character, rather than "None" or "unitless", for variables that have no units (e.g., a ratio or a direction cosine). If this attribute is used, then UNITS is not used. The value of the attribute must be a variable in the same CDF data set.

VALIDMIN and VALIDMAX --- required for time varying data and support_data

hold values which are, respectively, the minimum and maximum values for a particular variable that are expected over the lifetime of the mission. The values must match the data type of the variable.

VAR_NOTES --- optional

holds ancilliary information about the variable and can be any length.

VAR_TYPE --- required for all variables

identifies a variable as either

V_PARENT --- optional for use with derived variables

identifies the "attached" variable which stores the parent variable(s) of a derived variable. The `attached" variable can be dimensional and sized to hold as many parents as necessary. The syntax of each entry would be: logical_file_id>variable_name.

*Return to Top of Page

* Return to ISTP/IACG Guidelines

* Return to Space Physics Use of CDF

*CDF home page

Authors and Curators

Mona Kessel, mona.kessel@gsfc.nasa.gov, (301)286-6595
Code 632, NASA Goddard Space Flight Center
Greenbelt, MD 20771, USA

Authorized by R.E. McGuire, Head, Space Physics Data Facility
(Code 632, NASA/GSFC), Robert.E.McGuire@gsfc.nasa.gov, (301)286-7794
Last Updated: 3 October 2003, RLK