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. Only base SI units, 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 its SI_CONVERSION string.

more to follow ... 

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)

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

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.