CDF Format Guide

1. Introduction

The CdfAttributeManager class provides an interface to examine the CDF Format Guide.

1.1 Purpose and Scope

This document is provided as a reference for construction of standard CDF files. It is intended to complement information available from the Space Physics Data Facility (listed in Sec. 1.2). It lays down REQUIREMENTS and RECOMMENDATIONS for Level 2 (and above) CDF files that are intended for public access, and should be taken as RECOMMENDATIONs for all other mission CDFs. This document is based on discussions with personnel at NASA’s Space Physics Data Facility (SPDF). It is intended to provide sufficient reference material to understand CDF files and the requirements for creating mission-specific CDF files.

1.2 References

Relevant documents that provide background material and support details provided in this guide are listed below:

2. Conventions

Scientific data products that will be shared between SWxSOC entities (e.g. missions, ITFs, IDS groups) or made available to the general research community, stored as CDF data files, are expected to be compatible with CDF version 3.5. Data that will not be shared beyond an individual team may be stored in any format that is convenient for that team.

2.1 Science Product Naming Conventions

Data products will be produced with the following filename format where the individual identifying components are described in Table 2-1. Additionally, to ensure software compatibility between disparate systems, filenames will consist of all lowercase characters. Filenames are used as a system identifier for a logical grouping of data and are also stored in the Logical_file_id global attribute field (see Section 3.1). It is expected that filenames will be created dynamically from the attributes identified in Section 3 of this document.

Filename Format

scId_instrumentId_mode_dataLevel_optionalDataProductDescriptor_startTime_vX.Y.Z.ext

Table 2-1: Filename Component Description

Short Name

Description

Valid Options

scID

Spacecraft ID

hermes, gdc, padre, …

instrumentId

Instrument or investigation identifier shortened to three letter acronym.

eea, mrt, nms, spn, meddea, …

mode

TBS

default, brst, …

dataLevel

The level to which the data product has been processed

l0, l1, ql, l2, l3, l4

optionalDataProductDescriptor

This is an optional field that may not be needed for all products. Where it is used, identifier should be short (e.q. 3-8 characters) descriptors that are helpful to end-users. If a descriptor contains multiple components, underscores are used to separate those components.

An optional time span may be specified as “2s” to represent a data file that spans two seconds. In this case, “10s” and “5m” are other expected values that correspond with ten seconds and 5 minutes respectively.

startTime

The start time of the contained data given in ISO 8601 format.

20230519T000003

vX.Y.Z

The 3-part version number of the data product. Full description of this identifier is provided in Section 3.1.1 of this document.

v0.0.0, v

.ext

The required file extension, where CDF is required.

cdf

2.1.1 Version Numbering Guidelines

The three-part version number contains the interface number, quality number, and bug fix/revision number. The initial release of CDF data that is suitable for scientific publication should begin with “v1.Y.Z”. Each component of the version number is incremented in integer steps, as needed, and Table 3-2 describes the instances in which the value should be incremented. Release “v0.Y.Z” may be used for early development purposes.

Table 2-2: Version Numbering Guidelines

Part

Name

Description

X

Interface Number

Increments in this number represent a significant change to the processing software and/or to the content/structure of the file. These changes may be incompatible with existing code. Increments in this number may require code changes to software.

Y

Quality Number

This number represents a change in the quality of the data in the file, such as change in calibration or increase in fidelity. Changes should not impact software but may require consideration when processing data.

Z

Bug Fix / Revision Number

This number changes to indicate minor changes to the contents of the file due to reprocessing of missing data. Any dependent data products should generally be reprocessed if this value changes.

3. Global Attributes

Global attributes are used to provide information about the data set as an entity. Together with variables and variable attributes, the global attributes make the data correctly and independently usable by someone not connected with the instrument team, and hence, a good archive product.

The required, recommended, and optional global attributes that have been identified for use with ISTP-compliant data products are listed below. Additional global attributes can be defined but they must start with a letter and can otherwise contain letters, numbers, and the underscore character (no other special characters allowed). Note that CDF attributes are case-sensitive and must exactly follow what is shown here.

Detailed descriptions of the attributes listed below are available at the ISTP/IACG Global Attributes Webpage.

3.1 Required Global Attributes

The following global attributes shown in Table 3-1 are required with ISTP-compliant data products. For each attribute the following information is provided:

  • description: (str) A brief description of the attribute

  • default: (str) The default value used if none is provided

  • required: (bool) Whether the attribute is required by ISTP standards

Note that this table is derived from sammi/data/default_global_cdf_attrs_schema.yaml

Table 3-1: Required Global Attributes

Attribute

default

description

required

Acknowledgement

Text string at PI disposal allowing for information on expected acknowledgment if data is citable. Example: “Cite McComas et al (2016),doi:10.1007/s11214-014-0059-1”

False

Data_level

This attribute is used in file name creation and records the level of processsing done on the dataset. Valid values: - l0>Level 0 - l1>Level 1 - l2>Level 2 - l3>Level 3 - l4>Level 4 - ql>Quicklook

False

Data_product_descriptor

This is an optional field that may not be needed for all products. Where it is used, identifier should be short (e.q. 3-8 characters) descriptors that are helpful to end- users. If a descriptor contains multiple components, underscores are used to separate those components.

False

Data_type

This attribute identifies the data type of the CDF data set. Both a long name and a short name are given. For ISTP exchangeable data products the values are “Kn>Key Parameter” for approximately minute averaged survey data, and “Hn>High Resolution data” for certified data of higher resolution than Key Parameters. Key Parameters can run from 0 to 9 to allow for more than one kind of data product. For Cluster/CSDS this can either be “SP>Summary Parameter” or “PP>Prime Parameter”. Other possible data types may be defined in future. If any of these data sets are modified or used to produce derived products, the data type should be, e.g., “Mn>Modified Data n”, where n is from 0 to 9. Example: “L2-Summary>level 2 summary”

True

Data_version

This attribute identifies the version of a particular CDF data file for a given date, e.g., the file GE_K0_MGF_19920923_V01 is the first version of data for 1992 September 23. Each time this particular data file is reproduced - for recalibration or other reasons - the Data_version is incremented by 1. Data_version always starts at ‘1’. Example: “07”, “v1.0.3”

True

Descriptor

This attribute identifies the name of the instrument or sensor that collected the data. Both a long name and a short name are given. An example for ISTP is “EPI>Energetic Particles and Ion Composition”. The short name should be limited to from 2 to 4 characters for consistency with ISTP. This attribute should be single valued. For example, from the HERMES mission, the following are valid values: - EEA>Electron Electrostatic Analyzer - MERIT>Miniaturized Electron pRoton Telescope - NEMISIS> Noise Eliminating Magnetometer In a Small Integrated System - SPAN-I>Solar Probe Analyzer for Ions

True

Discipline

This attribute describes both the science discipline and sub discipline. The list for space physics is: - “Space Physics>Magnetospheric Science”, - “Space Physics>Interplanetary Studies”, - “Space Physics>Ionospheric Science”

True

DOI

Unique Digital Identifier (DOI) as a persistent identifier for the dataset, of the form https://doi.org/<PREFIX>/<SUFFIX> with the <PREFIX> identifying the DOI registration authority and the <SUFFIX> identifying the dataset. The DOI should point to a landing page for additional information about the dataset. DOIs are typically created by the SPASE naming authority or archive.

False

File_naming_convention

source_datatype_descriptor_yyyyMMdd
If File_naming_convention was not set, it uses default setting:

source_datatype_descriptor_yyyyMMdd

False

Generated_by

This attribute allows for the generating data center/group to be identified.

False

Generation_date

Date stamps the creation of the file using the syntax yyyymmdd, e.g., “

False

HTTP_LINK

This attribute stores the URL for the PI or CoI web site holding on-line data. This attribute is used in conjunction with “LINK_TEXT” and “LINK_TITLE”. There can be up to 5 entries for each - there MUST be a corresponding entry of “LINK_TEXT” and “LINK_TITLE” for each “HTTP_LINK” entry. CDAWeb will then link to the URL given by “HTTP_LINK” using the “LINK_TITLE” and the description in “LINK_TEXT”, on the CDAWeb Data Explorer page. For example: - “LINK_TEXT” = 3-sec MGF magnetic field 1 Sep 1993 through 30 Sep 2015 available at - “LINK_TITLE” = ISAS DARTS - “HTTP_LINK” = https://www.darts.isas.jaxa.jp/stp/geotail/

False

Instrument_mode

TBS

False

Instrument_type

This attribute is used to facilitate making choices of instrument type. More than one entry is allowed. Acceptable values include: - Magnetic Fields (space) - Particles (space) - Plasma and Solar Wind - Ephemeris -> Ephemeris/Attitude/Ancillary

True

LINK_TEXT

This attribute stores text describing on-line data available at PI or CoI web sites. This attribute is used in conjunction with “LINK_TITLE” and “HTTP_LINK”. There can be up to 5 entries for each - there MUST be a corresponding entry of “LINK_TITLE” and “HTTP_LINK” for each “LINK_TEXT” entry. CDAWeb will then link to the URL given by “HTTP_LINK” using the “LINK_TITLE” and the description in “LINK_TEXT”, on the CDAWeb Data Explorer page. For example: - “LINK_TEXT” = 3-sec MGF magnetic field 1 Sep 1993 through 30 Sep 2015 available at - “LINK_TITLE” = ISAS DARTS - “HTTP_LINK” = https://www.darts.isas.jaxa.jp/stp/geotail/

False

LINK_TITLE

This attribute stores the title of the web site holding on-line data available at PI or CoI web sites. This attribute is used in conjunction with “LINK_TEXT” and “HTTP_LINK”. There can be up to 5 entries for each - there MUST be a corresponding entry of “LINK_TEXT” and “HTTP_LINK” for each “LINK_TITLE” entry. CDAWeb will then link to the URL given by “HTTP_LINK” using the “LINK_TITLE” and the description in “LINK_TEXT”, on the CDAWeb Data Explorer page. For example: - “LINK_TEXT” = 3-sec MGF magnetic field 1 Sep 1993 through 30 Sep 2015 available at - “LINK_TITLE” = ISAS DARTS - “HTTP_LINK” = https://www.darts.isas.jaxa.jp/stp/geotail/

False

Logical_file_id

This attribute stores the name of the CDF file using the ISTP naming convention (source_name / data_type / descriptor / date / data_version), e.g., GE_K0_MGF_19920923_V01. This attribute is required (1) to allow storage of the full name on IBM PCs, and (2) to avoid loss of the original source in the case of accidental (or intentional) renaming. For CDFs created on the ISTP CDHF, the correct Logical_file_id will be filled in by an ICSS support routine.

True

Logical_source

This attribute carries source_name, data_type, and descriptor information. Used by CDAWeb. It is composed of the following values: - source_name - (e.g. spacecraft identifier) - descriptor - (e.g. instrument identifier - see Section Error! Reference source not found.) - data_type - (e.g. mode, data level, and optional data product descriptor - value come from ‘Data_type’ attribute)

True

Logical_source_description

This attribute writes out the full words associated with the encrypted Logical_source above, e.g., “Level 1 Dual Electron Spectrometer Survey Data”. Users on CDAWeb see this value on their website.

True

Mission_group

This attribute has a single value and is used to facilitate making choices of source through CDAWeb. Valid values include (but are not restricted to): - Geotail - IMP8 - Wind - Geosynchronous Investigations - Ground-Based Investigations

True

MODS

This attribute is an NSSDC standard global attribute which is used to denote the history of modifications made to the CDF data set. The MODS attribute should contain a description of all significant changes to the data set. This attribute is not directly tied to Data_version, but each version produced will contain the relevant modifications. This attribute can have as many entries as necessary to contain the desired information.

False

Parents

This attribute lists the parent CDF(S) for files of derived and merged data sets. Subsequent entry values are used for multiple parents. The syntax for a CDF parent would be e.g. “CDF>logical_file_id”.

False

PI_affiliation

This attribute value should include a recognizable abbreviation.

True

PI_name

This attribute value should include first initial and last name.

True

Project

This attribute identifies the name of the project and indicates ownership. For ISTP missions and investigations, the value used is “ISTP>International Solar-Terrestrial Physics”. For the Cluster mission, the value is “STSP Cluster>Solar Terrestrial Science Programmes, Cluster”. Other acceptable values are “IACG>Inter-Agency Consultative Group”, “CDAWxx>Coordinated Data Analysis Workshop xx”, and “SPDS>Space Physics Data System”. Others may be defined in future. This attribute can be multi-valued if the data has been supplied to more than one project.

True

Rules_of_use

Text containing information on, {it e.g.} citability and PI access restrictions. This may point to a World Wide Web page specifying the rules of use.

False

Skeleton_version

This is a text attribute containing the skeleton file version number. This is a required attribute for Cluster, but for IACG purposes it exists if experimenters want to track it.

False

Software_version

This is a required attribute for Cluster, but for IACG purposes it exists if experimenters want to track it.

False

Source_name

This attribute identifies the mission or investigation that contains the sensors. For ISTP, this is the mission name for spacecraft missions or the investigation name for ground-based or theory investigations. Both a long name and a short name are provided. This attribute should be single valued.

True

spase_DatasetResourceID

Unique dataset identifier assigned by SPASE, of the form spase://<NAMING_AUTHORITY>/<UNIQUE_ID>, where <UNIQUE_ID> is the ID assigned to the SPASE resource record for the dataset in the SPASE system by a SPASE <NAMING_AUTHORITY>. The SPASE resource record provides metadata about the dataset, including pointers to locations holding the data.

False

Start_time

The start time of the contained data given in YYYYMMDD_hhmmss

False

TEXT

This attribute is an SPDF standard global attribute, which is a text description of the experiment whose data is included in the CDF. A reference to a journal article(s) or to a World Wide Web page describing the experiment is essential and constitutes the minimum requirement. A written description of the data set is also desirable. This attribute can have as many entries as necessary to contain the desired information. Typically, this attribute is about a paragraph in length and is not shown on CDAWeb. CDAWeb is the web portal for access to SPDF data, available at https://cdaweb.gsfc.nasa.gov.

True

Time_resolution

This attribute identifies the time resolution of the data in the CDF file. The time resolution is given in seconds. For example, “3 seconds” for 3-second resolution data.

False

TITLE

This attribute is an NSSDC standard global attribute which is a title for the data set, e.g., “ Geotail EPIC Key Parameters”.

False

Validate

Details to be specified. This attribute is written by software for automatic validation of features such as the structure of the CDF file on a simple pass/fail criterion. The software will test that all expected attributes are present and, where possible, have reasonable values. The syntax is likely to be of the form “test>result>where-done>date”. It is not the same as data validation.

False

3.3 Optional Attributes

Table 3-3: Optional Attributes

Attribute

Description

Parents

This attribute lists the parent data files for files of derived and merged data sets. The syntax for a CDF parent is: “CDF>logical_file_id”. Multiple entry values are used for multiple parents.

Skeleton_version

This is a text attribute containing the skeleton file version number.

Rules_of_use

Text containing information on citability and/or PI access restrictions. This may point to a World Wide Web page specifying the rules of use. Rules of Use are determined on both a mission and instrument basis, at the discretion of the PI.

Time_resolution

Specifies time resolution of the file, e.g., “3 seconds”.

4. Variables

There are three types of variables that should be included in CDF files:

  • data,

  • support data,

  • metadata.

Additionally, required attributes are listed with each variable type listed below.

To facilitate data exchange and software development, variable names should be consistent across instruments and spacecraft. Additionally, it is preferable that data types are consistent throughout all data products (e.g. all real variables are CDF_REAL4, all integer variables are CDF_INT2, and flag/status variables are UINT2). This is not to imply that only these data types are allowable within CDF files. All CDF supported data types are available for use by SWxSOC affiliated projects.

For detailed information and examples, please see the ISTP/IACG Webpage

4.1 Data

These are variables of primary importance (e.g., density, magnetic field, particle flux). Data is always time (record) varying but can be of any dimensionality or CDF supported data type. Real or Integer data are always defined as having one element.

4.1.1 Naming

SWxSOC affiliated data variables must adhere to the following naming convention * scId_instrumentId_paramName

An underscore is used to separate different fields in the variable name. It is strongly recommended that variable names employ further fields, qualifiers and information designed to identify unambiguously the nature of the variable, instrument mode and data processing level, with sufficient detail to lead the user to the unique source file which contains the variable. It is recommended that these follow the order shown below.

  • scId_instrumentId_paramName[_coordSys][_paramQualifier][_subModeLevel][_mode][_dataLevel]

where the required fields are described in Table 4-1 and the optional fields are described in Table 4-2. An example data variable would be hermes_eea_n_gse_l2.

Table 4-1: Required Data Variable Fields

Required Field Name

Description

scId

Spacecraft identifier, see Table 2-1 for acceptable values

instrumentId

Instrument or investigation identifier, see Table 2-1 for acceptable values and note the caveats listed in Section 4.1.1.1.

paramName

Data parameter identifier, a short (a few letters) representation of the physical parameter held in the variable.
Table 4-2: Optional Data Variable Fields

Optional Field Name

Description

coordSys

An acronym for the coordinate system in which the parameter is cast.

paramQualifier

Parameter descriptor, which may include multiple components separated by a “_” as needed (e.g. “pa_0” indicates a pitch angle of 0).

subModeLevel

Qualifier(s) to include mode and data level information supplementary to the following two fields.

mode

See Table 2-1 for acceptable values.

dataLevel

See Table 2-1 for acceptable values.
4.1.1.1 Caveats

Note the following caveats in the variable naming conventions:

  • CDF variable names must begin with a letter and can contain numbers and underscores, but no other special characters.

  • In general, the instrumentId field follows the convention used for file names as defined in Section 2.1. However, since variable names cannot contain a hyphen, an underscore should be used instead of a hyphen when needing to separate instrument components. For instance, “eea-ion” is a valid instrumentId in a filename but when used in a variable name, “eea_ion” should be used instead.

  • To ensure software compatibility between disparate systems, parameter names will consist of all lowercase characters.

4.1.2 Required Epoch Variable

All ISTP-compliant CDF data files must contain at least one variable of data type CDF_TIME_TT2000, typically named “Epoch”. This variable should normally be the first variable in each CDF data set. All time varying variables in the CDF data set will depend on either this “epoch” variable or on another variable of type CDF_TIME_TT2000 (e.g. hermes_eea_epoch). More than one CDF_TIME_TT2000 type variable is allowed in a data set to allow for more than one time resolution, using the required DEPEND_0 attribute (see Section 5.5) to associate a time variable to a given data variable. It is recommended that all such time variables use “epoch” within their variable name.

For ISTP, but not necessarily for all mission’s data, the time value of a record refers to the center of the accumulation period for the record if the measurement is not an instantaneous one. Time variables used as DEPEND_0 are strongly recommended to have DELTA_PLUS_VAR and DELTA_MINUS_VAR attributes which delineate the time interval over which the data was sampled, integrated, or otherwise representative of. This also locates the timetag within that interval.

The epoch datatype, CDF_TIME_TT2000, is defined as an 8-byte signed integer with the characteristics shown in Table 5-3.

Table 4-3: Characteristics of CDF_TIME_TT2000

Name

Example

time_base

J2000 (Julian date 2451545.0 TT or 2000 January 1, 12h TT)

resolution

nanoseconds

time_scale

Terrestrial Time (TT)

units

nanoseconds

reference_position

rotating Earth Geoid

Given a current list of leap seconds, conversion between TT and UTC is straightforward (TT = TAI + 32.184s; TT = UTC + deltaAT + 32.184s, where deltaAT is the sum of the leap seconds since 1960; for example, for 2009, deltaAT = 34s). Pad values of -9223372036854775808 (0x8000000000000000) which corresponds to 1707-09-22T12:13:15.145224192; recommended FILLVAL is same.

It is proposed that the required data variables VALIDMIN and VALIDMAX are given values corresponding to the dates 1990-01-01T00:00:00 and 2100-01-01T00:00:00 as these are well outside any expected valid times.

4.1.3 Required Attributes: Data Variables

Data variables require the following attributes:

  • CATDESC

  • DEPEND_0

  • DEPEND_i [for dimensional data variables]

  • DISPLAY_TYPE

  • FIELDNAM

  • FILLVAL

  • FORMAT or FORM_PTR

  • LABLAXIS or LABL_PTR_i

  • SI_CONVERSION

  • UNITS or UNIT_PTR

  • VALIDMIN and VALIDMAX

  • VAR_TYPE

In addition, the following attributes are strongly recommended for vectors, tensors and quaternions which are held in or relate to a particular coordinate system:

  • COORDINATE_SYSTEM

  • TENSOR_ORDER

  • REPRESENTATION_i

  • OPERATOR_TYPE [for quaternions]

4.1.4 Attributes for DEPEND_i Variables

Variables appearing in a data variable’s DEPEND_i attribute require a minimal set of their own attributes to fulfill their role in supporting the data variable. The standard SUPPORT_DATA variable attributes are listed in Section 4.2.2. Other standard variable attributes are optional.

4.2 Support Data

These are variables of secondary importance employed as DEPEND_i variables as described in section 4.1.3 (e.g., time, energy_bands associated with particle flux), but they may also be used for housekeeping or other information not normally used for scientific analysis.

4.2.1 Naming

Support data variable names must begin with a letter and can contain numbers and underscores, but no other special characters. Support data variable names need not follow the same naming convention as Data Variables (4.1.1) but may be shortened for convenience.

4.2.2 Required Attributes: Support Variables

  • CATDESC

  • DEPEND_0 (if time varying)

  • FIELDNAM

  • FILLVAL (if time varying)

  • FORMAT/FORM_PTR

  • LABLAXIS or LABL_PTR_i

  • SI_CONVERSION

  • UNITS/UNIT_PTR

  • VALIDMIN (if time varying)

  • VALIDMAX (if time varying)

  • VAR_TYPE = “support_data”

Other attributes may also be present.

4.3 Metadata

These are variables of secondary importance (e.g. a variable holding “Bx”, “By”, “Bz” to label magnetic field). Metadata are usually text strings as opposed to the numerical values held in DEPEND_i support data.

4.3.1 Naming

Metadata variable names must begin with a letter and can contain numbers and underscores, but no other special characters. Metadata variable names need not follow the same naming convention as Data Variables (4.1.1) but may be shortened for convenience.

4.3.2 Required Attributes: Metadata Variables

  • CATDESC

  • DEPEND_0 (if time varying, this value must be “Epoch”)

  • FIELDNAM

  • FILLVAL (if time varying)

  • FORMAT/FORM_PTR

  • VAR_TYPE = metadata

4.4 Variable Attribute Schema

The following variable attributes shown in Table 5-4 are required with ISTP-compliant data products. For each attribute the following information is provided:

  • description: (str) A brief description of the attribute

  • required: (bool) Whether the attribute is required by ISTP standards

  • valid_values: (list) List of allowed values the attribute can take for ISTP-compliant products, if applicable

  • alternate: (str) An additional attribute name that can be treated as an alternative of the given attribute. Not all attributes have an alternative and only one of a given attribute or its alternate are required.

  • var_types: (str) A list of the variable types that require the given attribute to be present.

Note that this table is derived from sammi/data/default_variable_cdf_attrs_schema.yaml

Table 4-4 SWxSOC Variable Attribute Schema

Attribute

alternate

description

required

valid_values

var_types

TIME_BASE

fixed (0AD, 1900, 1970 (POSIX), J2000 (used by CDF_TIME_TT2000), 4714 BC (Julian)) or flexible (provider-defined)

False

RESOLUTION

Using ISO8601 relative time format, for example: “1s” = 1 second. Resolution provides the smallest change in time that is measured.

False

TIME_SCALE

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]

False

REFERENCE_POSITION

Topocenter (local), Geocenter , rotating Earth geoid (used by CDF_TIME_TT2000). Reference_Position is optional metadata to account for time variance with position in the gravity wells and with relative velocity. While we could use a combined TimeSystem attribute that defines mission-specific time scales where needed, such as UTC-at-STEREO-B, it’s cleaner to keep them separate as Time_Scale=UTC and Reference_Position=STEREO-B.

False

LEAP_SECONDS_INCLUDED

comma-delimited list (within brackets) of leap seconds included in the form of a lists of ISO8601 times when each leap second was added, appended with the size of the leap second in ISO8601 relative time (+/- time, most commonly: “+1s”) [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 34 (in 2009) 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 pecific UTC but continues on without leap seconds in TAI mode; this is basically what missions that don’t add leap seconds are doing. $ cat tai-utc.dat | awk ‘ORS=”,” { val = $7 - prev } {prev = $7} { print $1$2”01+” val “s” }’

False

ABSOLUTE_ERROR

Absolute or systematic error, in same units as Units attribute.

False

RELATIVE_ERROR

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.

False

BIN_LOCATION

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. Since clock readings are usually truncated, the real value may be closer to 0.0.

False

AVG_TYPE

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: - 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

False

CATDESC

This is a human readable description of the data variable. Generally, this is an 80-c haracter string which describes the variable and what it depends on.

True

data, support_data, metadata

CDELTi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value field shall contain a floating point number giving the partial derivative of the coordinate specified by the CTYPEi keywords with respect to the pixel index, evaluated at the reference point CRPIXi, in units of the coordinate specified by the CTYPEi keyword.

False

CNAMEi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value shall contain a charachter string represnting the name of the i’th axis. The name is used for comment/documentation purposes only and is not used as a part of the i’th axis coordinate transformations.

False

COORDINATE_SYSTEM

All variables for which the values are dependent on the system of coordinates are strongly recommended to have this attribute. This includes both full vectors, tensors, etc. or individual values, e.g. of an angle with respect to some axis. The attribute is a text string which takes the form: “XXX[>optional long name]”

False

CTYPEi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value field shall contain a character string, giving the name of the coordinate represented by axis i.

False

CUNITi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value shall be the units along axis i, compatible with CTYPEi to be used for scaling and coordinate transformations along the i’th axis.

False

CRPIXi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value field shall contain a floating point number, identifying the location of a reference point along axis i, in units of the axis index. This value is based upon a counter that runs from 1 to NAXISn with an increment of 1 per pixel. The reference point value need not be that for the center of a pixel nor lie within the actual data array. Use comments to indicate the location of the index point relative to the pixel.

False

CRVALi

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. This metadata attribte should be used for the i’th dimension (1-based) and reapeated for all WCSAXES dimensions. The value field shall contain a floating point number, giving the value of the coordinate specified by the CTYPEn keyword at the reference point CRPIXi.

False

DELTA_PLUS_VAR

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, 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. The value of the attribute must be a variable in the same CDF data set.

False

DELTA_MINUS_VAR

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, 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. The value of the attribute must be a variable in the same CDF data set.

False

DEPEND_0

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.

True

data

DEPEND_i

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. It is strongly recommended that DEPEND_i variables hold values in physical units.

False

DERIVN

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.

False

DICT_KEY

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

False

DISPLAY_TYPE

This tells automated software, such as CDAWeb, how the data should be displayed.

True

time_series time_series>noerrorbars spectrogram stack_plot image no_plot

data

FIELDNAM

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.

True

data, support_data, metadata

FILLVAL

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. Fill values are automatically supplied in the ISTP CDHF ICSS environment (ICSS_KP_FILL_VALUES.INC) for key parameters produced at the CDHF. The FILLVAL data type must match the data type of the variable.

True

data, support_data, metadata

FORMAT

FORM_PTR

This field allows software to properly format the associated data when displayed on a screen or output to a file. Format can be specified using either Fortran or C format codes. For instance, “F10.3” indicates that the data should be displayed across 10 characters where 3 of those characters are to the right of the decimal. For a description of FORTRAN formatting codes see the docs here: https://docs.oracle.com/cd/E19957-01/805-4939/z40007437a2e/index.html

True

data, support_data, metadata

FORM_PTR

FORMAT

The value of this field is a variable which stores the character string that represents the desired output format for the associated data.

False

LABLAXIS

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. Only one of LABLAXIS or LABL_PTR_i should be present.

True

data, support_data

LABL_PTR_i

LABLAXIS

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 value of the attribute must be a variable in the same CDF data set and is generally 6-10 characters. Only one of LABLAXIS or LABL_PTR_i should be present.

False

LIMITS_WARN_MIN

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

False

LIMITS_WARN_MAX

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

False

LIMITS_NOMINAL_MIN

Values which define the range of nominal operations and where values outside the range of these values 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. 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 values data type must match the data type of the variable.

False

LIMITS_NOMINAL_MAX

Values which define the range of nominal operations and where values outside the range of these values 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. 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 values data type must match the data type of the variable.

False

MJDREF

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. The value shall contain a floating point number representing the reference time position of the time stamps along the 0’th axis of the measurement.

False

MONOTON

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.

False

INCREASE DECREASE

OPERATOR_TYPE

This has been introduced to describe HERMES quaternions (see Section 5.2 below). It has allowed values “UNIT_QUATERNION” or “ROTATION_MATRIX” although other values could be added. Unit quaternions correspond to pure spatial rotations.

False

REPRESENTATION_i

This strongly recommended attribute holds the way vector or tensor variables are held, e.g., as Cartesian or polar forms, and their sequence order in the dimension i in which they are held. Cartesians are indicated by x,y,z; polar coordinates by r (magnitude), t (theta - from z-axis), p (phi - longitude or azimuth around z-axis from x axis), l (lambda = latitude). Examples follow.

False

SCALEMIN

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.

False

SCALEMAX

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.

False

SCALETYP

is a text string which describes the type of scaling that should be used for the variable. The value of this attribute can be used with application software. Examples are listed below: - linear - log

False

SCAL_PTR

The value of this field is a variable which stores the character string that represents the desired scaling type for the associated data. The allowed values are linear and log. The value of the attribute must be a variable in the same CDF data set.

False

sig_digits

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.

False

SI_CONVERSION

The conversion factor to SI units. This is the factor that the variable must be multiplied by in order to convert it to generic SI units. This parameter contains two text fields separated by the “>” delimiter. The first component is the conversion factor and the second is the standard SI unit. Units are defined according to their standard SI symbols (ie. Tesla = T, Newtons = N, Meters = m, etc.) For data variables that are inherently unitless, and thus lack a conversion factor, this data attribute will be “ > “ where ‘ ‘ is a blank space and the quotation marks are not included. Units which are not conveniently transformed into SI should follow the blank syntax “ > “ described above.

False

data, support_data

TENSOR_ORDER

All variables which hold physical vectors, tensors, etc., or sub-parts thereof, are strongly recommended to have their tensorial properties held by this numerical value. Vectors have TENSOR_ORDER=1, pressure tensors have TENSOR_ORDER=2, etc. Variables which hold single components or sub-parts of a vector or tensor, e.g., the x-component of velocity or the three diagonal elements of a tensor, use this attribute to establish the underlying object from which they are extracted. TENSOR_ORDER is a number, usually held as a CDF_INT4, rather than a character string.

False

TIMEDEL

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. The value shall contain a floating point number representing the resolution of the time stamps along the 0’th axis of the measurement. The TIMEDEL should match the CRDELi along the time axis of the measurement.

False

TIMEUNIT

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. The value shall contain a character string giving the units of the time stamps along the 0’th axis of the measurement. The TIMEUNIT should match the CUNITi along the time axis of the measurement

False

UNITS

UNIT_PTR

A 6-20 character string that identifies the units of the variable (e.g. nT for magnetic field). Use a blank character, rather than “None” or “unitless”, for variables that have no units (e.g., a ratio or a direction cosine).

True

data, support_data

UNIT_PTR

UNITS

The value of this field is a variable which stores short character strings which identify the units of the variable. Use a blank character, rather than “None” or “unitless”, for variables that have no units (e.g., a ratio or a direction cosine). The value of this attribute must be a variable in the same CDF data set.

False

VALIDMIN

The minimum value for a particular variable that is expected over the lifetime of the mission. Used by application software to filter out values that are out of range. The value must match the data type of the variable.

True

data, support_data

VALIDMAX

The maximum value for a particular variable that is expected over the lifetime of the mission. Used by application software to filter out values that are out of range. The value must match the data type of the variable.

True

data, support_data

VAR_NOTES

A text string that provides additional information about the variable. This information can include the source of the data, the method of calculation, or any other information that is relevant to the variable.

False

VAR_TYPE

Used in CDAWeb to indicate if the data should be used directly by users.

True

data support_data metadata ignore_data

data, support_data, metadata

VARIABLE_PURPOSE

are a list of tags/keywords separated by commas that indicate probable uses of the variable and its function. Software can use these attributes 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. The values are always in a character string. 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

False

V_PARENT

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.

False

WCSAXES

This is a FITS WCS Keyword being repurposed for handling WCS transformations with high-dimensional or spectral CDF data variables. The value field shall contain a non-negative integer no greater than 999, representing the number of axes in the associated data array.

False