Units of Measure

The CDF Format Guide requires that UNITS and SI_CONVERSION must be specified for each parameter.

• The following conventions are defined, so that a standard nomenclature is used for these metadata. 
• UNITS attribute
  • This attribute provides a human-readable ASCII string to be used as a plot label
  • No markup or text rendering is assumed, although the formatting rules given below will allow (La)TeX engines to render the strings, requiring at most the insertion of curly braces to protect exponents longer than one character and the replacement of spaces by hard spaces (backslash-space). Other markup languages (e.g., IDL) could similar be employed by a relatively small parsing/translation script.
  • UNITS variable attributes in Level 2 CDF files shall follow the table below. 
  • If a quantity is not shown, it should be expressed in common units, formatted as described below.
  • Such new quantities should be ADDED to the table. This ensures that common entities (e.g., density, velocity, etc.) are expressed in the same units across the mission.
  • The table below provides guides to the abbreviations, nomenclature, and format of the UNITS attribute (see also the Formatting Instructions and rules)
• SI_CONVERSION attribute
  • Gives the conversion from the MMS unit of measure to SI units
  • This attribute allows plotting/analysis tools to combine MMS data with data from other missions which use different units. 
  • Guidelines for SI unit nomenclature are proposed, below.
  • Guidelines for the syntax are also included below (see also the Formatting Instructions and rules)

Convention for unit nomenclature and SI conversion attribute (see table):

• SI unit symbols to be used for SI conversion (rather than SI unit names) without SI prefixes: e.g. T, rather than nT or Tesla; sr, rather than steradians.
  The SI_CONVERSION from nT would then be "1.0e-9>T".
• SI prefixes are allowed in variable units, but not in the converted SI unit (e.g., units of [km] are required for distances, but the SI conversion must be to [m]).
• Note that the SI unit for angles is radians [rad].
  The SI_CONVERSION for angles (in degrees as defined above) would be "0.0174532925>rad"
• Dimensionless variables are required (by ISTP standard) to be a blank character. For consistency the conversion should also be a blank character.
  The SI_CONVERSION for a dimensionless variable would be " > " (note that space characters surround the ">")
• Units that are already SI (e.g. Hz, V) will have a multiplicative factor of 1, so the SI_CONVERSION for spacecraft potential would be "1.0>V".
• Only dimensional units should be used. For example, a number density would have units of [cm^-3] not [#/cm^3]. 

Definitions and Formatting Instructions for Units of Measure used in MMS data product files

The following table lays out the agreed units of measure for common quantities in MMS data, and displays the approved format for the UNITS and SI_CONVERSION variable attributes in the CDF files. The formatting obeys the following rules:

UNITS

1. only letters, numbers, ^, /, (, ),  <space> and -
2. No curly braces or other markup
3. Designed for readability and use as plot labels

SI_CONVERSION

1. only letters, numbers, ^, <space> and -
2. No curly braces or other markup
3. No compound expressions; each individual quantity to be space-separated from the one that follows it.
4. No power of ten prefixes
5. Quantities for which no base SI unit exists or can be reached by a multiplicative factor (e.g., Celsius) to have " > " as their SI_CONVERSION strings.
6. Following practise in other missions, the list of allowed units includes both the list of 7 "base SI" units and the 22 "named units" derived from those (see https://en.wikipedia.org/wiki/International_System_of_Units). 

Additions/Corrections awaiting DSWG decision:

• Earth radius: 6371.2 km

• ASCII Date/Time: ISO8601 standard (e.g. YYYY-MM-DDTHH:MM:SS.SSS or YYYY-DDDTHH:MM:SS.SSS)

MMS Team members are welcome to ADD ADDITIONAL QUANTITIES as they are defined.

---------------------------------------------------------------------------------------------------------------------

The remainder of this page contains earlier versions of this subject and are marked for deletion.

The CDF Format Guide requires that UNITS and SI_CONVERSION must be specified for each parameter.

• It is proposed that conventions should be defined, so that a standard nomenclature is used for these metadata. 
• UNITS attribute
  • units in Level 2 CDF files shall be taken from the list above
  • The units shall be specified as a human-readable ASCII string, using the abbreviations listed above. 
  • guidelines for unit nomenclature are proposed, below.
• SI_CONVERSION attribute
  • Gives the conversion from the MMS unit of measure to SI units
  • This attribute allows for plotting/analysis tools to combine MMS data with data from other missions which use different units. 
  • Guidelines for SI unit nomenclature are proposed, below.
  • Requires guidelines for syntax, which are also included below.

Convention for unit nomenclature and SI conversion attribute (see table above):

• SI unit symbols to be used for SI conversion (rather than SI unit names) without SI prefixes: e.g. T, rather than nT or Tesla; sr, rather than steradians.
  The SI_CONVERSION from nT would then be "1.0e-9>T".
• SI prefixes are allowed in variable units, but not in the converted SI unit (units of [km] are required for distances, but the SI conversion must be to [m]).
• Note that the SI unit for angles is radians [rad]. 
  The SI_CONVERSION for angles (in degrees as defined above) would be "0.0174532925>rad"
• Dimensionless variables are required (by ISTP standard) to be a blank character. For consistency the conversion should also be a blank character.
  The SI_CONVERSION for a dimensionless variable would be " > ".
• Units that are already SI (e.g. Hz, V) will have a multiplicative factor of 1, so the SI_CONVERSION for spacecraft potential would be "1.0>V".

Convention for compound units (see table above): 

• Only dimensional units should be used. For example, a number density would have units of [cm^{-3}] not [#/cm^{3}]. 
• LaTeX math notation is to be used exponents, so the units for acceleration would be [m/s^{2}]

• • This is usable through IDL with the graphics routines from "Coyote's guide" (David Fanning) or the TexToIDL package.
  • This is usable through MATLAB, which directly supports TeX markup in graphics by specifying an interpreter to the text object.
  • This is usable in Python through the graphics package matplotlib, which can use LaTeX to render the text in graphics output for several plotting backends.
  • LaTeX is directly supported by GNUplot, in case anyone still uses that!
  • Where this isn't currently supported is Autoplot, though it may not be difficult for Jeremy to support basic TeX-style markup for units.
  • If LaTeX markup is allowed here then there is no reason people can't use it to give equations in other attributes, which could be handy when defining calculated quantities.

Previous Definitions of Units of Measure used in MMS data product files:

• Earth radius: 6371.2 km

• ASCII Date/Time: ISO8601 standard (e.g. YYYY-MM-DDTHH:MM:SS.SSS or YYYY-DDDTHH:MM:SS.SSS)