loinc-conversion

Service that converts LOINC codes and UCUM units to a standardized representation. loinc-conversion is a REST-server that accepts lists of (LOINC-code, unit, value?) and returns corresponding lists of (LOINC-code, UCUM-unit, value). It provides three distinct functions:

1. Standardization of UCUM units Returns a standardized UCUM unit for each LOINC code. (In most cases, the returned UCUM unit is the EXAMPLE_UNIT defined in the official Loinc.csv by Regenstrief.)

2. Conversion of non-UCUM units For selected common (especially in Germany) non-UCUM laboratory units the valid UCUM unit is provided.

3. Conversion of LOINC codes Selected LOINC codes that represent the same concept, and where a unambiguous conversion factor exists (e.g. 718-7 = "Hemoglobin [Mass/volume] in Blood" and 59260-0 = "Hemoglobin [Moles/volume] in Blood"), are converted to an arbitrarily* selected LOINC code (718-7 in the example).

   *The conversion target is the more common unit - which is highly subjective.

REST server description

Endpoint: POST /conversions Content-type: application/json Body:

[
  {
    "loinc": "str, e.g. 718-7",
    "unit": "UCUM unit, e.g. g/dL",
    "value": "float, optional(=1.0)",
    "id": "anything_you_want, optional"
  }
]

Example

Query

POST http://localhost:8080/conversions HTTP/1.1
content-type: application/json

[
  {
    "loinc": "718-7",
    "unit": "g/dL",
    "value": 12,
    "id": "my_internal_id_22"
  },
  {
    "loinc": "59260-0",
    "unit": "mmol/l",
    "value": 10
  }
]

Result

[
  {
    "value": 12,
    "unit": "g/dL",
    "loinc": "718-7",
    "id": "my_internal_id_22"
  },
  {
    "value": 16.1,
    "unit": "g/dL",
    "loinc": "718-7"
  }
]

Configuration

Environment variable	Description	Default
LOG_REQUESTS	Whether all API requests should be logged to stdout.	false
PORT	The port to bind the web server to.	8080
LOINC_VERSION	The version of the LOINC database to use for conversion. Valid options: 2.67, 2.77	2.67

Development

Install Dependencies

npm install

Run with hot reload

npm run watch

The app now runs on http://localhost:8080/api/v1/conversions and restarts everytime a file in the src/ dir changes.

Run tests

npm run tests:e2e

This expects the app to run on http://localhost:8080. You can specify a different endpoint by setting the API_ENDPOINT env var.

Benchmark

# Processor Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz, 4001 Mhz, 4 Core(s), 8 Logical Processor(s)
# 32 GB DDR4 RAM @ 3600 MHz
$ bombardier -d 30s "http://localhost:8080/api/v1/conversions?loinc=718-7&unit=g%2FdL&value=10"
Bombarding http://localhost:8080/api/v1/conversions?loinc=718-7&unit=g%2FdL&value=10 for 30s using 500 connection(s)
[=================================================================================================================] 30s
Done!
Statistics        Avg      Stdev        Max
  Reqs/sec     15883.46    1672.96   52707.38
  Latency       31.51ms    45.90ms      2.76s
  HTTP codes:
    1xx - 0, 2xx - 476294, 3xx - 0, 4xx - 0, 5xx - 0
    others - 0
  Throughput:     5.61MB/s

Legal

This material contains content from LOINC (loinc.org). LOINC is copyright © 1995-2021, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.