5. ISTP Variable Attributes

Variable attributes are linked with and provide additional information about the individual variables. The following tables list all the ISTP variable attributes with examples and requirements based on the ISTP variable type (data, support_data, or metadata; defined by the VAR_TYPE attribute value). Note that if a variable has an attribute that is not needed/not applicable, it will be ignored by most of the ISTP compliant applications. RV means record-varying (in CDF format) or, simply, time-varying variable. See Variable Attribute Definitions for the full set of defined variable attributes in alphabetical order. Variable attributes can be listed in any order.

Note that attribute names are case sensitive, and the names of the ISTP variable attributes must match the case as shown. Also, for variable attributes with numerical values (e.g., FILLVAL, VALIDMIN, VALIDMAX), the attribute data type must match the variable data type. Also note that variable attribute CDF_CHAR data type in CDF format corresponds to either character or scalar string data types in netCDF-4 format (array of strings as the variable attribute value is not supported).

Additional variable attributes may be defined. Their names must start with a letter and can contain letters, numbers, the underscore character, but no other special or Unicode characters. Though attribute names are case sensitive, the names must not be distinguished by case only.

Attribute Name	Requirement (see details in Notes column)	Example Value, Required Data Type	Notes
CATDESC	Required	"Electron count rate" CDF_CHAR	Required for all variables. No more than 120, but preferably 80, characters.
long_name (netCDF only)	Required	"Electron count rate" CDF_CHAR	Required for all variables.
COORDINATE_SYSTEM (PROPOSAL ONLY)	Required	"GSE" CDF_CHAR	Required for data vectors, tensors, and individual components.
DEPEND_0	Required	"Epoch" CDF_CHAR	Required for RV variables.
DEPEND_1	Required	"Electron_Energy" CDF_CHAR	Required for data of the following form: 1-D spectrogram, 1-D stack_plot, 2-D spectrogram, image.
DEPEND_2	Required	"Telescope_angle" CDF_CHAR	Required for data of the following form: 2-D spectrogram, image.
DEPEND_3	Required	"Sector_angle" CDF_CHAR	Required for data of the following form: 3-D spectrogram.
DISPLAY_TYPE	Required	"time_series" CDF_CHAR	Required for data.
FIELDNAM	Required	"Electron count rate" CDF_CHAR	Required for all variables. No more than 50, but preferably 30, characters.
FILLVAL	Required	-1.0e+31 Must match variable data type	Required for RV variables.
_FillValue (netCDF only)	Required	-1.0e+31 Must match variable data type	Required for RV variables.
FORMAT	Required	"F10.1" CDF_CHAR	Required for all variables not using FORM_PTR, except for defined time data types.
FORM_PTR	Required	"formats_E_cnt_rate" CDF_CHAR	Required for 1-D data, support_data, and metadata not using FORMAT. Points to a 1-D string metadata variable with the same dimension size.
LABLAXIS	Required	"E count rate" CDF_CHAR	Required for data of the following form: image, scalar time_series, 1-D spectrogram, 1-D stack_plot. Also needed for support_data that does not use LABL_PTR_1. No more than 20, but preferably 10, characters.
LABL_PTR_1	Required	"Electron_Energy_Label" CDF_CHAR	Required for data of the following form: 1-D Time_series, 2-D Spectrogram. Also needed for 1-D and 2-D support_data without a LABLAXIS. Points to a 1-D string metadata variable with the same dimension size.
LABL_PTR_2	Required	"Telescope_Label" CDF_CHAR	Required for data of the following form: 2-D spectrogram, 3-D spectrogram. Also needed for 2-D support_data without LABLAXIS. Points to a 1-D string metadata variable with the same dimension size.
LABL_PTR_3	Required	"Sector_Label" CDF_CHAR	Required for data of the following form: 3-D Spectrogram. Points to a 1-D string metadata variable with the same dimension size.
REPRESENTATION_i (PROPOSAL ONLY)	Required, required by Cluster	"representation_xyz" CDF_CHAR	Required for data vectors and tensors. Points to a 1-D string metadata variable with the same dimension size.
TENSOR_FRAME	Optional, required by Cluster	"GSE" CDF_CHAR	Optional (required by Cluster) for data vectors, tensors, and individual components.
TENSOR_ORDER (PROPOSAL ONLY)	Required, required by Cluster	2 Integer	Required for data vectors and tensors.
UNITS	Required	"count/ms" CDF_CHAR	Required for data and support_data not using UNIT_PTR.
units (netCDF only)	Required	"count/ms" CDF_CHAR	Required for data and support_data not using UNIT_PTR.
UNIT_PTR	Required	"units_E_cnt_rate" CDF_CHAR	Required for 1-D data and support_data not using UNITS. Points to a 1-D string metadata variable with the same dimension size.
VALIDMIN	Required	0.0 Must match variable data type	Required for data and RV support_data.
VALIDMAX	Required	1000.0 Must match variable data type	Required for data and RV support_data.
VAR_TYPE	Required	"data" CDF_CHAR	Required for all variables; defines the ISTP variable type.
DICT_KEY	Recommended	"particle_flux>number_rate" CDF_CHAR	Recommended for data and support_data; describes the variable using keywords from controlled dictionaries.
FRAME_ORIGIN (PROPOSAL ONLY)	Recommended	"Observatory" CDF_CHAR	Recommended for data vectors, tensors, and individual components.
FRAME_VELOCITY (PROPOSAL ONLY)	Recommended	"Observatory" CDF_CHAR	Recommended for data vectors, tensors, and individual components.
SCALETYP	Recommended	"linear" CDF_CHAR	Recommended for data not using SCAL_PTR and support_data.
SCAL_PTR	Recommended	"scales_E_cnt_rate" CDF_CHAR	Recommended for 1-D data not using SCALETYP. Points to a 1-D string metadata variable with the same dimension size.
sig_digits	Optional, recommended by Cluster	5 Integer	Optional (recommended by Cluster) for data.
VAR_NOTES	Recommended	"Particle Energy mode. Corrected for deadtime. May contain substantial non-electron background." CDF_CHAR	Recommended for all variables; unlimited character length.
AVG_TYPE	Optional	"standard" CDF_CHAR	Optional for data and RV support_data.
DELTA_MINUS (PROPOSAL ONLY)	Optional	5.0 Must match variable data type	Optional for data and support_data.
DELTA_MINUS_VAR	Optional	"E_cnt_rate_DELTA" CDF_CHAR	Optional for data and support_data variables. Points to a support_data variable with the same dimension sizes.
DELTA_PLUS (PROPOSAL ONLY)	Optional	5.0 Must match variable data type	Optional for data and support_data.
DELTA_PLUS_VAR	Optional	"E_cnt_rate_DELTA" CDF_CHAR	Optional for data and support_data variables. Points to a support_data variable with the same dimension sizes.
FRAME	Optional	"vector>gse_xyz" CDF_CHAR	Optional for data.
LIMITS_NOMINAL_MIN	Optional	200.0 Must match variable data type	Optional for data and RV support_data.
LIMITS_NOMINAL_MAX	Optional	800.0 Must match variable data type	Optional for data and RV support_data.
LIMITS_WARN_MIN	Optional	100.0 Must match variable data type	Optional for data and RV support_data.
LIMITS_WARN_MAX	Optional	900.0 Must match variable data type	Optional for data and RV support_data.
MONOTON	Optional	"INCREASE" CDF_CHAR	Optional for epoch variables (RV support_data).
SCALEMIN	Optional	200.0 Must match variable data type	Optional for data and RV support_data.
SCALEMAX	Optional	800.0 Must match variable data type	Optional for data and RV support_data.
SI_CONVERSION	Optional	"1.0E3>count/s" CDF_CHAR	Optional for data and support_data.
VARIABLE_PURPOSE	Optional	"PRIMARY_VAR" CDF_CHAR	Optional for data.
V_PARENT	Optional	"E_cnt_rate_all" CDF_CHAR	Optional for data.

5.1. Variable Attributes for Time Documentation

The attributes in the table below should be used for precise definition of a time variable, and especially for time variables in netCDF with no dedicated time data type. Note that they are not needed for the CDF_TIME_TT2000 time data type, internally precisely defined as:

TIME_BASE = "J2000"  
TIME_SCALE = "Terrestrial Time"
REFERENCE_POSITION = "Rotating Earth Geoid"
UNITS = "ns"

See CDF_TIME_TT2000 requirements analysis and development approach for more details.

Attribute	Requirement (see details in Notes column)	Example Value, Required Data Type	Notes
TIME_BASE	Recommended (Important for netCDF files and clarity)	"J2000" CDF_CHAR	Fixed ("0 AD" (used by CDF_EPOCH and CDF_EPOCH16), "1900", "1970" (POSIX), "J2000" (used by CDF_TIME_TT2000), "4714 BC" (Julian)) or "flexible" (provider-defined).
TIME_SCALE	Recommended	"TT" CDF_CHAR	"TT" (same as TDT, used by CDF_TIME_TT2000), "TAI" (same as IAT, TT-32.184s), "UTC" (includes leap seconds), "TDB" (same as SPICE ET), "EME1950" [default: "UTC"].
LEAP_SECONDS_INCLUDED	Recommended for UTC only	"1961JAN01+1.42282s, … ,2017JAN01+1s" CDF_CHAR	Comma-delimited list of leap seconds.
ABSOLUTE_ERROR	Optional	0.3 Must match variable underlying basic data type	Absolute or systematic error, in same units as UNITS attribute.
BIN_LOCATION	Optional	0.5 CDF_REAL4, CDF_REAL8, or equivalent	Relative position of time stamp to the data measurement bin, with 0.0 at the beginning of time bin and 1.0 at the end. Default is 0.5 for the time at the center of the data measurement.
REFERENCE_POSITION	Optional	"Geocenter" CDF_CHAR	"Topocenter" (local), "Geocenter", "Rotating Earth Geoid" (used by CDF_TIME_TT2000).
RELATIVE_ERROR	Optional	0.4 Must match variable underlying basic data type	Relative or random error, in same units as UNITS attribute - to specify the accuracy of the time stamps relative to each other.
RESOLUTION	Optional	"1ms" CDF_CHAR	Using ISO8601 relative time format, for example: "1ms" = 1 millisecond. Resolution provides the smallest change in time that is measured.
UNITS	Optional	"ns" CDF_CHAR	SI measurement unit: "s", "ms"(milliseconds for CDF_EPOCH variables), "ns"(nanoseconds for CDF_TIME_TT2000), "ps"(picoseconds for CDF_EPOCH16).

5.2. Variable Attribute Definitions

5.2.1. ABSOLUTE_ERROR

(Optional for time variables.) Absolute or systematic error, in same units as UNITS attribute.

5.2.2. AVG_TYPE

(Optional for data and RV support_data.) The default averaging technique that should be performed on the data to reduce resolution. 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:

• "standard" - simple arithmetic mean.

• "angle_degrees" - “direction” average over 360 deg e.g., average of 5 and 355 is 0 instead of 180.

• "angle_radians" - “direction” average over 2 pi.

• "angle_hour" - “direction” average over local times (hours), e.g., average of 2 and 22 is 0 instead of 12.

• "RMS" - square root of the average of the squares of the values.

• "log" - logarithm of the average of the anti-logarithms of the values.

• "decibel" - 10 times the logarithm of the average of the anti-logarithms of the (values/10).

• "cosine" - cosine of the average of the arc-cosines of the values.

• "none" - no meaningful averaging calculation is possible.

• "Geometric" - anti-logarithm of the average of the logarithms of the values.

5.2.3. BIN_LOCATION

(Optional for time variables.) Relative position of time stamp to the data measurement bin, with 0.0 at the beginning of time bin and 1.0 at the end. Default is 0.5 for the time at the center of the data measurement bin. Since clock readings are usually truncated, the real value may be closer to 0.0.

5.2.4. CATDESC

(Required for all variables. netCDF additionally requires long_name attribute with the same value.) Catalog description, CATDESC, is no more than 120, but preferably 80, characters textual description of the variable, and should also include 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, e.g., CDAWeb web interface). If necessary, more detailed variable description, including, e.g., caveats or description of all possible values for a flag variable, should be included in the VAR_NOTS attribute. CATDESC examples for different instrument types:

• Geotail CPI: "Ion number density (Solar Wind Analyzer), scalar"

• Geotail EPI: "Ion Diff. Intensity, at 12 energies 67-1361 keV"

• Wind MFI: "Magnetic Field, Cartesian GSM coordinates"

• Geotail EFD: "Electric Field from spherical probe, sunwd \ duskwd comp"

• Canopus MPA: "42 values of 5577A Intensities from Geodetic Lat 46-67, Long=265"

• Canopus MARI: "Local Auroral Electrojet index, lower bound (CL), scalar"

5.2.5. COORDINATE_SYSTEM

(Required for data vectors, tensors, and individual components. PROPOSAL ONLY.) The name of the coordinate system of a tensor, e.g., "GSE". Same as TENSOR_FRAME.

5.2.6. DELTA_PLUS, DELTA_MINUS

(Optional for data and support_data. PROPOSAL ONLY.) Similar to DELTA_PLUS_VAR and DELTA_MINUS_VAR, with the difference that, instead of pointing to variables, DELTA_PLUS and DELTA_MINUS hold single (+/-) values that apply to all original variable values. DELTA_PLUS and DELTA_MINUS can also hold 1-D arrays of values (of the same size as the original variable) in case the original variable is a 1-D variable with each value requiring a separate (+/-) pair. The data type of the attribute values must match the data type of the original variable. Also, see DELTA_PLUS_VAR and DELTA_MINUS_VAR description on using with time data types.

5.2.7. DELTA_PLUS_VAR, DELTA_MINUS_VAR

(Optional for data and support_data.) The two attributes, always used together, have as their values the names of metadata variables (in the same dataset) which store the uncertainty (or range) of the original variable values. The uncertainty (or range) is stored as a (+/-) on the value of the original variable. In many cases, the original variable will be at the center of the interval, so that only one uncertainty (or range) variable will need to be defined to which both DELTA_PLUS_VAR and DELTA_MINUS_VAR will point to. See example of use.

The variables pointed to by DELTA_PLUS_VAR and DELTA_MINUS_VAR must be of the same dimensionality/dimension sizes and the same data type as the original variable, and can be either time-varying or time invariant. In case of the original variable being of a CDF time data type (CDF_TIME_TT2000, CDF_EPOCH, or CDF_EPOCH16), variables pointed to by DELTA_PLUS_VAR and DELTA_MINUS_VAR should be of the underlying basic data type (CDF_INT8 for CDF_TIME_TT2000 and CDF_REAL8 for both CDF_EPOCH and CDF_EPOCH16).

5.2.8. DEPEND_0

(Required for RV variables.) Explicitly ties a 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 the name of a time variable (time ordering parameter for ISTP), e.g., "Epoch". Different time resolution data variables can be supported in a single dataset by defining multiple time variables, e.g., Epoch, Epoch_1, Epoch_2, Epoch_1s, Epoch_1m (or any other meaningful name), each representing a different time resolution. These are attached appropriately to variables in the dataset via their DEPEND_0 attribute. The value of the attribute must be the name of a variable in the same dataset. See example of use.

5.2.9. DEPEND_i

(Required for dimensional data variables, as shown in the table above. Note that 1-D time series data variables do not need DEPEND_1.) 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_i 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 DEPEND_1 and DEPEND_2 attributes, etc. The value of the attribute must be the name of a variable in the same dataset. See example of use.

5.2.10. DICT_KEY

(Recommended for data and support_data variables.) Describes the variable using keywords from controlled dictionaries (either SPASE model dictionary, preferred, or original ISTP dictionary). Use of both options is described in Dictionary Keywords.

5.2.11. DISPLAY_TYPE

(Required for data variables.) Tells automated software what type of plot to make and what attributes and associated variables in the CDF are required in order to do so. Some valid values are listed below. See example of use.

• "time_series"

• "spectrogram"

• "stack_plot"

• "image"

• "no_plot"

5.2.12. FIELDNAM

(Required for all variables.) Holds a short character string (no more than 50, but preferably 30, characters) which names 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. Note that CATDESC attribute is used for complete variable description.

5.2.13. FILLVAL

(Required for RV variables. netCDF additionally requires _FillValue attribute with the same value.) The attribute holds a special value that is used in place of the variable values that are known to be non-valid or missing. The FILLVAL attribute data type for each variable must match the data type of that variable. The ISTP recommended FILLVAL values for different data type are listed below. However, different FILLVAL values, and possibly different for different variables of the same data type, may be used as long as for each variable its FILLVAL value is outside of the [VALIDMIN, VALIDMAX] range for that variable. Additionally, for Floating Point data types, NaN (IEEE 754) can be used.

Note that decimal -1.0E31, a recommended FILLVAL value for Floating Point data types (IEEE 754 binary 4-byte and 8-byte floating-point), does not have exact binary representation in either of those data types, and the exact values stored in CDF (or netCDF) binary files are -9999999848243207295109594873856 for CDF_REAL4 and -9999999999999999635896294965248 for CDF_REAL8. However, since both the variable and attribute values are stored as binary, and since the FILLVAL attribute is required to be of the same data type as the variable, there is exact bit match between the variable filled values and the FILLVAL value. Also note that NaN, the other recommended, and potentially preferred, FILLVAL value for Floating Point data types, is not equal to itself in most programming language, and a separate algorithm for identifying NaNs should always be implemented.

Also listed below are the default values (for different data type) of the PadValue CDF variable property. PadValue is used, e.g., to fill allocated variable records when a variable in a CDF file is first created and before the actual data records are written for the variable. PadValue is also returned when a variable record outside of the maximum record for the variables is read. The default PadValue is set automatically by the CDF Library when a CDF variable is created. Note that starting with CDF Library V3.8, if FILLVAL attribute is defined, it will be used to fill variable’s missing data, instead of the PadValue.

Data Type	FILLVAL	PadValue
CDF_REAL4	-1.0E31 or NaN	-1.0E30
CDF_REAL8	-1.0E31 or NaN	-1.0E30
CDF_INT1	-128	-127
CDF_UINT1	255	254
CDF_INT2	-32768	-32767
CDF_UINT2	65535	65534
CDF_INT4	-2147483648	-2147483647
CDF_UINT4	4294967295	4294967294
CDF_INT8	-9223372036854775808	-9223372036854775807

Additionally, the ISTP Guidelines require the following special FILLVAL values (and the CDF Library sets default PadValue values) for variables of the three time types defined in CDF. Note that in a file CDF_TIME_TT2000, CDF_EPOCH, and CDF_EPOCH16 values are stored as 8-byte signed integer, 8-byte floating-point, and two 8-byte floating-point numbers, respectively. The shown Input/Output String is the time sting (ISO 8601) corresponding to the FILLVAL or PadValue value. Note that for the time types defined in CDF, corresponding CDF Library functions must be used for converting between values and the string representations.

Time Type	FILLVAL or PadValue	Value	Input/Output String
CDF_TIME_TT2000	FILLVAL	-9223372036854775808	"9999-12-31T23:59:59.999999999"
	PadValue	-9223372036854775807	"0000-01-01T00:00:00.000000000"
CDF_EPOCH	FILLVAL	-1.0E31	"9999-12-31T23:59:59.999"
	PadValue	0.0	"0000-01-01T00:00:00.000"
CDF_EPOCH16	FILLVAL	-1.0E31, -1.0E31	"9999-12-31T23:59:59.999999999999"
	PadValue	0.0, 0.0	"0000-01-01T00:00:00.000000000000"

5.2.14. FORMAT

(Required for all variables not using FORM_PTR, except for defined time data types.) Is the output format used for data ASCII listings (e.g., using CDFlist utility of CDF Library). 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 should be in Fortran format, i.e., "I10" for an integer, "F10.3" for a floating-point, or "A10" for a character data type.

5.2.15. FORM_PTR

(Required for 1-D data, support_data, and metadata not using FORMAT.) FORM_PTR is used instead of FORMAT when one format string is not sufficient for a dimensional variable. Its value is the name of a 1-D metadata variable (in the same dataset) with the same dimension size, which stores the character strings representing the desired output formats for the original variable.

5.2.16. FRAME

(Optional for data.) Optional and partially redundant with the more powerful description provided by the three concepts TENSOR_ORDER, REPRESENTATION_i, and TENSOR_FRAME.

5.2.17. FRAME_ORIGIN

(Recommended for data vectors, tensors, and individual components. PROPOSAL ONLY.) Identifies the location of the coordinate system origin (e.g., FRAME_ORIGIN = "Observatory") if different from that implied by the value in COORDINATE_SYSTEM.

5.2.18. FRAME_VELOCITY

(Recommended for data vectors, tensors, and individual components. PROPOSAL ONLY.) Identifies the motion of the coordinate system origin (e.g., FRAME_VELOCITY = "Observatory") if different from that implied by the value in COORDINATE_SYSTEM.

5.2.19. LABLAXIS

(Required, as shown in the table above, for variables not using LABL_PTR_1.) Should be a short string (no more than 20, but preferably 10, characters), which can be used to label the y-axis for a plot or to provide a heading for a data listing. Note that the unit strings are included separately via the UNITS/UNIT_PTR attributes.

5.2.20. LABL_PTR_i

(Required for dimensional variables, as shown in the table above, for variables 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 be from 1 to the total number of dimensions of the original variable. E.g., the value of LABL_PTR_1 is the name of a metadata variable (in the same dataset) which holds a 1-D array of character strings corresponding to the first dimension of the original variable. The actual labels should be short as described above for LABLAXIS. See example of use.

5.2.21. LEAP_SECONDS_INCLUDED

(Recommended for UTC time variable only.) A comma-delimited list of times when leap seconds were added, appended with each leap second size [default: standard list of leap seconds up to time of data]. LEAP_SECONDS_INCLUDED is needed to account for time scales that don’t have all 37 (in 2022) leap seconds and for the clocks in various countries that started using leap seconds at different times. The full list is required to handle the equally or more common case where a time scale starts at a specific Universal Time Coordinate (UTC) but continues on without leap seconds in TAI mode; this is basically what missions that don’t add leap seconds are doing.

LEAP_SECONDS_INCLUDED="1961JAN01+1.42282s,1961AUG01-0.05s,1962JAN01+0.47304s,1963NOV01+0.1s,1964JAN01+1.29427s,1964APR01+0.1s,1964SEP01+0.1s,1965JAN01+0.1s,1965MAR01+0.1s,1965JUL01+0.1s,1965SEP01+0.1s,1966JAN01+0.47304s,1968FEB010.1s,1972JAN01+5.78683s,1972JUL01+1s,1973JAN01+1s,1974JAN01+1s,1975JAN01+1s,1976JAN01+1s,1977JAN01+1s,1978JAN01+1s,1979JAN01+1s,1980JAN01+1s,1981JUL01+1s,1982JUL01+1s,1983JUL01+1s,1985JUL01+1s,1988JAN01+1s,1990JAN01+1s,1991JAN01+1s,1992JUL01+1s,1993JUL01+1s,1994JUL01+1s,1996JAN01+1s,1997JUL01+1s,1999JAN01+1s,2006JAN01+1s,2009JAN01+1s,2012JUL01+1s,2015JUL01+1s,2017JAN01+1s"

5.2.22. LIMITS_NOMINAL_MIN, LIMITS_NOMINAL_MAX

(Optional for data and RV support_data.) Values which define the range of nominal operations, and where values outside the range should be flagged as warnings (often referred to as yellow limits). Visualization software can use these attributes for indicating limits on plots or other warnings. The range of LIMITS_NOMINAL_MIN and LIMITS_NOMINAL_MAX fall within the range of LIMITS_WARN_MIN and LIMITS_WARN_MAX (often referred to as red limits). Yellow limits are often set a certain percentage away from the red limits to give the operator a chance to respond before the red limits are reached. The attribute data type must match the data type of the variable.

5.2.23. LIMITS_WARN_MIN, LIMITS_WARN_MAX

(Optional for data and RV support_data.) Values which define the limits where damage is likely to occur for values outside of this range (often referred to as red limits). Visualization software can use these attributes for indicating limits on plots or other warnings. The attribute data type must match the data type of the variable.

5.2.24. MONOTON

(Optional for epoch variable.) Indicates whether the variable is monotonically increasing or monotonically decreasing. Use of MONOTON is strongly recommended for Epoch/time variables, and it can significantly increase the data retrieval speed. Valid values: "INCREASE" and "DECREASE".

5.2.25. RELATIVE_ERROR

(Optional for time variables.) Relative or random error (in same units as UNITS attribute) - to specify the accuracy of the time stamps relative to each other. This is usually much smaller than ABSOLUTE_ERROR.

5.2.26. REFERENCE_POSITION

(Optional for time variables.) Used to account for time variance with position in the gravity wells and with relative velocity. E.g, "Topocenter" (local), "Geocenter", "Rotating Earth Geoid" (used by CDF_TIME_TT2000). While we could use a combined TimeSystem attribute that defines mission-specific time scales where needed, such as "UTC-at-STEREO-B", it is cleaner to keep them separate as TIME_SCALE = "UTC" and REFERENCE_POSITION = "STEREO-B".

5.2.27. REPRESENTATION_i

(Required [required by Cluster] for data vectors and tensors. PROPOSAL ONLY.) Points to a 1-D metadata variable holding string representations of the i-th dimension of the data variable, e.g., ["x","y","z"] for Cartesian components in the x-y-z order, ["r","p","t"] for spherical polar, ["r",”p”,"z"] for cylindrical polar. Number of REPRESENTATION_i attributes must match the number of dimensions of the data variable. When REPRESENTATION_i are used with LABLAXIS, labels for tensor components are created by concatenating to the LABLAXIS value the corresponding value in the variable pointed to by REPRESENTATION_i, e.g., "Vx", "Vy", "Vz" for a 1-D vector (using LABLAXIS = "V" and REPRESENTATION_1 pointing to a variable holding ["x","y","z"]) or "Pxx", "Pxy", "Pxz", "Pyx", etc., for a tensor of order 2 (using LABLAXIS = "P" and both REPRESENTATION_1 and REPRESENTATION_2 pointing to a variable holding ["x","y","z"]).

5.2.28. RESOLUTION

(Optional for time variables.) Using ISO8601 relative time format, e.g. "1s". Resolution provides the smallest change in time that is measured.

5.2.29. SCALEMIN, SCALEMAX

(Optional for data and RV support_data.) Minimum/maximum values which can be based on the actual values of data found in the dataset or on the probable uses of the data, e.g., plotting multiple files on the same scale. Visualization software can use these attributes as defaults for plotting. The attribute data type must match the data type of the variable.

5.2.30. SCALETYP

(Recommended for data not using SCAL_PTR and for support_data.) Indicates whether the variable should have a "linear" or a "log" scale as a default.

5.2.31. SCAL_PTR

(Recommended for 1-D data not using SCALETYP.) Used for dimensional variables when one value of SCALTYP is not sufficient. SCAL_PTR is used instead of SCALTYP, and will point to a 1-D metadata variable (in the same dataset) with the same dimension size as the original variable. The allowed values are "linear" and "log". The value of the attribute must be the name of a variable in the same dataset.

5.2.32. SI_CONVERSION

(Optional for data and support_data.) The multiplicative factor for converting UNITS value into International System of Units (SI) units. The factor is expressed in the form "number>x", where number is a numerical value and x is the appropriate SI units. The basic SI units are: m (meter), N (newton), kg (kilogram), Pa (pascal), s (second), Hz (hertz), A (ampere), V (volt), K (kelvin), W (watt), rad (radian), J (joule), sr (steradian), C (coulomb), T (tesla), ohm (ohm), mho (mho or seimens), H (henry), and F (farad). Two useful units which are not SI units are: degree (angle), and unitless (no units). An example is SI_CONVERSION = "1e-9>T" which converts the units of magnetic field data expressed in nT to T. Another example is SI_CONVERSION = "1E+3>m/s", which converts a velocity expressed in km/s to m/s.

5.2.33. sig_digits

(Optional [recommended by Cluster] for data.) This attribute provides the number of significant decimal digits required to preserve the precision of the parameter (essential for ASCII conversion).

5.2.34. TENSOR_FRAME

(Optional [required by Cluster] for data vectors and tensors.) The name of the frame (coordinate system) of a tensor, e.g., "GSE". Same as COORDINATE_SYSTEM.

5.2.35. TENSOR_ORDER

(Required [required by Cluster] for data vectors and tensors. PROPOSAL ONLY.) The order of a tensor, i.e. 1 for a vector, 2 for a 3x3 tensor.

5.2.36. TIME_BASE

(Recommended for time variables, important for netCDF files and clarity.) Fixed: "0 AD" (used by CDF_EPOCH and CDF_EPOCH16), "1900", "1970" (POSIX), "J2000" (used by CDF_TIME_TT2000), "4714 BC" (Julian), or "flexible" (provider-defined).

5.2.37. TIME_SCALE

(Recommended for time variables.) "TT" (same as TDT, used by CDF_TIME_TT2000), "TAI" (same as IAT, TT-32.184s), "UTC" (includes leap seconds), "TDB" (same as "SPICE ET"), "EME1950". Default: "UTC".

5.2.38. UNITS

(Required for data and support_data not using UNIT_PTR. Optional for CDF time data type variables. netCDF additionally requires units attribute with the same value.) Is a short string (no more than 20, but preferably 10, 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. For CDF time data type variables, UNITS = "ns" (nanoseconds) for CDF_TIME_TT2000 type, UNITS = "ms" (milliseconds) for CDF_EPOCH type, and UNITS = "ps" (picoseconds) for CDF_EPOCH16.

5.2.39. UNIT_PTR

(Required for 1-D data and support_data not using UNITS.) Points to a 1-D metadata variable (in the same dataset) with the same dimension size, which stores short strings (no more than 20, but preferably 10, characters) 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. If this attribute is used, then UNITS is not used.

5.2.40. VALIDMIN, VALIDMAX

(Required for data and RV support_data.) Hold values which are, respectively, the minimum and maximum valid values for a particular variable that are expected over the lifetime of the mission (not individual files). The value data types must match the data type of the variable.

5.2.41. VAR_NOTES

(Recommended for all variables.) Holds additional information about the variable, caveats, or references to related algorithms, models, and software. (Note: use TEXT global attribute for all information related to the whole dataset and for very long variable descriptions.) For a quality flag variable, this attribute should include complete description of all flag values, while the flag value corresponding to the science quality data can also be included in the UNITS attribute, e.g., UNITS = "0=good".

5.2.42. VAR_TYPE

(Required for all variables.) Identifies ISTP variable type as either:

• "data" - plottable variables of integer or real type (used in CDAWeb and similar software in the list of variables to select from for processing or display).

• "support_data" - support (attached to data) variables of integer or real type.

• "metadata" - labels or other character type variables.

• "ignore_data" - variables to be ignored by applications/APIs.

5.2.43. VARIABLE_PURPOSE

(Optional for data.) List of free text tags/keywords separated by commas that indicate probable uses of the variable and its function. Software can use this attribute to find the primary variables in the dataset, find variables with a common function, indicate variables suitable for specific purposes such as summary plots or educational displays, etc. Tags could indicate a common geophysical quantity to enable matching several variables of the same kind. For instance, all magnetic field variables could be tagged with VARIABLE_PURPOSE = "Magnetic_Field" even though they have different coordinate systems or cadences. Software could use this tag to identify variables with a common theme for easier distinguishing between groups of variables and selecting between them. Suggested tags/keywords include:

• "PRIMARY_VAR" - one of the primary variables in the dataset.

• "EDUCATION" - one of the variables suitable for displaying in an educational context.

• "SUMMARY" - one the variables to display on automatic summary plots.

• "CARTESIAN", "ANGULAR" - distinguish variables by coordinate system.

• "Magnetic_Field", "Electric_Field", etc. - common instrument tag to relate similar variables.

5.2.44. V_PARENT

(Optional for data. For use with derived variables.) Points to a metadata variable which stores the parent variables (including variables from different files/datasets) of a derived variable. The pointed to variable can be dimensional and sized to hold as many parents as necessary. The syntax of each value would be a string in the form Logical_file_id>variable_name.