API calls to SemEHR index

Types of documents

SemEHR contains four types of documents as follows.

• patient: patients;
• ctx_concept: contextualised concepts;
• eprdoc: clinical notes;
• medprofile: structured medical profiles.

Patient

API call

URL Prefix http://IP_ADDR:PORT/INDEX/patient/

1. Query patients (/_search/)

   RESTful Examples:

   • query patients by keyword hepatitis: /_search/?q=hepatitis
   • query patients by UMLS concept - CUI C0019158 (hepatitis): /_search/?q=C0019158
   • query patients by contextualised concept - EB07A6EF908CFC11B1B003E1B1CFA6C6 (CUI:C0019158, negation:Affirmed, temporality:Recent, experiencer:Patient): /_search/?q=EB07A6EF908CFC11B1B003E1B1CFA6C6

   Python examples:

query patients by keyword hepatitis

from elasticsearch import Elasticsearch

es_host = 'http://IP_ADDR:PORT/'
index_name = 'INDEX'
doc_type = 'patient'
query = 'hepatitis'
es = Elasticsearch([es_host])
results = es.search(index=index_name, doc_type=doc_type, body={'query': {'term': {'_all': query}}, 'size': 1})
print results

query patients by contextualised concept - EB07A6EF908CFC11B1B003E1B1CFA6C6

from elasticsearch import Elasticsearch

es_host = 'http://IP_ADDR:PORT/'
index_name = 'INDEX'
doc_type = 'patient'
query = 'hepatitis'
es = Elasticsearch([es_host])
results = es.search(index=index_name, doc_type=doc_type, body={'query': {'term': {'anns.contexted_concept': 'EB07A6EF908CFC11B1B003E1B1CFA6C6'}}, 'size': 1})
print results

2. Get patient data by id (/id)

   RESTful Example:

   • get patient by id - 99836 /99836/

   Python Example:

from elasticsearch import Elasticsearch

es_host = 'http://IP_ADDR:PORT/'
index_name = 'INDEX'
doc_type = 'patient'
query = 'hepatitis'
patient_id = '99836'
es = Elasticsearch([es_host])
result = es.get(index_name, patient_id, doc_type=doc_type)
print result

data structure

Patient's properties including anns (annotations), articles (clinical notes of the patient) and id (patient id).

• anns (indexed; stored; list of JSON object) all annotations identified in all the patient's clinical notes
  • CUI (type: keyword) the UMLS concept ID of the annotation;
  • appearances (type: list of JSON object) where the annotation appears;
    • date (type: date, in ticks) the date of the containing document;
    • eprid (type: keyword) the containing document id;
    • offset_end (type: long) the end offset of the original string in the containing document;
    • offset_start (type: long) the start offset of the original string in the containing document;
  • contexted_concept (type: keyword) the id of the contextualised concept (MD5 code of the string CUI_VoNEGATION_VoEXPERIENCER_VoTEMPORALITY).
• articles (indexed; not stored; type: list of JSON object) all clinical notes of the patient
  • eprid (type: keyword) the id of the clinical note
  • fulltext (type: text) the full text of the clinical note
• id (indexed; stored; type: keyword) the patient id

ctx_concept

API call

URL Prefix http://IP_ADDR:PORT/INDEX/ctx_concept/

1. Query contextualised concepts (/_search/)

   RESTful Examples:

   • query patients by keyword hepatitis: /_search/?q=hepatitis
   • query patients by UMLS concept - CUI C0019158 (hepatitis): /_search/?q=C0019158

   Python examples:

query ctx_concept by keyword hepatitis

from elasticsearch import Elasticsearch

es_host = 'http://IP_ADDR:PORT/'
index_name = 'INDEX'
doc_type = 'ctx_concept'
query = 'hepatitis'
es = Elasticsearch([es_host])
results = es.search(index=index_name, doc_type=doc_type, body={'query': {'term': {'_all': query}}, 'size': 1})
print results

query ctx_concept by contextualised concept - hepatitis, negation:Affirmed, temporality:Recent, experiencer:Patient

from elasticsearch import Elasticsearch

es_host = 'http://IP_ADDR:PORT/'
index_name = 'INDEX'
doc_type = 'patient'
query = 'hepatitis'
es = Elasticsearch([es_host])
results = es.search(index=index_name, doc_type=doc_type, body={'query':
                                                                   {
                                                                       'bool': {'must': [
                                                                           {
                                                                               'term': {'prefLabel': query}
                                                                           },
                                                                           {
                                                                               'term': {'temporality': 'Recent'}
                                                                           },
                                                                           {
                                                                               'term': {'negation': 'Affirmed'}
                                                                           },
                                                                           {
                                                                               'term': {'experiencer': 'Patient'}
                                                                           }
                                                                       ]
                                                                       }
                                                                   },
                                                               'size': 1})
print results

2. Get contextualised concept by id (/id)

   RESTful Example:

   • get patient by id - D118B8A0CE2CDDF84E67E124380C0E88 /D118B8A0CE2CDDF84E67E124380C0E88/

data structure

ctx_concept has properties as follows.

• STY (indexed; stored; keyword) - the semantic type of the concept
• CUI (indexed; stored; keyword) - the UMLS CUI of the concept
• experiencer (indexed; stored; keyword) - the experiencer contextual info of the concept (Patient or others)
• negation (indexed; stored; keyword) - the negation contextual info (Affirmed or Negated)
• prefLabel (indexed; stored; text) - the preferred label of the concept
• temporality (indexed; stored; keyword) - the temporality contextual info (Recent, History or Hypothetical)
• vocabularies (indexed; stored; text) - the vocabularies that contains the concept