Specifying Units for Attributes

[ajpatterson]

Moved from ​http://www.ome-xml.org/ticket/114

Want to be able to choose the units that certain attributes are stored in.

Currently this is needed for pixel sizes: EM images use nanometers instead of microns. As a work-around we can store small values as microns, but we risk losing accuracy in converting nanometers to and from microns.

Also would be nice to store the units in the XML document itself, rather than the schema, as done by EM-DB, and requested by some users.

<cell>
  <cellA units="A">352.0</cellA>
  <cellB units="A">352.0</cellB>
  <cellC units="A">352.0</cellC>
  <cellAlpha units="degrees">90.0</cellAlpha>
  <cellBeta units="degrees">90.0</cellBeta>
  <cellGamma units="degrees">90.0</cellGamma>
</cell>

The EM-DB schema mostly does not allow different units and looks like this:

<xs:complexType name="cellType">
    <xs:all>
      <xs:element minOccurs="0" name="cellA" type="emd:cType"/>
      <xs:element minOccurs="0" name="cellB" type="emd:cType"/>
      <xs:element minOccurs="0" name="cellC" type="emd:cType"/>
      <xs:element minOccurs="0" name="cellAlpha" type="emd:cAngleType"/>
      <xs:element minOccurs="0" name="cellBeta" type="emd:cAngleType"/>
      <xs:element minOccurs="0" name="cellGamma" type="emd:cAngleType"/>
    </xs:all>
</xs:complexType>

<xs:complexType name="cType">
    <xs:simpleContent>
      <xs:extension base="xs:decimal">
        <xs:attribute fixed="A" name="units" type="xs:string" use="required"/>
      </xs:extension>
    </xs:simpleContent>
</xs:complexType>
<xs:complexType name="anglType">
    <xs:simpleContent>
      <xs:extension base="xs:decimal">
        <xs:attribute fixed="degrees" name="units" type="xs:string" use="required"/>
      </xs:extension>
    </xs:simpleContent>
</xs:complexType>

[jburel]

Moving to 4.4 as part of EM and review all the sections of Schema were we need to add units

[wmoore]

Another request for units ​https://www.openmicroscopy.org/community/viewtopic.php?f=4&t=1246

[rleigh]

I've been looking into various ways of supporting different units in the OME model. One standard method which could be used here is UnitsML, by NIST: ​http://unitsml.nist.gov/

v1.0 draft here: ​https://www.oasis-open.org/committees/download.php/44626/UnitsML-v1.0-csd04.xsd
and guide here: ​https://www.oasis-open.org/committees/download.php/43529/UnitsML-Guide-v1.0-wd01.pdf

This is embeddable either in whole or as selected subsets within our own schema, and allows specification of all physical units including SI units and additional units which could be either user-defined or defined by us, and can detain things like conversion factors so that readers can just use the unit system of their choice e.g. metric lengths, and have it all transparently converted. Standard prefixes such as G, k, c, m, µ, n, p etc. can also be freely used and also transparently converted to the desired scale.

It's also possible to restrict the unit types used in particular places, for example to only permit length units to be used for image dimensions and time units for timecourse timestamps. This would permit e.g. use of µm, mm, nm, km, as well as non-metric units such as mil, inch etc. Likewise for time, s, ms, µs and ps could be used, as well as larger units such as minutes, hours and days etc.

It's also important to consider storage of screening data factors in OMERO.tables or directly in the schema. Here, we want to store arbitrary values and arbitrary units, e.g. concentration (mg/ml, µM, nM), treatment time (s, min), and enumerated types (cell type, substrate, drug name). Enumerated types are (as far as I can see) not supported by UnitsML, and would require support in the model as an alternative to scalar values. Having support for arbitrary units here also allows interconversion for analysis e.g. all drug concentrations in nM (with other values in mM and µM being converted to nM).

UnitsML permits the units in use to be stored in the XML document as a set, and then specific units referred to by reference in a similar manner to our use of annotations etc. Thus they could be user-defined in the user-interface and stored in the image. The units are stored as both a symbol and name, so may be displayed in the user-interface with no need for the program to have hard-coded knowledge of the unit system. We could default to having µm and s as the default length and time units in the absence of a reference for backward compatibility.

The advantage here is that the OME model would support images of arbitrary scale, and additionally it could represent the same unit system used in the original image, with no loss of precision due to conversion to µm or s scales.

Regards,
Roger

[wmoore]

NB: Units issue raised again in ome-users: ​http://lists.openmicroscopy.org.uk/pipermail/ome-users/2013-October/003955.html

[ajpatterson]

Referencing ticket #10268 has changed sprint.

[ajpatterson]

Referencing ticket #10268 has changed sprint.

[ajpatterson]

Referencing ticket #10268 has changed sprint.

[rleigh]

ImagingEnvironment? with units support

[rleigh]

Attached example of using org.unitsofmeasurement API. Note that this also relies on methods adding to the units enums to go to and from the base units.

[ajpatterson]

Table of the current values we store, there type, default and quantity:

† - This applies to all the float values used to draw the Shapes. It also would 
    apply to the points used in polygon and polyline that are stored in a string.
‡ - These currently do not have a default value set.

PhysicalX (ROI)       float †               pixel                 Length
PhysicalY (ROI)       float †               pixel                 Length
StrokeWidth           float                 pixel                 Length
FontSize              NonNegativeInt        pt                    Length
WellOriginX           float                 ‡                     Length
WellOriginY           float                 ‡                     Length
PositionX             float                 ‡                     Length
PositionY             float                 ‡                     Length
PhysicalSizeX         PositiveFloat         µm                    Length
PhysicalSizeY         PositiveFloat         µm                    Length
PhysicalSizeZ         PositiveFloat         µm                    Length
TimeIncrement         float                 s                     Time
DeltaT                float                 s                     Time
ExposureTime          float                 s                     Time
PositionX             float                 referenceFrame        Length
PositionY             float                 referenceFrame        Length
PositionZ             float                 referenceFrame        Length
PinholeSize           float                 µm                    Length
ExcitationWavelength  float                 nm                    Length
EmissionWavelength    float                 nm                    Length
X                     float                 referenceFrame        Length
Y                     float                 referenceFrame        Length
Z                     float                 referenceFrame        Length
Temperature           float                 °C                    Temperature
AirPressure           float                 mbar                  Pressure
WorkingDistance       float                 µm                    Length
Voltage               float                 V                     Voltage
CutIn                 PositiveInt           nm                    Length
CutOut                PositiveInt           nm                    Length
CutInTolerance        NonNegativeInt        nm                    Length
CutOutTolerance       NonNegativeInt        nm                    Length
Power                 float                 mW                    Power
Wavelength            PositiveFloat         nm                    Length
RepetitionRate        float                 Hz                    Frequency
Wavelength            PositiveFloat         nm                    Length
Voltage               float                 V                     Voltage
ReadOutRate           float                 MHz                   Frequency

[ajpatterson]

Frequency, Power, Pressure, Temperature, Time, Voltage are always float.

Length is float, but also uses NonNegativeInt (x3), PositiveFloat (x5) and PositiveInt (x2).

In six cases this is representing qa wavelength of some form:

• CutIn
• CutOut
• CutInTolerance
• CutOutTolerance
• Wavelength
• Wavelength

Three are a physical size:

• PhysicalSizeX
• PhysicalSizeY
• PhysicalSizeZ

And the remaining a font size:

• FontSize

[jamoore]

Closing as done. If there is anything that needs to be preserved elsewhere, please speak up.