Document Analysis API

In this tutorial, we will employ the Document Analysis API to convert unstructured clinical data, (e.g., History & Physical notes), into structured data elements.

The Document Analysis API normalizes unstructured free text. The identified terms include rich metadata mappings to multiple coding systems (e.g., SNOMED-CT, ICD-10-CM, etc.).

The API is intended to be invoked with single records at a time, for example, the text from clinical notes for a single note.

Setup

Start with a record of unstructured free text.

NLP Example Text:

Chief Complaint: “chest pain” HPI: -- is a 76 yo man with h/o HTN, DM, and sleep apnea who presented to the ED complaining of chest pain. He states that the pain began the day before and consisted of a sharp pain that lasted around 30 seconds, followed by a dull pain that would last around 2 minutes. The pain was reported as left chest pain. The onset of pain came while the patient was walking in his home. He did not sit and rest during the pain but continued to do household chores. Later on in the afternoon he went to the gym where he walked 1 mile on the treadmill, rode the bike for 5 minutes, and swam in the pool. He did not have any reoccurrences of chest pain while at the gym or later in the evening. The following morning (of his presentation to the ED) he noticed the pain as he was getting out of bed. Once again it was a dull pain, preceded by a short interval of a sharp pain. The patient did experience some tingling in his right arm after the pain ceased. He continued to have several episodes of the pain throughout the morning, so his daughter-in-law decided to take him to the ED around 12:30pm. The painful episodes did not increase in intensity or severity during this time. At the ED the patient was given nitroglycerin, which he claims helped alleviate the pain somewhat. -- has not experienced any shortness of breath, no nausea, or no diaphoresis during these episodes of pain. He has never had chest pain in the past. He was told “years ago” that he has a right bundle branch block and premature heart beats. Procedure History: he had an colonoscopy in 2002.

API Usage

The API can be accessed at: https://api.imohealth.com/documentanalysis.

An IMO Precision Normalize agreement is necessary to receive authentication credentials.

Following entering an agreement, API keys are provided and can be used to generate tokens. For more information, contact IMO Customer Support.

Authentication

Authentication is performed using OAuth 2.0 Bearer tokens which requires an IMO-provided client ID and secret.

The following code snippets demonstrate retrieving auth tokens:

curl

curl -u "<API Key>:<API Secret>" \
--data "grant_type=client_credentials&audience=https://api.imohealth.com" \
"https://api.imohealth.com/oauth/token"

python

import requests 

data =  { 
    'grant_type':'client_credentials', 
    'client_id':'&lt;API_KEY&gt;', 
    'client_secret':'&lt;API_SECRET&gt;', 
    'audience':'https://api.imohealth.com' 
} 

response = requests.post( 
    url     = "https://auth.imohealth.com/oauth/token", 
    json    = data 
) 
response = response.json() 

auth_token = response['access_token'] 
print(auth_token)

How to call the Document Analysis API

The Document Analysis API leverages Large Language Models (LLMs) for the identification of clinically relevant terms within unstructured text.

Description: This API will extract and classify Problem and Procedure terms from the unstructured clinical text provided. These terms will include mappings to external vocabularies, such as SNOMED and ICD.

This functionality can be reached via a POST request to the /documentanalysis HTTP endpoint, as shown in the examples below:

curl

curl -X POST \
-H "Authorization: Bearer &lt;AUTH_TOKEN&gt;" \ 
-H "Content-Type: application/json" \  
-data "{'text': 'PROCEDURE PERFORMED: Colonoscopy FINDINGS: A 10 mm polyp was found in the cecum. The polyp was removed with a hot snare.'}"\ 
"https://api.imohealth.com/documentanalysis"

python

import requests 

auth_token='&lt;AUTH_TOKEN&gt;' 
headers = {'Authorization': 'Bearer ' + auth_token} 
data = {'text': 'PROCEDURE PERFORMED: Colonoscopy FINDINGS: A 10 mm polyp was found in the cecum. The polyp was removed with a hot snare.', 'preferences': {'domain_filter': ['procedure']}} 

response = requests.post(
    url     = https://api.imohealth.com/documentanalysis,
    json    = data,
    headers = headers
} 

print(response.json())

Response

{
    "filename": "",
    "content": "PROCEDURE PERFORMED: Colonoscopy FINDINGS: A 10 mm polyp was found in the cecum. The polyp was removed with a hot snare.",
    "entities": [
        {
            "id": "b2b73969-e958-4e87-bfda-874fe67da013",
            "text": "Colonoscopy with polypectomy using hot snare",
            "type": "clinical_ai",
            "semantic": "procedure",
            "semantic_category": "",
            "section": null,
            "assertion": "",
            "explanation": "The procedure performed was a colonoscopy, during which a 10 mm polyp was found in the cecum and removed using a hot snare. This indicates a polypectomy was performed using the hot snare technique.",
            "codemaps": { "imo": { "default_lexical_code": "33338396", "default_lexical_title": "Colonoscopy with removal of polyp using snare technique", "lexical_code": "33352792", "lexical_title": "Colonoscopy with snare polypectomy", "confidence": "0.993" }, ... "cpt": {"codes": [ { "code": "45385", "title": "Colonoscopy w/lesion removal", "map_type": "Preferred primary",, ...     } ] }, ...},
        }
    ],
    "text_id": "fef87500-c5d1-42f6-aa05-a83ea7316814",
    "pipeline": {
        "name": "documentanalysis"
    },
    "preferences": {
        "thresholds": {
            "problem": 0.85,
            "procedure": 0.85
        },
        "type_filter": [
            "entities"
        ],
        "domain_filter": [
            "procedure"
        ]
    },
    "metadata": {}
}

(Note: The response above is truncated to display a brief selection of meaningful normalization. To view the full schema of the response, see the Reference Documentation tab for Document Analysis.)

Summary

You sent a call to the Document Analysis API with a goal to extract computable, clinician-friendly IMO terms from clinical unstructured free text. The API used NER to extract and classify Problem and Procedure terms from the unstructured clinical text provided.

Our NLP Service takes a 2-step approach to getting you clinically relevant codes for your unstructured text.

Identify clinical entities, which are shown in the entities array in the response.
Resolve the entities to standard code sets (e.g., ICD, SNOMED, IMO). See codemaps property of an Entity.

Notices

SNOMED®️ and SNOMED CT®️ are registered trademarks of IHTSDO.

LOINC®️ is a registered United States trademark of Regenstrief Institute, Inc.

RxNorm is publicly available data courtesy of the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services.