Units of Measure (UOM)
This article covers Seeq's support for units of measure including conversion, mathematical operations, and recognition of datasource units.
Overview
The general units approach in Seeq is to define a set of fundamental dimensions from which all units of measurement (UOM's) can be derived. A dimension is a unit category such as length or time. Within a dimension, units are compatible meaning conversions are available. For example, meter and inch are both of dimension length and therefore compatible. Kilogram and meter are not compatible because they are not in the same dimension.
When a time series has units affiliated with it, Seeq can perform unit conversions and make sensible decisions when performing math and other operations on data. For example, what is greater? 31 °F or 5 °C?
Below are tables of the units that are supported by Seeq in each release. In addition to the units listed, many derived units are not listed but still supported. A derived unit is made by using multiplication, division, or powers to combine units. Examples of derived units are kg/s or m². Note that a unit like m² has several acceptable forms: m², m^2, m*m, m·m.
Currency
There is currently no currency conversion. Prior to v53, this results in 1$ + 2€ = 3£. v53 and later gives an error when mixing currencies.
Tool and Formula Units
Seeq accepts all listed units and derived units in Seeq formulas and tools. Specific formula functions of interest are convertUnits() and setUnits().
Seeq formula has trouble when units contain parentheses. For example, the 5$/(kg*h).tosignal() is rejected by Seeq formula. The workaround is to add some 1's like this: 5$/(1kg*1h).tosignal()
Datasource Units
When Seeq syncs with signals from a datasource such as a historian, it applies any units of measure set by the datasource. When a signal's unit is not recognized, Seeq sets the units to unitless.
Seeq does make an attempt to find the best Seeq match for the datasource unit name. To check the units, look in the log file appserver-units.log for messages like these:
Log messages
DEBUG 2017-11-04T22:31:26.942-07:00 [G_2] c.s.a.q.v.s.SeriesQueriesV1 - Datasource: OSIsoft PI c29fb683-86c9-4a74-b0af-95b6b9f528fb Signal: AFEnumerationTest 19648 Unit 'C' parsed as '°C'
DEBUG 2017-11-04T22:31:29.015-07:00 [G_2] c.s.a.q.v.s.SeriesQueriesV1 - Datasource: OSIsoft PI c29fb683-86c9-4a74-b0af-95b6b9f528fb Signal: B.LEVEL.403 19629 Unable to parse a unit from 'Ton', defaulting to unitlessIn the log example, "Ton" was not mapped because Seeq doesn't know if a short ton, long ton, or metric ton was intended.
To fix any incorrect mappings or unrecognized units, use a Connector Property Transform. For example, if a short ton was intended for signal B.LEVEL.403, "Ton" could be mapped to "ston" using a Connector Property Transform. This unit transform could be applied to just one signal, a group of signals, or the entire datasource.
If the datasource units are unrecognized, Seeq still displays the units throughout the UI. Note that unrecognized units appear in grey italics.
It is always a good idea to check the unit parsing log messages especially if your datasource is lax about case or doesn't use parentheses in units. For example:
Is US intended to be microSiemens (uS) or microseconds (us)?
$/H is $/henry but perhaps hour (h) was intended instead of henry (H).
m/s/s is m/s² which is probably what was intended. $/bbl/d = $/(bbl*d) but perhaps $/(bbl/d) = ($*d)/bbl was intended. Unit of measure expressions are evaluated according to the order of operations.
Verifying Seeq's Unit Conversions
Are you curious about the unit conversions that Seeq is using? You can check for yourself using the Formula tool.
Step 1: Create a formula for constant signal with value of 1 meter.
1m.toSignal()
Step 2: Create a 2nd formula converting that signal to new units (feet)
$a.convertUnits('ft')
where $a is the signal from Step 1. You'll see that it now has a value of 3.2808 ft. If you had used units of Weber instead of feet,
$a.convertUnits('Wb')
an error is returned: m is not compatible with Wb
Don't forget about the formula parentheses tip mentioned earlier in this article.
Supported Prefixes
Seeq supports the SI prefixes as shown in the following table. See the units table for details on which units support which prefixes. Prefixes are applied to the unit directly to the right of the prefix. For example, km/g is kilometers/gram and not kilo(meters/gram) although both are equivalent.
M and MM
The prefixes M = 1e3 and MM = 1e6 are not supported. M is always interpreted as SI mega (1e6). We do attempt to map units with a prefix of MM to mega (1e6). If you intend M to be 1e3, you can use a Connector Property Transform to map, for example, MBTU to kBTU.
Prefix | Abbreviation |
|---|---|
deci | d |
centi | c |
milli | m |
micro | µ, u, or micro |
nano | n |
pico | p |
femto | f |
atto | a |
zepto | z |
yocto | y |
Prefix | Abbreviation |
|---|---|
deka | da |
hecto | h |
kilo | k |
mega | M |
giga | G |
tera | T |
peta | P |
exa | E |
zetta | Z |
yotta | Y |
Temperature arithmetic
1m+1ft is a well-defined formula. The answer could be presented in several different units of measure (meters, feet, miles, centimeters, etc.) but they are all the same after unit conversion. (Seeq will answer 1.3048m because Seeq converts the second unit into the first unit and then performs the operation.)
Temperature (in C or F) is trickier because it uses relative scales instead of absolute scales. This can lead to some unexpected behavior within Seeq.
Consider this formula: 1C+1F
Seeq's answer is
-16.22C. This is derived by converting the temperature 1F into C (-17.22C) and then adding.A potential option is
1.5555C.This is derived from saying a single degree change in Fahrenheit is 5/9s of a degree change in Celsius.Other potential option is
256.93C. This is derived from changing both units into Kelvin, adding them, and converting back to Celsius.
Consider this formula averaging two temperatures: (30C+90F)/2
The average is the answer Seeq will give, 31.11C.
The 'degree change' option (second option, hence forth referred to as the "delta calculation") would produce a different (and for averaging purposes, wrong) answer, 80C.
The 'Kelvin' option (third option), derived from converting to K and back also produces the average, 304.26K or 31.11C.
Therefore, as the default, the averaging behavior makes sense, even if it excludes the ability to do delta calculations. However, it can lead to some puzzling behavior. For instance, 1F+1C, the reverse of the above formula, results in 34.6F. This is a different answer from the earlier -16.22C (even accounting for unit conversion). While initially confusing, this is reasonable behavior. The starting points of 1F and 1C are very different, and the deltas added are fairly close. In addition, the averaging behavior we desire still holds:
(1C+1F)/2 = -16.22C/2 = -8.11C = 17.3F
(1F+1C)/2 = 34.6F/2 =17.3F = -8.11C
Normally, unit conversion operations are commutative. The order can be rearranged to get the same results.
(100m/3).convertUnits('cm') == 100m.convertUnits('cm')/3
The answer will be the same regardless of when you decide to convert. However with temperature, we see that the order does matter. Performing a division and then converting is not the same as converting and then dividing.
10F.convertUnits('C')/3 = 4.1C(10F/3).convertUnits('C')/3 = 5.3C
Delta Temperature
If you would like to perform delta operations such as 1C+1ΔF, we suggest manually multiplying by the scaling factor.
1C+(1F.setUnits('C') * (5/9))
Prefix Limitations
Parentheses
Prefixes cannot be applied to parentheses. For example k(m^3) is not supported. Some units of this form can be transformed to a unit Seeq will recognize.
Examples | |
|---|---|
Unrecognized | Recognized |
k(m)^3 | km^3 or (km)^3 |
k(m^3) | not supported |
k(m/g) which is the same as (km)/g | km/g or (km)/g |
Prefix Combinations
Prefixes cannot be combined. For example, k(mg) or kmg are not supported.
Table of Supported Units
Label is the name Seeq displays. Aliases are also recognized but will still be displayed using the label.
The Category is a loose category solely used to organize the units in any UI unit lists. Category is not the same as Dimension. For example, the Electric category contains several units used when dealing with Electricity but all the units within that category are not the same Dimension.
The default character set is UTF-8.
Category | UOM | Label | Aliases | Supported Prefixes |
Acceleration | Gravity at Earth's Surface | grav | ||
Angle Planar | Radian | rad | radian, rads, radians | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Revolution | rev | r | ||
Degree | ° | ˚, ˚A, deg, dega, degree, degrees | ||
Centiradian | centiradian | centiradians | ||
Gradian | gon | gradian, grade, grad, gradians, grads | ||
Angle Solid | Steradian | sr | steradian, steradians | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Sphere | sphere | |||
Angular Velocity | Revolutions Per Minute | rpm | ||
Revolutions Per Second | rps | |||
Angular Momentum | Newton Meter Second | Nms | ||
Area | Are | a | ||
Hectare | ha | |||
Acre | acre | |||
Capacitance | Farad | Farad | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Catalytic Activity | Katal | kat | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Currency | US Dollars | $ | USD | k, M, G, T |
Euros | € | EUR | k, M, G, T | |
British Pound | £ | GBP | k, M, G, T | |
Chinese Yuan | ¥ | CNY | k, M, G, T | |
Korean Won | ₩ | KRW | k, M, G, T | |
Generic Currency | ¤ | k, M, G, T | ||
Data | Bit | bit | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Byte | B | byte, bytes, octet, octets | k, M, G, T, P | |
Electric | Ampere | A | amp, amps, ampere, amperes | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Coulomb | coulomb | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | ||
Henry | H | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | ||
Ohm | Ω | ohm | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Siemens | S | mho, mhos | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Volt | V | v, volt, volts | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Elementary Charge | e | |||
Faraday | Fd | |||
Franklin | Fr | |||
Gilbert | Gi | |||
Ampere Hour | Ah | |||
Energy | Joule | J | j | k, M, g, G |
Erg | erg | |||
Electronvolt | eV | k, M, G | ||
Horsepower Hour | hph | |||
Watt Second | Ws | |||
Watt Hour | Wh | Whr | k, M, G | |
British Thermal Unit | BTU | btu | k, M, G | |
Calorie | cal | k, M, G | ||
Force | Newton | N | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Dyne | dyn | dyne | ||
Kilogram-force | kgf | |||
Pound-force | lbf | |||
Strong-Cobb | Sc | |||
Frequency | Hertz | Hz | hz, hertz | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Illuminance | Lux | lx | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Lambert | La | |||
Impulse | Newton Second | Ns | ||
Length | Meter | m | meter, metre, meters, metres | f, p, n, u, µ, micro, m, c, d, da, h, k, M |
Micron | micron | microns | ||
Mil (Thousandth of an Inch) | mil | mils | ||
Sixteenth of an Inch | sxi | |||
Inch | in | inch, inches | ||
Foot | ft | feet, foot | ||
US Survey Foot | foot_survey_us | |||
Yard | yd | |||
Mile | mi | |||
Nautical Mile | nmi | |||
Angstrom | Å | Angstrom | ||
Astronomical Unit | ua | |||
Light Year | ly | |||
Parsec | pc | |||
Point (Typography) | pt | |||
Pixel | pixel | |||
Luminous Flux | Lumen | lm | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Luminous Intensity | Candela | cd | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Magnetic | Tesla | T | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Weber | Wb | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | ||
Maxwell | Mx | |||
Gauss | G | |||
Mass | Gram | g | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Atomic Mass | u | amu | ||
Electron Mass | me | |||
Pound | lb | lbs | k, M | |
Ounce | oz | |||
Short Ton | ston | uston | ||
Long Ton | lton | ton_uk | ||
Metric Ton | t | tonne, tonnes | k | |
Moles | Mole | mol | mole, moles | k, M |
Gram-Mole | gmol | gmole, gmoles | k, M | |
Pound-Mole | lbmol | lbmole, lbmoles | k, M | |
Atom | atom | |||
Other | String | string | ||
Power | Watt | W | w, watt | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Volt-Ampere Apparent | VA | k, M | ||
Volt-Ampere Reactive | var | VAR | k, M | |
Horsepower (metric) | hp | |||
Pressure | Pascal | Pa | pa, paa, pad, pag | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Atmosphere | atm | |||
Bar | bar | barg, bara, bard | m | |
Millimeter of Mercury | mmHg | mmhg | ||
Inch of Mercury (32 °F) | inHg | inhg | ||
Pounds Per Square Inch | psi | psia, psig, psid | ||
Inches of Water (60 °F) | inWC | inwc, inwg, inWG | ||
Meter of Water (4 °C) | mWC | mwc, mwg, mWG | m | |
Torr | Torr | m | ||
Hectopascal | hPa | |||
Quantity | Count | count | counts, cnt, ct | |
Bacteria | Bac | |||
Cycles | cyc | |||
Events | events | |||
Executions | exc | |||
Radioactive | Becquerel | Bq | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | |
Gray | Gy | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | ||
Sievert | Sv | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y | ||
Rad | rd | |||
Rem | rem | |||
Curie | Ci | |||
Rutherford | Rd | |||
Roentgen | Roentgen | |||
Ratio | Decibel | dB | ||
Percent | % | percent, pct | ||
Parts Per Million | ppm | |||
Parts Per Million Weight | ppmw | ppmwt | ||
Parts Per Million Volume | ppmv | |||
Parts Per Billion | ppb | |||
Specific Gravity | SG | sg, spg | ||
API (American Petroleum Institute) Gravity | API | |||
Speed | Miles Per Hour | mph | ||
Kilometers Per Hour | kph | |||
Knot | kn | knot | ||
Mach | Mach | |||
Speed of Light | c | |||
Temperature | Kelvin | K | K, degk | y, z, a, f, p, n, u, µ, micro, m, c, d, da, h, k, M, g, G, T, P, E, Z, Y |
Degrees Rankine | °R | R, ˚R, degr, rankine | ||
Degrees Fahrenheit | °F | F, ˚F, ℉, degf, fahrenheit | ||
Degrees Celsius | °C | C, ˚C, ℃, degc, celsius | ||
Time | Second | s | sec, secs, second, seconds | n, micro, µ, m |
Minute | min | mins, minute, minutes | ||
Hour | h | hr, hrs, hour, hours | ||
Day | d | day, days | ||
Week | wk | wks, week, weeks | ||
Month | mo | month, months, mth | ||
Year | y | yr, yrs, year, years | ||
Torque | Newton Meter | Nm | ||
Viscosity | Centipoise | cP | cp, cps | |
Centistokes | cSt | cst, cstoke | ||
Volume | Liter | L | l, litre, liters, litres | y, z, a, f, p, n, u, micro, µ, m, c, d, da, h, M, G, T, P, E, Z, Y |
Kiloliter | kL | kl, klitre, kliters, klitres | ||
US Liquid Gallon | gal | usgal, usg, USGAL, gallon, gallons | k, M | |
US Fluid Ounce | oz_fl | |||
US Dry Gallon | gallon_dry_us | |||
Imperial Gallon | gallon_uk | |||
Imperial Fluid Ounce | oz_uk | |||
Barrel (42 US Liquid Gallons) | bbl | bbls, usbbl | k, M, G | |
Cubic Feet | cf | CF, SCF, scf | k, M | |
Cubic Centimeter | cc | |||
Volume Flow Rate | Thousand Barrels Per Day | kbd | ||
Volumetric Flux | LMH (Liters per Square Meter per Hour) | LMH | lmh |
UOM Limitations
Limitation: Mole Units
g/g*mol, kg/kg*mol and lb/lb*mol all display as 1/mol.
Limitation: Multiplier numbers aren't supported
Units with numbers in the unit name such as 1000m are not supported. In this example, this is not the number 1000 with the unit m, it is a unit called 1000m.
Sample with | ||
|---|---|---|
Value | UOM | |
Supported | 14 | m |
Not supported | 14 | 1000m |
Most units of this form can be transformed to a unit Seeq will recognize. However, depending on the intention, there may not be a transformation for units such as 1000M3/D. If (1000m)^3/d was intended, this can be transformed to km^3/d. There is no transform for 1000(m^3)/d.
Examples | |
|---|---|
Unrecognized Unit | Recognized Alternate Unit |
1000kbd | Mbbl/d |
lb/1000kBTU | lb/MBTU |
1000cf | not supported |
1000ft^3 | not supported |
Limitation: Multiple Measurement Names with the Same Underlying Units
Psia and psig represent two different measurements that both have units of lb/in². Unfortunately, only one name for lb/in² is currently supported and that name is psi. Units of psia and psig will be displayed as psi. There are several classes of units with this limitation:
UOM | Label | Unsupported Measurement Names |
|---|---|---|
Bar | bar | barg, bara, bard (Before v53, mbar is displayed as the equivalent hPa) |
Cubic Centimeter | cm³ | cc (supported in v54 and beyond) |
Cubic Feet | cf | acf, scf |
Cubic Meter | m³ | sm³ |
Inches of Water (60 °F) | inWC | inH20a, inH20g |
Parts Per Million | ppm | ppmv, ppmw, ppmwt (supported in v54 and beyond) |
Pascal | Pa | paa, pad, pag |
Pounds Per Square Inch | psi | psia, psig, psid |
Power Triangle
The one exception to this limitation is W (Watt), VA (Volt-Ampere Apparent) and var (Volt-Ampere Reactive). These are all supported (at the expense of losing J/s. A J/s signal will be displayed as var.) When doing math with these signals, you may need to set the units of the result. For example, the formula $myW + $myVA will result in a signal with units of Watts. If one of the others was desired, you could change the formula to ($myW + $myVA).convertUnits('var').