{"id":21982090,"url":"https://github.com/lhncbc/ucum-lhc","last_synced_at":"2025-05-16T09:07:14.057Z","repository":{"id":39849341,"uuid":"57145984","full_name":"LHNCBC/ucum-lhc","owner":"LHNCBC","description":"LHC implementation of UCUM validation and conversion services","archived":false,"fork":false,"pushed_at":"2025-05-07T17:01:00.000Z","size":13184,"stargazers_count":57,"open_issues_count":1,"forks_count":17,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-07T17:11:23.037Z","etag":null,"topics":["javascript","ucum","units-of-measure"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LHNCBC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-26T16:52:14.000Z","updated_at":"2025-05-07T17:01:04.000Z","dependencies_parsed_at":"2023-02-10T18:45:34.760Z","dependency_job_id":"1ceb823a-239f-40a8-953e-d71219e7339a","html_url":"https://github.com/LHNCBC/ucum-lhc","commit_stats":{"total_commits":595,"total_committers":5,"mean_commits":119.0,"dds":"0.17142857142857137","last_synced_commit":"a8d3182db3a83b0a884c5a4988c44ca7e1330b83"},"previous_names":["nlm-lhc/ucum-lhc","lhncbc/ucum-lhc"],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LHNCBC%2Fucum-lhc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LHNCBC%2Fucum-lhc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LHNCBC%2Fucum-lhc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LHNCBC%2Fucum-lhc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LHNCBC","download_url":"https://codeload.github.com/LHNCBC/ucum-lhc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501558,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","ucum","units-of-measure"],"created_at":"2024-11-29T17:21:49.638Z","updated_at":"2025-05-16T09:07:09.773Z","avatar_url":"https://github.com/LHNCBC.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ucum-lhc\nThis is the LHC implementation of validation and conversion services based on\nthe [Unified Code for Units of Measure](http://unitsofmeasure.org) (UCUM) code\nsystem created by the Regenstrief Institute, Inc.  \n\nSee our [overview page](https://ucum.nlm.nih.gov/ucum-lhc) for\ngeneral information.\n\nThis is a work in progress so more capabilities will probably be introduced.\n\n## Check out the Demo page\n\nWe have a [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html) that \nshows various capabilities.  That includes the validation and conversion\nfunctions described below.  You might want to try that out first.\n\n## Get the code\n\nThe ucum-lhc code is written as ES6 modules, but the npm package (see below)\nalso contains CommonJS modules, as well as a \"browser-dist\" directory with files\nready to use in a web browser.\n\nCurrently we have code to serve multiple purposes.  The core code supports\nthe validation and conversion of UCUM unit expressions as well as a function\nto search for commensurable units for a specified unit expression.  Other code is \nconcerned with importing and exporting the UCUM data, and in supporting the\ndemo page (noted above).  If you are looking to include the ucum-lhc core code \nin your application, download the code as an [npm](https://www.npmjs.com) package.\n\n### Getting the code as an npm package\n\nYou can use the [npm](https://www.npmjs.com) package manager \nto install the ucum-lhc npm package.  (npm is \n[automatically installed](https://www.npmjs.com/get-npm) with Node.js.)\n\n    npm install @lhncbc/ucum-lhc --save\n\nThis will install the @lhncbc/ucum-lhc directory in your node_modules diretory. \nThe browser-dist subdirectory will contain ucum-lhc.min.js for use directly in a\nbrowser.\n\n## Using the code \n\nThe ucum-lhc.min.js file includes the source code you need for the validation,\nconversion and commensurable units functions as well as the ucum code\ndefinitions file.  We assume that your main motivation for including the\nucum-lhc code is to have those capabilities for units of measure on your system.  \n\n### Server side\nTo access those capabilities from your server side code (or from client side\ncode that goes through a build system), require the npm package\nand create a UcumLhcUtils object that contains those functions.\n\n    const ucum = require('@lhncbc/ucum-lhc');\n    const utils = ucum.UcumLhcUtils.getInstance();\n\n \n### Client side\n\nTo access those capabilities from your client side code, include the \nucum-lhc.min.js package in your html file.  \n\n    \u003cscript src=\"path-to-installed-package/browser-dist/ucum-lhc.min.js\"\u003e\u003c/script\u003e\n\nThe validation, conversion and commensurable units functions are available from \nthe _ucumPkg.UcumLhcUtils_ class.  In your client side javascript code access \nthose functions via the ucumPkg object.  For example, \n\n    var parseResp = ucumPkg.UcumLhcUtils.getInstance().validateUnitString(uStr, true);\n        \n### Function descriptions\n        \nBelow is documentation for the public functions on the UcumLhcUtils instance.\n*  [validateUnitString](#validateunitstringustr-suggest)\n*  [convertUnitTo](#convertunittofromunitcode-fromval-tounitcode-options)\n*  [checkSynonyms](#checksynonymsthesyn)\n*  [convertToBaseUnits](#converttobaseunitsfromunit-fromval)\n*  [commensurablesList](#commensurableslistfromunit-categorylist)\n\n#### validateUnitString(uStr, suggest)\n\nThis method validates a unit string.  It first checks to see if the string passed \nin is a unit code that is found in the unit codes table. If it is not found it \nparses the string to see if it resolves to a valid unit string.\n\nIf a valid unit cannot be found, the string is tested for some common errors,\nsuch as missing brackets or a missing multiplication operator.  If found, the\nerror is reported in the messages array that is returned.\n\nIf a valid unit cannot be found and an error cannot be discerned, this may\nreturn, if requested, a list of suggested units in the suggestions array\nthat is returned.  Suggestions are based on matching the expression with\nunit names and synonyms.\n\n**Parameters**:\n1) uStr: the string to be validated;\n2) suggest: a boolean to indicate whether or not suggestions are\n    requested for a string that cannot be resolved to a valid unit;\n    true indicates suggestions are wanted; false indicates they are not,\n    and is the default if the parameter is not specified;\n\n**Returns**: an object with five properties:\n   * 'status' will be 'valid' (the uStr is a valid UCUM code), 'invalid'\n        (the uStr is not a valid UCUM code, and substitutions or\n        suggestions may or may not be returned, depending on what was\n        requested and found); or 'error' (an input or programming error\n        occurred);\n   * 'ucumCode' the valid ucum code, which may differ from what was passed\n        in (e.g., if 'Gauss' is passed in, this will contain 'G') OR null if\n        the string was flagged as invalid or an error occurred; \n   * 'msg' is an array of messages, if the string is invalid or an\n        error occurred, indicating the problem, or an explanation of a\n        substitution such as the substitution of 'G' for 'Gauss', or\n        an empty array if no messages were generated ;\n   * 'unit' which is null if no unit is found, or a hash for a unit found:\n     * 'code' is the unit's ucum code (G in the above example);\n     * 'name' is the unit's name (Gauss in the above example); and\n     * 'guidance' is the unit's guidance/description data.\n   * 'suggestions' if suggestions were requested and found, this is an array\n         of one or more hash objects.  Each hash contains three elements:\n     * 'msg' which is a message indicating what part of the uStr input\n         parameter the suggestions are for;\n     * 'invalidUnit' which is the unit expression the suggestions are\n         for; and\n     * 'units' which is an array of data for each suggested unit found.\n          Each array will contain the unit code, the unit name and the\n          unit guidance (if any).\n        If no suggestions were requested and found, this property is not\n        returned.\n\nFor example, to validate a unit string of m2/g4 (assuming you have created a\nutils object as described above):\n\n     var returnObj = utils.validateUnitString('m2/g4');\n     if (returnObj['status'] === 'valid')\n       /* the string is valid; returnObj['ucumCode'] will contain the valid \n          ucum code (may differ from what was entered), returnObj['msg'] may \n          contain a message or messages describing substitution(s) for the\n          code entered, and retObj['unit'] will contain 3 pieces of data for the \n          unit - code, name and guidance (provides information about the unit, \n          such as how the unit is used, etc.)*/\n     else\n       /* returnObj['status'] will be 'invalid' and */\n       /* returnOb['msg'] will have a message describing the problem */\n       \nFor information on unit string formatting, look at the _Ucum Unit Expression \nValidation_ section on the [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html).  \nThere is a button labeled \"Show entry hints\".  That will give you a short description \nof unit strings, and includes a link to the \n[UCUM Specification](http://unitsofmeasure.org/ucum.html), where you can find \nthe full deal.\n\n#### convertUnitTo(fromUnitCode, fromVal, toUnitCode, options)\n\nThis method converts a number of one type of unit to the equivalent number of\nanother type of unit.  Note that the number returned is not trimmed or\nrounded to any particular precision or significant digits.\n\nDisclaimer:  Conversion results should be verified independently before\nusing them in actual clinical settings.\n\n**Parameters**:\n1) fromUnitCode: the unit code/expression/string of the unit to be converted;\n2) fromVal: the number of \"from\" units to be converted to \"to\" units;\n3) toUnitCode: the unit code/expression/string of the unit that the from \n  field is to be converted to;\n4) options: an optional hash of options that can be passed in:\n   * 'suggestions' a boolean to indicate whether or not suggestions are wanted\n      for a string that cannot be resolved to a valid unit; true indicates\n      suggestions are wanted; false indicates they are not, and is the default\n      if the parameter is not specified;\n   * 'molecularWeight' the molecular weight of the substance in question when a\n      conversion is being requested from mass to moles/equivalents and vice versa.  It is\n      ignored if neither unit includes a measurement in moles.  In such cases\n      the mole-based unit must have a single mole unit in the numerator and the\n      mass-based unit must have a single mass unit in the numerator.\n   * 'charge' the absolute value of the charge of the substance in question when a conversion \n      is being requested from mass/moles to equivalents and vice versa. It is required \n      when one of the units represents a value in equivalents and the other in mass or moles. \n      It is ignored if neither unit includes an equivalent unit\n\n**Returns**: a hash with six elements:\n   * 'status' the will be: 'succeeded' if the conversion was successfully\n      calculated; 'failed' if the conversion could not be made, e.g., if\n      the units are not commensurable; or 'error' if an error occurred;\n   * 'toVal' the numeric value indicating the conversion amount, or null\n      if the conversion failed (e.g., the units are not commensurable);\n   * 'msg' is an array of messages, if the string is invalid or an\n      error occurred, indicating the problem, or an explanation of a\n      substitution such as the substitution of 'G' for 'Gauss', or\n      an empty array if no messages were generated;\n   * 'suggestions' if suggestions were requested and found, this is a hash\n        that contains at most two elements:\n     * 'from' which, if the fromUnitCode input parameter or one or more of\n         its components could not be found, is an array one or more hash\n         objects.  Each hash contains three elements:\n       * 'msg' which is a message indicating what unit expression the\n           suggestions are for;\n       * 'invalidUnit' which is the unit expression the suggestions are\n           for; and\n       * 'units' which is an array of data for each suggested unit found.\n           Each array will contain the unit code, the unit name and the\n           unit guidance (if any).\n         If no suggestions were found for the fromUnitCode this element\n         will not be included.\n     * 'to' which, if the \"to\" unit expression or one or more of its\n         components could not be found, is an array one or more hash\n         objects.  Each hash contains three elements:\n       * 'msg' which is a message indicating what part of the toUnitCode\n           input parameter the suggestions are for;\n       * 'invalidUnit' which is the unit expression the suggestions\n           are for; and\n       * 'units' which is an array of data for each suggested unit found.\n           Each array will contain the unit code, the unit name and the\n           unit guidance (if any).\n         If no suggestions were found for the toUnitCode this element will\n         not be included.\n       No 'suggestions' element will be included in the returned hash\n       object if none were found, whether or not they were requested.\n   * 'fromUnit' the unit object for the fromUnitCode passed in; returned\n      in case it's needed for additional data from the object; and\n   * 'toUnit' the unit object for the toUnitCode passed in; returned\n      in case it's needed for additional data from the object.\n\nFor example, to convert 27 U.S. fathoms to U.S. inches (assuming you have \ncreated a utils object as described above): \n \n    var returnObj = utils.convertUnitTo('[fth_us]', 27, '[in_us]');\n    if (returnObj['status'] === 'succeeded')\n      /* the conversion was successful.\n         returnObj['toVal'] will contain the conversion result\n           (~1943.9999999999998 - number, not formatted string)\n         returnObj['msg'] will be null\n         returnObj['fromUnit'] will contain the unit object for [fth_us]\n         returnObj['toUnit'] will contain the unit object for [in_us]\n       */\n    else if (returnObj['status'] === 'failed')\n      /* the conversion could not be made.\n         returnObj['toVal'] will be null\n         returnObj['msg'] will contain a message describing the failure\n         returnObj['fromUnit'] will be null\n         returnObj['toUnit'] will be null\n       */\n    else (returnObj['status'] === 'error)\n      /* the conversion encountered an error\n         returnObj['toVal'] will be null\n         returnObj['msg'] will contain a message describing the error\n         returnObj['fromUnit'] will be null\n         returnObj['toUnit'] will be null\n       */\n      \nIf you want to know what unit types a particular unit can be converted to, the \ncheckSynonyms function will provide a list of commensurable units for a specified\nunit expression.\n\n#### checkSynonyms(theSyn)\n\nThis method searches for units that include a single search term (theSyn) in the\nunit's synonyms data and/or the unit name.  It returns all units found with a \nmatch.  This is useful when an exact match for a term is not found.  For example,\nsubmitting the term \"pound\" to the _validUnitString_ method will result in a \n\"not found\" response.   Submitting it to this method will return with a list \nof possible pound units.\n\n**Parameters**:\n1) theSyn: the term to search for\n\n**Returns**: a hash with three elements:\n   * 'status' contains the status of the request, which can be 'error',\n      'failed' or 'succeeded'; \n   * 'msg' contains a message for an error or if no units were found; and \n   * 'units' which is an array that contains one hash for each unit found:\n     * 'code' is the unit's code;\n     * 'name' is the unit's name; and\n     * 'guidance' is the guidance, or description, for the unit.\n\n   For example, the 'units' array returned for a search term of \"pound\" would be:\n    * {\"code\":\"\\[lb_av\\]\",\"name\":\"pound - international\",\"guidance\":\"standard unit used in the US and internationally\"}\n    * {\"code\":\"\\[lbf_av\\]\",\"name\":\"pound force - US\",\"guidance\":\"only rarely needed in health care - see [lb_av] which is the more common unit to express weight\"}\n    * {\"code\":\"\\[lb_tr\\]\",\"name\":\"pound - troy\",\"guidance\":\"only used for weighing precious metals\"}\n    * {\"code\":\"\\[lb_ap\\]\",\"name\":\"pound - apothecary\",\"guidance\":null}\n    * {\"code\":\"\\[psi\\]\",\"name\":\"pound per square inch\",\"guidance\":null}\n\n(assuming you have created a utils object as described above):\n\n    var returnObj = utils.checkSynonyms('pound');\n    if (returnObj['status'] === 'succeeded')\n      /* one or more units was found.  returnObj['msg'] will be null and the\n         returnObj['units'] array will contain the data listed above */\n    else if (returnObj['status'] === 'failed')\n      /* no units were found and the returnObj['msg'] string will indicate that\n      */\n    else\n      /* returnObj['status'] will be 'error' and returnObj['msg'] will indicate\n         what the error was. */\n\n#### convertToBaseUnits(fromUnit, fromVal)\n\nConverts the given unit string into its base units, their exponents, and\na magnitude, and returns that data.\n\n**Parameters**:\n1) fromUnit: the unit string to be converted to base units information\n2) fromVal: the number of \"from\" units to be converted\n\n**Returns**:  an object with the properties:\n* status: indicates whether the result succeeded.  The value will be one of:\n  * 'succeeded':  the conversion was successfully calculated (which can be\n     true even if it was already in base units);\n  * 'invalid':  fromUnit is not a valid UCUM code;\n  * 'failed':  the conversion could not be made (e.g., if it is an \"arbitrary\" unit);\n  * 'error':  if an error occurred (an input or programming error)\n* msg: an array of messages (possibly empty), if the string is invalid or\n       an error occurred, indicating the problem, or a suggestion of a\n       substitution such as the substitution of 'G' for 'Gauss', or\n       an empty array if no messages were generated.  There can also be a\n       message that is just informational or warning.\n* magnitude: the new value when fromVal units of fromUnits is expressed in the base units.\n* fromUnitIsSpecial: whether the input unit fromUnit is a \"special unit\"\n        as defined in UCUM.  This means there is some function applied to convert\n        between fromUnit and the base units, so the returned magnitude is likely not\n        useful as a scale factor for other conversions (i.e., it only has validity\n        and usefulness for the input values that produced it).\n* unitToExp: a map of base units in fromUnit to their exponent\n\n#### commensurablesList(fromUnit[, categoryList])\n\nRetrieves a list of units commensurable, i.e., that can be converted from and\nto, a specified unit.  Returns an error if the \"from\" unit cannot be found.\nIf necessary, you can filter the list of units by specifying a list of unit\ncategories that should be in the resulting list.\n\n**Parameters**:\n1) fromUnit: the name/unit string\n2) categoryList:  optional parameter - the list of unit categories; possible\n   list values: 'Clinical', 'Nonclinical', 'Obsolete', 'Constant'\n\n**Returns**: an array containing two elements:\n* 0: an array of commensurable units if any were found, each of which is an\n     object with the properties:\n  * name_: unit name;\n  * csCode_: unit code;\n  * other properties are currently undocumented and their existence should not\n    be relied upon.\n* 1: an error message if the \"from\" unit is not found.\n\n\n### Download the GitHub repository\n\nThe code available here on GitHub includes functions and scripts to perform\nadditional functions, mainly to convert ucum data from various formats to \nthe data used by our code as well as the code that supports the demo page.\nClick on the green \"Code\" button above to download the repository.\n\n    \n### Building the code and data\nIf you wish to modify the code, the build process is simply:\n\n    npm run build\n\nIf 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhncbc%2Fucum-lhc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flhncbc%2Fucum-lhc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhncbc%2Fucum-lhc/lists"}