The XML4Pharma Application Server

XML4Pharma UCUM unit Web Services

Currently, two web services are available:


Introduction

Through the "ucum-essence.xml" file it is possible to do unit conversions without the need of conversion tables.
We have developed an algorithm that takes any unit in UCUM notation and decomposes it (using "cascading") into the base units (m,s,g,rad,K,cd,rad,mol), allowing to do unit conversion calculations.
This algorithm has now also been implemented in a RESTful web service. It is also used to validate whether a string corresponds to a valid UCUM unit (i.e. is a valid UCUM notation).


UCUM Unit Conversion web service

Through the "ucum-essence.xml" file it is possible to do unit conversions without the need of conversion tables.
We have developed an algorithm that takes any unit in UCUM notation and decomposes it (using "cascading") into the base units (m,s,g,rad,K,cd,rad,mol), allowing to do
unit conversion calculations.
This algorithm has now also been implemented in a RESTful web service. It is also used to validate whether a string corresponds to a valid UCUM unit (i.e. is a valid UCUM notation).

ATTENTION: 2016-09-10: API change!

The principles of the web service are the following:

So the HTTP request format is essentially:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/{source_quantity}/from/{source_unit}/to/{target_unit}
or:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/{source_unit}/to/{target_unit}
when the source quantity = 1 (the default)

Depending on what type your HTTP request has (XML, JSON, text), you will receive either XML, JSON or simple text.
In the latter case, you will get a simple string like:

1.0 [in_i] = 2.54 cm

In case your HTTP request is for XML, you will get the information according to the following structure:


Simple examples (all for request type "text")

To convert 1 inch (UCUM notation [in_i]) to centimeter (cm), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/[in_i]/to/cm
or: http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/[in_i]/to/cm
(as 1 is the default for the value to be converted) Resulting in: 1.0 [in_i] = 2.54 cm

To convert 3.5 foot (UCUM notation [ft_i] to micrometer (um), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/3.5/from/[ft_i]/to/um
Resulting in: 3.5 [ft_i] = 1066800.0 um
the "0002" at the end being caused by the cascading algorithm.

To convert 1 apothecary ounces (UCUM notation: [oz_ap]) to grams (g), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/[oz_ap]/to/g
Resulting into: 1.0 [oz_ap] = 31.103477 g

To convert 2.5 pounds per square inch (UCUM notation: [psi]) into millimeter mercury column (UCUM notation: mm[Hg]) use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/2.5/from/[psi]/to/mm[Hg]
Resulting in: 2.5 [psi] = 129.28769 mm[Hg]


Somewhat more difficult examples

Suppose you have a low expressed in US gallons per minutes (UCUM notation: [gal_us]/min), and want to convert that to liters per hour (UCUM notation: l/h or L/h - both are valid), then use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/[gal_us]/min/to/l/h
Resulting in: 1.0 [gal_us]/min = 227.12471 l/h

In order to convert millimeter mercury column (UCUM notation mm[Hg]) into its base components, which is kg/m.s-2 (kilogram per meter times square seconds), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mm[Hg]/to/kg/m.s-2
Resulting in: 1.0 mm[Hg] = 133.322 kg/m.s2


Non-matching properties

When trying to convert between units for which the properties don't match (e.g. weight to time), you will get an error message.
For example for kg (kilograms) to min (minutes), when you use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/kg/to/min
This results in the error message: Error: Source and Target unit do not seem to belong to the same property
This will also work for more complex expressions, as the converting engine breaks the unit down to the base units, and compares the exponents on these between source and target.


Conversions using moles

Essentially, "mol" is not a unit, it is a number. So 1 mol of cows is 6.023E23 number of cows (I don't believe we have one mol of cows on earth...).
However, as people are used to work with moles as if it were a unit, we implemented "mol" as being a base unit. So if we want to e.g. do a concentration conversion, like:
convert 1 mol per cubic inch (UCUM notation: [in_i]3) to mol/L, we use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mol/[in_i]3/to/mol/L
Resulting in: 1.0 mol/[in_i]3 = 61.023744 mol/L

One can also do more complex unit conversions using "mol", such as between "PK units" that have been published by CDISC
For example, you want to do the conversion between "h.pmol/l" (picomol-hours per liter) to "min.umol/ml" (micromol-minutes per cubic meter), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/h.pmol/l/to/min.umol/m3
Resulting in: 1.0 h.pmol/l = 0.06 min.umol/m3
This works, as both "l" (liter) as "m3" are volumes.

One can also use brackets (but no nested brackets yet), for example:

http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/m/(mg2.s2)/to/m.s-2.g-2


Annotations

In some cases, you might want to use annotations, for example to express "mol of creatinine".
You can do so, as long as there is a match between the annotations of the source with the annotations at the target side. If this is not the case, you will obtain an error message saying: ERROR: annotations mismatch between source and target

A valid web service request is however e.g.:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mol{creatinine}/l/to/mol{creatinine}/[in_i]3
Resulting in: 1.0 mol{creatinine}/l = 0.016387064 mol{creatinine}/[in_i]3


UCUM for SEND

One of the prejudices (within CDISC) about UCUM is that it would not be usable to units of the preclinical world (CDISC-SEND submissions). The contrary is true! UCUM brings order in units for animal and other preclinical studies. For example for the CDISC "PKUNIT" codelist (NCI C85494) contains almost 300 terms, with CDISC desperately adding new ones each time a new version is published. As the number of combinations is in principle inifinite, this list will grow and grow.
Furthermore, the CDISC codelist does not allow to do any unit conversions. It does e.g. not allow to calculate how many "(L/h)/m2" go into "(L/min)/cm2".
For "PKUNIT", no codelist is necessary: UCUM solves everything!

Let us take an (already somewhat more typical SEND example): We have chickens that drink water, and measure how much water they consume as function of the amount of space they have, amount of food, and time.
We however have one group in the US that measures this using gallons, square feet, ounces of food, and hours. In Europe however, the same measurement is made using liters, square meters, grams of food, and days.
So, what is the conversion factor? CDISC-CT won't tell you. For UCUM however, using our RESTful web service it is easy:

UCUM notation for the measurement in the US: [us_gal]{waterconsumption}/([ft_i]2.{chicken}.[oz_av]{food}.h)
UCUM notation for the measurement in Europe: l{waterconsumption}/(m2.{chicken}.g.{food}.d)

And the conversion factor can easily be obtained using our RESTful web service:

http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/l{waterconsumption}/(m2.{chicken}.g{food}.d)/to/[gal_us]{waterconsumption}/([ft_i]2.{chicken}.[oz_av][food].h)

Want to know the answer? Then try it yourself! Can you do this using CDISC Controlled Terminology?


Current limitations

Currently we still have following limitations (but are working on removing them):

If you find any other limitations or errors, please report them


The UCUM unit validity service

In some cases you (or your application) simply wants to check whether a string corresponds to a valid UCUM string/unit.
This can easily be done by using the "isValidUCUM" web service.

This web service is very simple to use:

examples


The UCUM unit to base units service

This service (still experimental - please let us know what you find of it), converts any unit in UCUM notation to the base units.

Request string:
http://xml4pharmaserver.com:8080/CDISCCTService/rest/toBaseUnits/{unit}

For example, if you don't know what the base units of "circular mil" (UCUM notation "[cml_i]"), you submit:
http://xml4pharmaserver.com:8080/CDISCCTService/rest/toBaseUnits/[cml_i]

Or for "gallon per square foot":
http://xml4pharmaserver.com:8080/CDISCCTService/rest/toBaseUnits/[gal_us]/[sft_i]

Resulting in:

When you think about it, it is clear: "gallon" is a volume (base unit: m3) and "square foot" is an area (base unit: m2), so, "gallon per square foot" reduces to "m" (exponent=1) and the "conversion" factor is 0.0407.

Another example is breaking down mm[Hg] to the base units:

http://xml4pharmaserver.com:8080/CDISCCTService/rest/toBaseUnits/mm[Hg]

Which returns (here as XML):

Essentially stating that 1 mm[Hg] = 133322 g.s-2.m-1

Also remark that the entries under "ResultBaseUnitList" can be used for easily treating the result or for chaining

Limitations:


Special character encoding

Not all browsers correctly encode the special characters "[", "]", "{" and "}" when doing the HTTP request. So if you copy-paste the listed URLs, you may need to replace following special characters: In applications, this should however be taken care of by the framework that you use (e.g. JAX-RS).

When using the browser, also ensure that it accepts XML, and displays it as such, i.e. that it does not try to "style" it. For example, some issues have been reported with Firefox with the Skype plugin.

Use of these web services

Although one can use these web services in the browser (you probably already discovered that), this is not the primary use of RESTful web services. This kind of web services is meant to be used in applications, such as already have been done in the "Smart Dataset-XML Viewer", an open source viewer for CDISC SDTM/SEND/ADaM submissions in XML available from SourceForge.

You are invited to use these web services in your pilot and production applications, taking the following into account:

Courtesy of XML4Pharma - last update: July 2017