ERDDAP > Convert > Units
Convert UDUNITS to/from Unified Code for Units of Measure (UCUM)
Two common standards for writing units of measure are:- UDUNITS
- from
Unidata,
which is used in
COARDS,
CF, and
NetCDF
data files. For example,
UDUNITS has many options for degrees Celsius, including degree_C and degC.
- UCUM - the Unified Code for Units of Measure. OGC services such as SOS, WCS, and WMS often refer to UCUM as UOM (Units Of Measure). For example, UCUM has just one case-sensitive option for degrees Celsius: "Cel".
Or, bypass this web page and do conversions from within a computer program, script, or web page.
- On this ERDDAP, most/all datasets use UDUNITS.
- In tabledap requests, you can request UDUNITS or UCUM.
- Always check the results from the converters.
- This isn't a validator. If the UDUNITS or UCUM units string is valid, the converter should return a correct, valid, converted string. If the UDUNITS (or UCUM) units string isn't valid, the converter will do its best and won't generate an error message. Invalid and unrecognized UDUNITS (or UCUM) names will be passed through unchanged. Emphasis is placed on preserving information rather than sanitizing or validating the units strings.
- The UDUNITS to UCUM converter can convert all UDUNITS-1 units Strings and most of UDUNITS-2.
- The UCUM to UDUNITS converter can convert almost all case-sensitive UCUM units Strings.
- For conversions in either direction, the results will be standardized in the sense that slight variations in the aliases and the syntax of the input will result in the same output. For example, UDUNITS="meter per second", "meters/second", "m.s^-1", and "m s-1" will all return UCUM="m.s-1". There is nothing special, unique, or better about the specific aliases or syntax of the standardized output compared to other aliases or syntax, except that is similar to the "canonical" form returned by the UDUNITS software.
- The "Standardize UDUNITS" option works well for valid UDUNITS strings and reasonably well for non-standard / invalid UDUNITS strings. Note that this is a simple standardization (e.g., "joule", "joules", and "J" all return "J") as opposed to the "canonical" form offered by the UDUNITS software (which, for example, converts all of the joule aliases to "kg.m2.s-2").
- If you think that a converter did a conversion incorrectly, first make sure that the input string is valid. If you think the input string is valid, please email the details to erd dot data at noaa dot gov .
- See the detailed comparison of UDUNITS and UCUM syntax and units below.
- DISCLAIMER OF LIABILITY - No person or organization associated with this website makes any warranty, express or implied, including warranties of merchantability and fitness for a particular purpose, or assumes any legal liability for the accuracy, completeness, or usefulness, of any information at this website.
Want To Do Conversions from within a Computer Program, Script, or Web Page?
If you change the extension of this web page's URL from .html to .txt, and add the query UDUNITS=udunitsString, UCUM=ucumString, or STANDARDIZE_UDUNITS=udunitsString, ERDDAP will respond with just the text result.- An example which converts UDUNITS to UCUM is
https://spraydata.ucsd.edu/erddap/convert/units.txt?UDUNITS=degC%20meter-1
- An example which converts UCUM to UDUNITS is
https://spraydata.ucsd.edu/erddap/convert/units.txt?UCUM=Cel.m-1
- An example which standardizes UDUNITS is
https://spraydata.ucsd.edu/erddap/convert/units.txt?STANDARDIZE_UDUNITS=degC/meter
Comparison of UDUNITS and UCUM Syntax
Issue | UDUNITS | UCUM | UDUNITS → UCUM Converter | UCUM → UDUNITS Converter |
---|---|---|---|---|
Character Set | UDUNITS-1 uses plain ASCII. UDUNITS uses ASCII, ISO 8859-1 (Latin-1), and the UTF-8 encoding of ISO 10646 (Unicode). | Plain ASCII | All UDUNITS units with just ASCII and ISO 8859-1 characters are converted. The few units with other characters are not converted | Most UCUM units are converted. |
case-sensitive | Yes. When different capitalizations are allowed, the variants are explicitly defined. | Yes. The converters work with the case-sensitive ("c/s") form of UCUM units. | (No changes needed) | (No changes needed) |
Plurals and Aliases | Supports plurals and aliases for the same unit. | Uses just one abbreviation/acronym for each unit. | The various plurals and aliases are converted to the corresponding UCUM unit. Unrecognized UDUNITS names are converted to comments. | This method tries to return common, short, single (not plural) UDUNITS aliases. Unrecognized UCUM names are left unchanged. |
metric prefixes
(e.g., "kilo" and 'k' mean "times 1000"; "µ" and 'u' mean "times 10^-6") |
Supported (see UDUNITS udunits2-prefixes.xml) | Supported (see the c/s column of the prefix symbol table) | The prefix is converted to its acronym (e.g., 'u') | The prefix is left as its acronym (e.g., 'u') |
multiplication operators | space (most common), '-' (a typo in the spec???), '.', '*', '·' | '.' | space, '*', and '·', are converted to '.' | always converted to a space (for consistency) |
division operators | '/', "per", "PER" | '/' | "per" and "PER" are converted to negative exponents. | (No changes needed) |
exponent operators | "**", '^', nothing (e.g., m-2 = m^-2) | '*' (really!), '^' (only in numbers), nothing (e.g., m-2) | "**" is converted to nothing (or '^' within numbers, e.g., 10^-6). | always converted to '^' (for consistency). |
operator precedence | Exponents are highest. Then multiplication and division are evaluated left to right. | Exponents are highest. Then multiplication and division are evaluated left to right. | (No changes needed) | (No changes needed) |
numbers | integer and floating point (e.g., 1.23456E-5) | integer only | Floating point numbers are converted to rational numbers (e.g., 12.34 becomes 1234.10^-2 (remember that '.' means "times") | Numbers are converted to integers or floating point numbers (e.g., 1.23456E-5). |
_ (underscore) | Used within individual unit names. | Used to indicate a subscript annotation within a unit name (e.g., "mo_g" for a Gregorian month) | (No changes needed) | (No changes needed) |
' (apostrophe) | Not used. | Used to separate words in a multi-word name (e.g., "[todd'U]" for a Todd unit) | (No changes needed) | (No changes needed) |
( ) | Used to group items. | Used to group items. | (No changes needed) | (No changes needed) |
[ ] | Not used. | Used to enclose groups of symbols that should be treated as a group (e.g., "[in_i]" for an international inch) | (No changes needed) | (No changes needed) |
{ } | Not used. | Used for annotations (e.g., "%{vol}" for percent by volume). | (No changes needed) | If the comment is defined in the UCUM standard, it will be converted. If the term isn't defined, { } will be converted to ( ). |
Comparison of UDUNITS and UCUM Units
For most units, there is a one-to-one correspondence between units in UDUNITS and UCUM. But there are a few difficulties and special cases:Units | UDUNITS | UCUM | UDUNITS → UCUM Converter | UCUM → UDUNITS Converter |
---|---|---|---|---|
count | "count" is a base unit. | No exact equivalent, since it is a dimensionless non-unit. | "count" is converted to "{count}" (a dimensionless annotation). | "{count}" is converted to "count". |
different types of degrees | UDUNITS treats degF, degC, degK, degree_north, degree_east, degree_west, degree_true, and their aliases as separate units. Some standards (e.g., COARDS and CF), use degree_east and degree_north to identify the longitude and latitude variables in a data file. | UCUM recognizes separate temperature degree units (e.g, [degF], Cel, K), but not separate direction degree units. They are all represented by "deg". | To distinguish between the various direction degree units, the converter adds a comment to direction degree units (e.g., "degree_north" becomes "deg{north}"). | If you append a comment( {east}, {north}, {west}, or {true}), the converter will convert to a direction unit (e.g., "deg{north}" becomes "degree_north"); otherwise, there is no way for the converter to generate direction degree units, so "deg" is converted to "degree". |
specific times | UDUNITS has a system to specify specific times as
"units since ISO8601Time", e.g., "seconds since 1970-01-01T00:00:00Z". | UCUM doesn't seem to have a system to specify specific times. | The converter converts, e.g.,
"seconds since 1970-01-01T00:00:00Z" to "s{since 1970-01-01T00:00:00Z}". | The converter converts e.g.,
"s{since 1970-01-01T00:00:00Z}" to "seconds since 1970-01-01T00:00:00Z". |
C | "C" means Coulomb, but is often mistakenly used to mean degree_C. | "C" means Coulomb. Degrees Celsius is identified via Cel. | "C" is converted to Cel, on the theory that C was used incorrectly. | "C" is left as "C". |
g | In UDUNITS-1, g means free-fall (although it is often mistakenly used to mean "gram").
In UDUNITS-2, g means gram. |
g means gram. [g] means free-fall. | Nothing is done. g in UDUNITS is assumed to mean gram. | g is converted to "gram". |
F | F means Fahrenheit. | F means farad. | F is converted to [degF]. | F is converted to "farad". |
NTU (Nephelometric Turbidity Unit) | NTU is not defined. | NTU is not defined. | NTU is converted to {NTU} following the UCUM method for noting the name of dimensionless (arbitrary) units. | {NTU} is converted to NTU. |
PSU (Practical Salinity Units) | PSU is not defined. | PSU is not defined. | PSU and PSU are converted to {PSU} following the UCUM method for noting the name of dimensionless (arbitrary) units. | {PSU} is converted to PSU, because the CF-recommended 1e-3 is not a useful or correct description. |
Comments and Non-standard Terms | UDUNITS doesn't allow comments or non-standard terms, thus many units strings are invalid. | UDUNITS doesn't allow non-standard terms, but does allow comments in { }. | Non-standard terms are converted to comments. | Comments are uncommented so that no information is lost; however, the result may be an invalid UDUNITS string. |