Analyzing Text

Annotator for Clinical Data detects medical concepts within unstructured data. When you send unstructured data to the service to be analyzed and designate the desired annotators to employ, the service will route your unstructured data through the designated annotators and return the medical concepts detected within your unstructured data.

How it works:

Designate which annotators to employ in analyzing your unstructured data. This designation is defined as an annotator flow. See the Annotator flows section for more details.
Send your unstructured data along with the annotator flow to the service to extract the desired medical concepts.

Example: analyze request referencing a persisted flow:

curl -X POST --header "Authorization: Bearer xxxxxxxxxxxxxxx" \
--header "Content-Type: text/plain" \
--header "Accept: application/json" \
--data-binary "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan." \
"<route_host>/v1/analyze/your_flow_id?version=2020-03-13"

When referencing a persisted flow in an analyze request, you can send plain text to the service for analysis.

Example: analyze request within flow included:

curl -X POST --header "Authorization: Bearer xxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" -d "{
  \"annotatorFlows\": [
    {
      \"flow\": {
        \"elements\": [
          {
            \"annotator\": {

Annotator flows

Annotator flows define which annotators to employ on a given request and the order in which request data flows through the annotators. An annotator flow along with the unstructured data to be analyzed are the two required inputs for the service. Flows can either be defined dynamically as part of the request or persisted via the flows APIs and referenced as a path parameter on an analyze request, e.g. analyze/{flow_id}.

The analyze/{flow_id} API supports text/plain requests, whereas the analyze API, where the flow is defined within the request, requires you define both the flow and unstructured data to be analyzed in JSON format.

The following predefined flows are provided with the service:

Annotator Flow	Description
wh_acd.ibm_clinical_insights_v1.0_standard_flow	Annotator for Clinical Data provides a ready-to-use Clinical Insights flow that extracts clinically relevant information by performing deep contextual analysis of clinical notes. The Clinical Insights flow is a default configuration provided with Annotator for Clinical Data that produces clinical attributes for Prescribed Medications, Diagnoses, Therapeutic Procedures, and Diagnostic Procedures by contextually evaluating each type of clinical information to determine that it is both relevant and pertinent to the patient. See the Clinical Insights documentation for a detailed explanation. As new versions of the Clinical Insights flow are released, older versions will be deprecated and eventually retired. This is known as the version lifecycle. Annotator for Clinical Data will support two versions of the Clinical Insights flows, the current latest version and the previous version. This is known as an “n-1” version support scheme. Once an older version is marked as “deprecated”, a 90 day period will begin before the deprecated version is officially “retired” and no longer functional. The deprecated version will remain operational for a 90 day period before it is considered retired. Once a version has been retired, it will no longer be available and any attempts to use a retired version will fail.

Annotator Flow

Description

wh_acd.ibm_clinical_insights_v1.0_standard_flow

Annotator for Clinical Data provides a ready-to-use Clinical Insights flow that extracts clinically relevant information by performing deep contextual analysis of clinical notes. The Clinical Insights flow is a default configuration provided with Annotator for Clinical Data that produces clinical attributes for Prescribed Medications, Diagnoses, Therapeutic Procedures, and Diagnostic Procedures by contextually evaluating each type of clinical information to determine that it is both relevant and pertinent to the patient. See the Clinical Insights documentation for a detailed explanation.

As new versions of the Clinical Insights flow are released, older versions will be deprecated and eventually retired. This is known as the version lifecycle. Annotator for Clinical Data will support two versions of the Clinical Insights flows, the current latest version and the previous version. This is known as an “n-1” version support scheme. Once an older version is marked as “deprecated”, a 90 day period will begin before the deprecated version is officially “retired” and no longer functional. The deprecated version will remain operational for a 90 day period before it is considered retired. Once a version has been retired, it will no longer be available and any attempts to use a retired version will fail.

Table 1. Predefined annotator flows

Creating flows

The flows APIs are used to create and manage user-defined flows. Flows define both which annotators are to be employed in analyzed unstructured data as well as the order in which request data is routed through the annotator set. Request data is routed through the designated annotators serially. Many of the annotators are designed to act upon the output of other annotators - e.g. the concept detection annotator will pull in the section name of encompassing section annotations output by the section annotator. In order to take full advantage of this type of annotator cooperation, please follow the annotator ordering guidelines defined in the table below for the applicable annotators in your flow.

Order	Annotators
1	section
2	concept_detection allergy bathing_assistance cancer dressing_assistance eating_assistance ejection_fraction lab_value medication named_entities procedure seeing_assistance smoking symptom_disease toileting_assistance walking_assistance
3	disambiguation
4	concept_value
5	hypothetical negation
6	relation
7	model_broker
8	attribute_detection

Table 2. Recommended annotator flow ordering

Unstructured data input

By default, the unstructured data input sent to the service is not returned in the response and the following characters are encoded in the response to protect against cross-site scripting attacks in the event the output is rendered within a browser. If you want the unstructured data input sent back in the response and you do not want the following characters encoded, include the following query parameter on the analyze request return_analyzed_text=true.

Response

A sample response is shown below when the default setting (i.e. return_analyzed_text=false) is used and the encoding process is activated. Notice that the begin and the end field of the concepts are not affected by the character encoding. Set return_analyzed_text=true to avoid the encoding results and to show the analyzed text in the response.

{
    "unstructured": [
        {
            "data": {
                "conceptValues": [
                    {
                        "cui": "C0005893",
                        "preferredName": "Body mass index procedure",
                        "trigger": "greater than",

Using ACD: Custom Resource APIs

Using ACD: Customizing