Submitting Documents to NLP API

The NLP API SDK comes with libraries and clients for Python and Java. The libraries can be used to build your own custom client to integrate the NLP API’s processing into your application suite to meet your business needs. The clients are provided to illustrate what a working client looks like and can serve as a starting point for application design.

This document walks a user through submitting documents for processing using the Python SDK client, with additional generic information required for document submission for users wishing to build their own clients using the SDK or API specification.

In submitting documents to the NLP API for structured data extraction, several things are needed:

1. The data and some metadata, including:

   1. The data: medical text
   2. Metadata: a unique identifier (an alphanumeric string, with no spaces)
   3. Metadata: optionally, a report category and a report subcategory (see the section on these below)

2. Public and private key files supplied to you by emtelligent.

3. The URL for the NLP API processing engine that you have been given access to by emtelligent.

4. Client software - either developed by you using the API specification and SDK libraries, or one of the pre-built clients supplied in the SDK.

5. A decision about which text features you wish to extract (N.B. depending on your contract with emtelligent, only certain features may be available):

   1. Which ontologies you want to use for named entity recognition - the choices are SNOMED-CT, ICD-10, ICD-10-CM, RadLex, the RadLex Playbook, MEDCIN, RxNorm, UMLS NCI, UMLS HGNC, UMLS LOINC, and the emtelligent ontology
   2. Which relations you wish to extract, e.g. experiencer relations, to identify who (if specified) experienced a medical condition, procedure, medication, etc.
   3. Which entity attributes you wish to extract, e.g. polarity - whether a named entity is asserted (“The patient has cancer”) or negated (“The patient does not have cancer”)

   The full set is described in Processing Options below.

Customers wishing to write their own client from scratch using the API specification are welcome to do so, although all of the above requirements still apply or the NLP API engine will return an error.

Understanding Report Categories and Subcategories

Medical text is frequently ambiguous. The acronym ‘CAD’ in a clinical note usually indicates the author is talking about ‘coronary artery disease’. However, in a mammography report, ‘CAD’ usually refers to computer-aided detection software, used to aid the radiologist in detection of subtle breast lesions.

The NLP API uses preexisting knowledge about medical documents stored in medical software systems like EMRs to improve the specificity of its output to reduce ambiguity and processing mistakes. Users submitting documents for processing to the NLP API should therefore indicate what kind of document it is in the document submission.

The possible document categories and subcategories for processing are defined in the API specification here.

Both the category and the subcategory are optional. When they are not supplied, the NLP API detects the report kind automatically and reports the detected values in the output, where the method member of each document attribute records whether the value was supplied in the input (manual) or detected by the NLP API (automatic); see Understanding the NLP API Output. Automatic detection is not enabled in every installation of the NLP API, so supplying the report kind remains the most reliable option where it is known. A report kind that is supplied in the input is always used as given.

Processing Options

The features that you can use are grouped into four categories and listed in the sections that follow:

• Attributes
• Ontology
• Relations
• Document

Note that the features available to you may be restricted by your licensing agreement. To enable a feature you do not currently have access to, contact support@emtelligent.com.

The most up-to-date list of features is found in the API documentation for /submit found here.

Attributes

• entity-polarity: Extract polarity (negation status) for entities.
• entity-uncertainty: Extract uncertainty for entities.
• entity-question-status: Extract whether the entity is used in the context of a question (e.g.Assess for C-spine injury.).
• entity-known-ambiguity: Extract whether the entity is an ambiguous term (e.g. PT which could mean physical therapy, patient ). This attribute reflects the inherent ambiguity as used by clinicians.
• entity-guidance: Extract whether the entity is used in the context of a statement that provides guidance about the imaging modality or procedure used (e.g. CT cannot reliably exclude early infarct).
• entity-measurement-unit: Extract measurement units for entities.
• entity-factuality: Extract whether the entity mention is factual, hypothetical (e.g. part of an “if” statement, a differential diagnosis, or something scheduled for the future), or generic (e.g. part of a general knowledge, educational or reference statement rather than a finding about the patient).
• entity-experiencer: Extract who experiences the entity, as a string such as patient, mother, or provider. This is a simpler alternative to following experiencer-relations when all you need is to restrict a search to the patient’s own findings.
• entity-concept-link-confidence: Extract confidence scores for entity concept links, on the ontologies that support it.
• entity-contextual-validity: Use a wider context to validate entity concept links and negation. This produces no additional output; it improves the precision of the concept links and of the polarity attribute. It is more compute intensive than the other attribute features, and is most useful on noisier sources such as clinical notes.

Note that entity-factuality overlaps with entity-uncertainty, entity-question-status, and entity-guidance: it is a single, more general attribute covering much of what those three cover individually.

Ontology

• snomed-ontology: Map to concepts in SNOMED-CT.
• snomedicd10-ontology: Map to ICD-10 concepts using SNOMED-CT’s ICD-10 reference set.
• snomedicd10cm-ontology: Map to ICD-10 concepts using SNOMED-CT’s ICD-10 CM reference set.
• radlex-ontology: Map to concepts in RadLex.
• radplaybook-ontology: Map to concepts in the Radlex Playbook.
• medcin-ontology: Map to concepts in MEDCIN.
• rxnorm-ontology: Map to concepts in RxNorm.
• umlsnci-ontology: Map to concepts in UMLS NCI.
• umlshgnc-ontology: Map to concepts in UMLS HGNC.
• umlsloinc-ontology: Map to concepts in UMLS LOINC.
• emtelligent-ontology: Map to concepts in Emtelligent’s entity identification set.

Relations

• experiencer-relations: Identify experiencer relations - e.g. ‘the patient’s mother had carpal tunnel syndrome’.
• qualifier-relations: Identify qualifier relations - these capture a modification relation of a concept, e.g. ‘mild-to-moderate stenosis’ or ‘large parenchymal mass’. The kind of modification is reported in the qualifier_type attribute of each relation; see QualifierRelation in the NLP API output result schema.
• measurement-relations: Identify measurement relations - e.g. ‘In the right adrenal gland, there is a mass that measures 4.2 cm’.
• medication-relations: Identify medication prescription information - e.g. ‘Aspirin 81 mg p.o. one q.d.’
• temporality-relations: Identify temporal relations indicated by historical mentions and specific dates - e.g. ‘status post procedure’, ‘2016/8/13 patient presented to her primary care physician with complaints of chest pain’
• followup-relations: Identify followup recommendations - e.g. ‘A follow-up CT scan in 3 months time is recommended to exclude malignancy’.
• imagelink-relations: Identify image reference relations - e.g. ‘The left kidney contains a low-attenuation lesion in the lower pole (series 2, image 42)’.
• reportedevent-relations: Identify critical communications - e.g. ‘Findings were discussed with Dr. Smith at 1:30 p.m. by Dr. Jones by phone’.
• anatomicsite-relations: Identify anatomic site relations - e.g. ‘She developed re-stenosis in her iliac arteries.’

More information about using relations for data retrieval and analysis see Relations Feature Introduction.

Document

• text: Store the text for recognized terms in addition to span offsets, and the text of the whole document. You can omit this option to minimize the size of the results. Text for recognized terms can be calculated from the document’s text using their span offsets.
• document-infer-structure: Rewrite the text of the document to restore structure such as tables and line breaks before it is processed. This is for text input only, and is intended for extremely poorly formatted input where newlines are no longer part of the document and any markings that indicated table structure have been stripped out; such documents lose the layout that NLP API relies on to find sections and to extract relations, particularly measurement relations in tabular data. It is not intended for documents that still carry their original formatting. Because the feature replaces the document text, the rewritten text is returned in the text member of the document and is what all of the spans in the output refer to.

Additional Considerations

• When no features are specified, a default set of features is enabled that depends on how your NLP API deployment was configured. This set is chosen at deployment time; for the list of default features on your API server, contact Emtelligent.
• If you specify features, then you must also select at least one ontology feature. Otherwise the engine will return no output.
• followup-relations, and imagelink-relations features are specific to Radiology reports; i.e. they are only extracted from reports processed with category set to Radiology. Furthermore, these relation features are only extracted from the FINDINGS and IMPRESSION sections of Radiology reports (or equivalently-named sections).
• The engine automatically enables the emtelligent-ontology option when any relation is used (with the exception of the experiencer-relation) to ensure that the relations will be able to match as many arguments as possible.
• The entity-measurement-unit option can be used independently of measurement-relations or in combination with measurement-relations.
• entity-factuality, entity-experiencer, entity-contextual-validity, and document-infer-structure are compute intensive and are not enabled by default; they have to be requested explicitly.

Using features in the Python client and SDK

Users should consider which data extraction features they require for a given task. The number of features used increases the processing time and may result in a larger amount of output being returned than is optimal. Hence, it is recommended that you use the NLP API client options to select a subset of features as required for your use case.

Providing processing features to the NLP API is covered in the Python SDK docs and in particular:

• Choosing processing features in the NLP API Python client is found in Python client options.
• Choosing processing features in the NLP API Python SDK is found in Building your own client documentation.

Understanding NLP API’s Job Submission Workflow

The NLP API engine waits for processing jobs to be submitted to it. A job could be a single report or a batch containing multiple reports. A single job usually only takes a few seconds or so to process (depending on the length of the text submitted, and the number of features requested to be extracted), while larger jobs may take hours to process.

When a user sends a job to the NLP API, this initial send is called a submission. The example clients use the command line argument submit to indicate to the engine that they are sending in some text for processing. Once the engine has fully received the submission, it returns a task id to the client to use for tracking this task.

As some jobs may take quite a while to process, a user may wish to receive continual status updates on the job progress, to see how many reports have been processed. In this case, the client will use the command line argument watch, sent along with the task id to the NLP API to inquire for information on the processing status.

Finally, when a job has been completed, the NLP API holds the result until the user sends a download request for it, or until the global report holding timeout (usually 24 hours) passes. At any time before this timeout, the user can download the structured data output from the NLP API by sending in a download request along with the task id.

In an alternate workflow, users can specify an optional callback URL to the NLP API on job submission. When the job is done processing, the NLP API will issue an HTTP GET request to the callback URL to indicate the job status (success, i.e. the job is complete or failure, i.e. there was an issue processing the job).

Maximum Submission Size

The NLP API engine will accept submissions up to a maximum submission size of approximately 500 MB, although this can be configured on a per-customer basis. Individual installations of the NLP API might limit the size of text documents (not XML or PDF) to smaller values (say 2MB) to avoid spending time processing a document which has the incorrect file name suffix (e.g. a PDF file sent with a .txt file suffix). The Python SDK will shard the submission documents to fit within this size limit, and the Python SDK sets a fixed overhead of 10 KB for headers for each submit request and 1 KB for auth overhead per document in each submit request.

Summary

This document has hopefully introduced the concepts of document submission and the required metadata elements to get the reader started with document processing using the NLP API. More documentation about the Python clients is provided in the Python SDK docs and about the Java client in the Java SDK docs.