LHC implementation of UCUM validation and conversion services
This is the LHC implementation of validation and conversion services based on the Unified Code for Units of Measure (UCUM) code system created by the Regenstrief Institute, Inc.
See our overview page for general information.
This is a work in progress so more capabilities will probably be introduced.
We have a demo page that shows various capabilities. That includes the validation and conversion functions described below. You might want to try that out first.
The ucum-lhc code is written in the ECMAScript 6 version of Javascript. Since that version is not yet universally supported, the code is compiled to standard Javascript using the Babel compiler.
Currently we have code to serve multiple purposes. The core code supports the validation and conversion of UCUM unit expressions as well as a function to search for commensurable units for a specified unit expression. Other code is concerned with importing and exporting the UCUM data, and in supporting the demo page (noted above). If you are looking to include the ucum-lhc core code in your application, download the code as an npm package.
You can use the npm package manager to install the ucum-lhc npm package. (npm is automatically installed with Node.js.)
npm install @lhncbc/ucum-lhc --save
This will install the @lhncbc/ucum-lhc directory in your node_modules diretory. The dist subdirectory will contain ucum-lhc.js and ucum-lhc.min.js (minimized version of ucum-lhc.js).
You can use the bower package manager to install the ucum-lhc bower package. (If you do not have bower installed on your machine you can install it using npm. See https://bower.io). Install the ucum-lhc package using the bower install command
bower install ucum-lhc
This will install the ucum-lhc directory in your bower_components directory. The dist subdirectory will contain ucum-lhc.js and ucum-lhc.min.js (minimized version of ucum-lhc.js).
The ucum-lhc.min.js file (which is the minimized version of the ucum-lhc.js file) includes the source code you need for the validation, conversion and commensurable units functions as well as the ucum code definitions file. We assume that your main motivation for including the ucum-lhc code is to have those capabilities for units of measure on your system.
To access those capabilities from your server side code, require the npm package and create a UcumLhcUtils object that contains those functions.
var ucum = require('@lhncbc/ucum-lhc');
var utils = ucum.UcumLhcUtils.getInstance();
To access those capabilities from your client side code, include the ucum-lhc.min.js package in your html file.
<script src="path-to-installed-package/dist/ucum-lhc.min.js"></script>
The validation, conversion and commensurable units functions are available from the ucumPkg.UcumLhcUtils class. In your client side javascript code access those functions via the ucumPkg object. For example,
var parseResp = ucumPkg.UcumLhcUtils.getInstance().validateUnitString(uStr, true);
Below is documentation for the public functions on the UcumLhcUtils instance.
This method validates a unit string. It first checks to see if the string passed in is a unit code that is found in the unit codes table. If it is not found it parses the string to see if it resolves to a valid unit string.
If a valid unit cannot be found, the string is tested for some common errors, such as missing brackets or a missing multiplication operator. If found, the error is reported in the messages array that is returned.
If a valid unit cannot be found and an error cannot be discerned, this may return, if requested, a list of suggested units in the suggestions array that is returned. Suggestions are based on matching the expression with unit names and synonyms.
For example, to validate a unit string of m2/g4 (assuming you have created a utils object as described above):
var returnObj = utils.validateUnitString('m2/g4');
if (returnObj['status'] === 'valid')
/* the string is valid; returnObj['ucumCode'] will contain the valid
ucum code (may differ from what was entered), returnObj['msg'] may
contain a message or messages describing substitution(s) for the
code entered, and retObj['unit'] will contain 3 pieces of data for the
unit - code, name and guidance (provides information about the unit,
such as how the unit is used, etc.)*/
else
/* returnObj['status'] will be 'invalid' and */
/* returnOb['msg'] will have a message describing the problem */
For information on unit string formatting, look at the Ucum Unit Expression
Validation section on the demo page.
There is a button labeled "Show entry hints". That will give you a short description
of unit strings, and includes a link to the
UCUM Specification, where you can find
the full deal.
This method converts a number of one type of unit to the equivalent number of another type of unit. Note that the number returned is not trimmed or rounded to any particular precision or significant digits.
Disclaimer: Conversion results should be verified independently before using them in actual clinical settings.
For example, to convert 27 U.S. fathoms to U.S. inches (assuming you have created a utils object as described above):
var returnObj = utils.convertUnitTo('[fth_us]', 27, '[in_us]');
if (returnObj['status'] === 'succeeded')
/* the conversion was successful.
returnObj['toVal'] will contain the conversion result
(~1943.9999999999998 - number, not formatted string)
returnObj['msg'] will be null
returnObj['fromUnit'] will contain the unit object for [fth_us]
returnObj['toUnit'] will contain the unit object for [in_us]
*/
else if (returnObj['status'] === 'failed')
/* the conversion could not be made.
returnObj['toVal'] will be null
returnObj['msg'] will contain a message describing the failure
returnObj['fromUnit'] will be null
returnObj['toUnit'] will be null
*/
else (returnObj['status'] === 'error)
/* the conversion encountered an error
returnObj['toVal'] will be null
returnObj['msg'] will contain a message describing the error
returnObj['fromUnit'] will be null
returnObj['toUnit'] will be null
*/
If you want to know what unit types a particular unit can be converted to, the checkSynonyms function will provide a list of commensurable units for a specified unit expression.
This method searches for units that include a single search term (theSyn) in the unit's synonyms data and/or the unit name. It returns all units found with a match. This is useful when an exact match for a term is not found. For example, submitting the term "pound" to the validUnitString method will result in a "not found" response. Submitting it to this method will return with a list of possible pound units.
@param theSyn the term to search for
@returns a hash with three elements:
For example, the 'units' array returned for a search term of "pound" would be:
(assuming you have created a utils object as described above):
var returnObj = utils.checkSynonyms('pound');
if (returnObj['status'] === 'succeeded')
/* one or more units was found. returnObj['msg'] will be null and the
returnObj['units'] array will contain the data listed above */
else if (returnObj['status'] === 'failed')
/* no units were found and the returnObj['msg'] string will indicate that
*/
else
/* returnObj['status'] will be 'error' and returnObj['msg'] will indicate
what the error was. */
Converts the given unit string into its base units, their exponents, and a magnitude, and returns that data.
Parameters:
Returns: an object with the properties:
The code available here on GitHub includes functions and scripts to perform additional functions, mainly to convert ucum data from various formats to the data used by our code as well as the code that supports the demo page. Click on the green "Code" button above to download the repository.
If you wish to modify the code, the build process is simply:
npm run build
If you wish to modify or update either of the source data files (ucum-essence.xml or ucum.csv), see impexp/README.md for instructions on build steps for data changes.