Units Support

[ajpatterson]

General requirement to add support for every value stored/displayed to have settable units.

[rleigh]

Units in C++ using Boost.Units

[rleigh]

Example of using units in C++ attached. Output is:

Length x1 = 2.425e-05 m
Length x2 = 24.25 um
Length x3 = 0.2425 nm
Length x4 = 2.425e-05 m

• Units are static compile-time value types
• Types may be defined for any dimension and scale e.g. length can be m, nm, µm, km type, for storing the type
• Values may be defined in any scale compatible with the stored unit system, e.g. specify µm for storing in metres, and the appropriate conversion (×10¯⁶) will be performed automatically
• All unit scale conversions are performed at compile-time

Factors to consider:

• Due to the compile-time restrictions, an internal canonical representation must be defined for each unit type (e.g. m for length, s for time, Pa for pressure)
• Any conversions are also compile-time, so any derived units used by the model, e.g. µm, nm, ms, ps must also be explicitly used at compile-time; it will not be possible to support arbitrary unit systems this way
• Arbitrary units /could/ be supported, so long as the units are convertible to an existing supported unit or derived unit.
• For display it's trivial to interconvert between units, but this would also need hardcoding. Example, value 0.000042m would need assigning to a micron type to display as 43µm
• Symbols in the units headers are ASCII only, so we would also need to handle proper unicode unit symbols (not hard)

The Boost.Units strategy would make it possible to correctly support SI units across the whole C++ codebase fairly trivially; it can certainly be used pervasively throughout the model code. The code that assigns values from attributes will just need to use the "unit" attribute or equivalent to perform the appropriate unit conversion. We can have a single utility source file to handle this for each dimension in use.

[rleigh]

On the java side:

​http://jscience.org/api/index.html and ​http://www.jcp.org/en/jsr/detail?id=275 (but JSR was rejected). Otherwise looks ideal; still usable independently despite the rejection? Or is the javax namespace off-limits?
​http://stackoverflow.com/questions/1193810/java-metric-unit-conversion-library
​https://java.net/projects/jscience/sources/svn/show/trunk/jscience/physics/src/main/java/org/jscience/physics/unit?rev=694
Looks like it's not dead and is currently on java.net as above, but not sure if it has a stable release yet. Worth checking in more detail for certain.

[rleigh]

Note that all the above libraries are compile-time type-safe unit converters. If we do want greater dynamism, i.e. to be able to register and use additional unit systems at runtime, we can certainly do so; we would probably just need to roll our own classes to contain both value and unit information [the above only store values; the unit *is* the type]. This can make use of the above libraries to do the underlying conversions, it's just adding a layer over the top.

[rleigh]

Melissa, do you have any thoughts on usable units implementations on the Java side of things? The jscience stuff looks OK, but if there are better alternatives you are aware of, then it would be good to know. Have you used the jscience units stuff at all?

[ajpatterson]

Some comment from paper notes made last year:

• Initialy look at adding support to the distance and time units.

• Two approaches - fixer versus user configurable

• Need to list the unit libraries (as above) with "What does the API provide?" and "Compile time or runtime?"

• What does Scifio use? Has it a units solution in use already?

[rleigh]

I think Curtis has mentioned that scifio has some support for units, but I know nothing of the details.

[crueden-x]

ImgLib2 (and hence SCIFIO) uses Unidata's UDUNITS library (part of NetCDF-Java, and also called UCAR Units) for units support:

• ​UDUNITS Java binary releases
• ​UDUNITS Java source on GitHub
• ​UDUNITS Javadoc
• ​More Units documentation

There is also a C version of UDUNITS:

• ​UDUNITS C version web page
• ​UDUNITS C source on GitHub
• ​UDUNITS R bindings ;-)

Lastly, the ImgLib2 code that uses the UCAR Units API:

• ​Calibrated axis with associated unit
• ​Service for unit conversion (not really used yet).
• ​CombinedRealInterval: a union of RealIntervals?
• ​CombinedCalibratedRealInterval: a union of CalibratedRealIntervals?

SCIFIO attaches a CalibratedAxis object to each dimension, and can populate the unit string according to what is present in the metadata. However, we have not yet implemented reconciliation between compatible units using the UnitService. From the ​CombinedRealInterval javadoc:

In the case of RealIntervals which also implement CalibratedSpace, no reconciliation is done to ensure that overlapping axes have equal units or calibrations; it is assumed that each axis has already been standardized to a common calibration via the CalibratedViews#recalibrate method.

CalibratedViews does not yet exist, but the plan is for it to drive the reconciliation of differing-but-compatible units between multiple CalibratedRealInterval objects.

[crueden-x]

See also ​ImageJ ticket #1621, which describes our research into unit libraries, and includes commentary on both JScience and UoMO unit libraries.

[mtbcarroll]

Has ​http://www.unitsofmeasurement.org/ been considered?

[rleigh]

Old JSR-275 (javax.measure) API, implemented by jscience is abandoned. Current development appears to be on org.unitsofmeasurement, implemented by UOMo. UOMo dependencies on eclipse/osgi.

[jamoore]

..."depends on eclipse"? Looking at ​http://unitsofmeasure.googlecode.com/svn/trunk/unit-api/pom.xml I don't see any dependencies.

[rleigh]

There are no deps on it in the interfaces (unit-api). The deps are in the UOMo implementation of the api, or at least appear to be; this part needs looking at in more detail: ​http://www.eclipse.org/uomo/

[crueden-x]

Based on our research (again: see ​ImageJ ticket #1621), I would advise against UOmo. It seems to be largely a one-person show, not available in Maven Central now or anytime soon, and has several dependencies including OSGi.

[rleigh]

UDUnits AFAICS doesn't implement a typesafe units API; it is handling conversions. The JSRs and jscience/UOMo *are* defining and implementing strongly-typed units with transparent conversion between unit systems. I would like for us to be using strongly-typed units in our metadata APIs where possible or else the end user will need to handle all unit conversion by hand, and the metadata values would not be directly-associated with any unit. This is vastly less usable and also less safe.

That said, jscience is not currently developed. But UOMo certainly is. If it's possible to remove its OSGI dependencies, would that be more palatable? Is the OSGI dependency a jproblem in practice?

[crueden-x]

I don't understand why an strongly-typed (i.e., compile-safe) unit API is required for end users to benefit from unit conversion. Of course I agree that a type-safe units API might be handy for developers coding against the API. But end users will not know the difference. And UDUnits definitely can definitely perform unit conversions -- that is its central purpose.

As for whether the dependencies or maturity of UOMo would cause problems in practice... I suppose someone will have to evaluate that. The ImageJ ticket I linked contains all the information I have about it from Barry, who has now left our group.