Averbis Health Discovery: User Manual

^{Version 6.1.0, 06/08/2021}

0. Changes in Health Discovery 6.0

Averbis Health Discovery GUI enables you to no longer be limited to using the REST API in your production scenario. You can now also import documents into Health Discovery and get the results easily via bulk export.

But the Health Discovery version 6 has much more to offer. You can look forward to:

• a seamless integration of the REST API into Python
• new enhancements and changes to the API format
• Apache UIMA v3 upgrade
• lots of new and improved annotators

1. Overview

Health Discovery is a text mining and machine learning platform for analyzing large amounts of patient data. With Health Discovery, medical documents can be analyzed and searched for diagnoses, symptoms, prescriptions, special findings, and other criteria. Heterogeneous patient data in both structured and unstructured forms can be harmonized and analyzed by text mining, and can be accessed and searched via a unified interface.

Health Discovery has a modular structure. The various functionalities are roughly divided into the following categories:

• General: There are some general modules in which projects and users with corresponding rights and roles can be created.

• Sources: There are several ways to invite documents to Health Discovery. Documents can be imported from your own client or from any server from file or database.

• Terminology: Health Discovery allows you to create your own terminology or import terminologies. These can be integrated into text mining, and terms of these terminologies can be found in texts.

• Text Analysis: This category contains various modules for configuring text mining pipelines, starting text mining processes, and viewing text mining results. Different text mining pipelines can also be compared with each other.

• Search: Health Discovery contains a semantic full-text search that can be configured and used in the various modules of this category.

• Classification: Health Discovery contains a machine learning-based classification module. Users can sort documents manually or automatically into different categories. An intuitive interface enables the training and evaluation of machine learning models.

The user manual is intended to give you a quick introduction to Health Discovery with the "Getting started" section. Then the text mining components and pipelines that are included in Health Discovery are described in detail.

2. Getting started

2.1. Login to Health Discovery and create a project

Step 1: Enter the URL of Health Discovery in a web browser and login with your user name and password. If you don’t know the URL or your credentials, contact your system administrator.

Step 2: To create a new project go to the "Project Administration" section (1) and click the button "Create Project" (2).

Step 3: Enter a project name into the field "Name" (3) of the dialog "Create Project" and click "Save" (4).

After the project was created successfully, you can open the project by clicking on the newly added name in the list of the "Project Administration" section.

2.2. Import documents

Step 1: On page "Home", select "Project Administration" and click on a project name. You are redirected to the "Project Overview" page of this project.

Step 2: On the "Project Overview" page, choose module "Import Documents", click on "New Import", give your import batch a name, select the Importer Type "Text Importer" and the documents to be imported. You can import a single file or a zip container with multiple files.

Step 3: By clicking on "Import", the document import starts. You can click on the "Refresh" button to the right of your document import to see the progress.

2.3. Run a text mining process

Health Discovery typically contains predefined pipelines that are already available when the application starts. Therefore, you can start text mining processing immediately after importing the first documents. This goes as follows:

Step 1: On the "Project Overview" page, select "Pipeline Configuration" and start a text mining pipeline, e.g "discharge"

Step 2: Switch back to "Project Overview" and select "Processes".

Step 3: Click on "New Text Analysis"

Step 4: Give your text mining process a name, select the document source and the text mining pipeline, and click Ok.

Step 5: The text analysis starts now. By clicking on the browser refresh you can monitor the progress of the text analysis.

2.4. View text mining results

As soon as a text mining process has the state "idle", you can see the results in the Annotation Editor by clicking on the process name.

The Annotation Editor shows the results of your text analytic process.

2.5. Configure your own pipeline

If you want to build your own pipeline from existing text mining components, proceed as follows:

Step 1: In "Project Overview", click on "Pipeline Configuration".

Step 2: Click on "Create Pipeline".

Step 3: Give your pipeline a name, optionally a description and click on "Ok".

Step 4: Click the pen icon ("Edit Pipeline") to the right of your pipeline.

Step 5: Select the desired components from the components on the right by clicking on the corresponding left arrow. For more information about the available components and which upstream components they require, see Available Text Mining Annotators & Web Service Specification

2.6. Create your first terminology

If you want to create your own terminology, proceed as follows:

Step 1: In "Project Administration", select "Terminology Administration".

Step 2: Click on "Create Terminology".

Step 3: Assign a "Terminology ID", a "Label", a "Version". Choose whether the terminology should have a hierarchy or not. Leave the "Concept type" on "de.averbis.extraction.types.Concept" and the "Encrypted export" on disabled. Select the language(s) in which the terminology is to be created. Then click on "Ok".

Step 4: Switch to the "Terminology Editor" by going to the "Project Overview" page and clicking on "Terminology Editor".

Step 5: Click on the "plus" to the right of your terminology to create the first concept.

Step 6: Enter a "Concept ID", a "Preferred Term" and optionally a "Comment" and click "Ok".

Step 7: By clicking on the button "Add Terms" you can add more synonyms to the concept. If you want to add more than one synonym, click on "add another term". Once all synonyms have been inserted, click on "Ok".

Step 8: By clicking on the "plus" to the right of your newly created concept you can create further sub-concepts.

2.7. Download your terminology

Step 1: Go to "Terminology Administration" module.

Step 2: Choose your terminology and click the icon "Preparing OBO download".

The preparation time depends on the size of your terminology. Once the download is ready, a notification appears in the bell symbol in the upper menu bar.

Step 3: Refresh the page using the refresh-button. Now the button for downloading the terminology is activated.

Step 4: Click on the download icon and save the the OBO file.

2.8. Integrate own terminologies into a text mining pipeline

You can import your own terminologies to Health Discovery. Optionally, a mapping mode for each synonym can be imported, too. To import terminologies, you must convert them to the OBO file format. The minimal structure of your OBO terminology looks like the example below.

synonymtypedef: DEFAULT_MODE "Default Mapping Mode" 
synonymtypedef: EXACT_MODE "Exact Mapping Mode"      
synonymtypedef: IGNORE_MODE "Ignore Mapping Mode"   

[Term]
id: 1
name: First Concept
synonym: "First Concept" DEFAULT_MODE []
synonym: "First Synonym" IGNORE_MODE [] 
synonym: "Second Synonym" EXACT_MODE [] 
 
[Term] id: 2 name: First Child is_a: 1 ! First Concept

To import terms with mapping modes, the OBO terminology begins with the synonym type definitions ("synonymtypedef"), as shown in the first three lines of the OBO terminology in the example above. The "synonymtypedef" are optional and need only to be applied when using mapping modes. Each concept begins with the flag "[TERM]", followed by an "id" and a preferred name with the flag "name". After that you can add as many synonyms as you like with the flag "synonym", followed by the desired mapping mode (optionally). Note: if you would like to define a mapping mode for your concept name, you have to add the term as synonym, as shown in the example for "First Concept". Furthermore, if your terminology contains a hierarchy, you can use "is_a" to refer to other concepts of your terminology.

2.8.1. Import a terminology

To import a terminology like the one shown above, proceed as follows:

Step 1: In "Project Overview", click on "Terminology Administration".

Step 2: Click on "Create New Terminology". Fill in the dialog as described in Create your first terminology.

Step 3: Once you have created a terminology, click the up arrow icon to the right of the terminology.

Step 4: In the "Import Terminology" dialog, select "OBO Importer" as import format. Then select the terminology you want to import from the file system. Click on "Import".

Step 5: By clicking on the "Refresh" button to the right of the terminology you can check the progress of the import. When the terminology has been fully imported, the state changes to "Terminology imported".

Step 6: To browse your terminology, switch to the "Terminology Editor" by going to the "Project Overview" page and clicking on "Terminology Editor".

After successful terminology import, terms, hierarchies and mapping modes can be checked in the Terminology Editor.

2.9. Use the Web Service

All text mining pipelines configured and started in Health Discovery can also be accessed via web service. To do this, proceed as follows:

Step 1: Add the suffix "/rest/swagger-ui.html" to the URL of Health Discovery (e.g. https://<YOURURL>/health-discovery/swagger-ui.html)

Step 2: In the green upper menu bar, select the spec "REST API v1"

Step 3: Click on "Text Analysis" and then on "/ /rest/v1/textanalysis/projects/{projectName}/pipelines/{pipelineName}/analyseText ".

Step 4: Click on the button on the upper right "Try it out"

Step 5: Add API token as a string to "api-token" (1) (for more details of generating an API token follow this Link REST API Overview), "discharge" to pipelineName (2) (or the name of another started pipeline) and "default" to "projectName" (3).

Step 6: Add any text in the field "text".

Step 7: The field "language" can be left blank for the "discharge" pipeline, as the pipeline automatically recognizes the language.

Step 8: Click on the blue botton "Execute" on the buttom left (4).

Step 9: You receive the response in the response body section.

3. Available Text Mining Annotators & Web Service Specification

Health Discovery contains a number of pipelines and text mining components. These can be configured in the "Pipeline Configuration" module. The individual components are described below. In addition to a short description of the component, it specifies which types the components require as input and which type they generate. A web service example of an annotation of the corresponding type is also given.

3.1. BiologicallyDerivedProducts

3.1.1. Description

A biologically derived product is a material substance originating from a biological entity intended to be transplanted or infused into another biological entity. Examples for a biologically derived product include hematopoietic stem cells such as bone marrow, peripheral blood, or cord blood extraction. This annotator extracts the information about the type of the transplanted biological product, the amount of transplanted cells and the date in the context of allogeneic transplantations.

Currently, the annotation is limited to the extraction of the biological product of CD34-positive stem cells.

3.1.2. Input

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.1.3. Output

Annotation Type: de.averbis.types.health.BiologicallyDerivedProduct

3.1.4. Terminology Binding

3.1.5. Web Service Example

Text Example: "On 11/11/2008 transfusion of 4.5x 106 CD34-positive cells/kg"

{
      "begin": 29,
      "end": 42,
      "type": "de.averbis.types.health.BiologicallyDerivedProduct",
      "coveredText": "4.5x 106 CD34",
      "id": 1839,
      "negatedBy": null,
      "quantity": 4500000,
      "matchedTerm": "CD34+",
      "dictCanon": "CD34+",
      "conceptID": "78002-3",
      "source": "Averbis-Lab-Terminology_2.0",
      "time": {
        "begin": 3,
        "end": 13,
        "type": "de.averbis.types.health.Date",
        "coveredText": "11/11/2008",
        "id": 1840,
        "kind": "DATE",
        "value": "2008-11-11"
      },
      "uniqueID": "Averbis-Lab-Terminology_2.0:78002-3
}

3.2. Chimerism

3.2.1. Description

This component annotates information about chimerism. In the field of transplantation medicine, a chimerism analysis is performed after stem cell or bone marrow transplantation to determine whether the recipient’s hematopoietic system is only derived from the donor or not. The chimerism is called "complete" if more than 95% of the tested hematopoietic cells originate from the donor, otherwise the chimerism is called "mixed".

3.2.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.2.3. Output

Annotation Type: de.averbis.types.health.Chimerism

3.2.4. Web Service Example

Text Example: "Chimärismusanalyse vom 17.11.2008: Nachweis von 85,2 % Donorzellen."

    {
      "begin": 48,
      "end": 66,
      "type": "de.averbis.types.health.Chimerism",
      "coveredText": "85,2 % Donorzellen",
      "id": 1469,
      "date": null,
      "kind": "MIXED",
      "value": 85.2
    }

3.3. Clinical Section Keyword 

3.3.1. Description

Clinical Section Keyword is a keyword from which an eventual Clinical Section is derived, e.g. "Patient History" is a keyword for Anamnesis Section. Not every Clinical Section Keyword leads to a Clinical Section.

3.3.2. Input

Above this annotator, the following annotators must be included in the pipeline

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.3.3. Output

Annotation Type: de.averbis.types.health.ClinicalSectionKeyword

3.3.4. Terminology Binding

3.3.5. Web Service Example

Text Example: "Medication Citation|Active|CM| TraMADol HCl - 50 MG Oral Tablet;TAKE 1 TABLET 3 TIMES DAILY.; RPT~Tylenol Arthritis Ext Relief 650 MG TBCR;TAKE 1 TABLET 3-4 TIMES DAILY.; RPT~CeleBREX 200 MG Oral Capsule;TAKE 1 CAPSULE DAILY.; RPT~Folbic TABS;; RPT~Folic Acid 1 MG Oral Tablet;TAKE 1 TABLET DAILY.; RPT~PredniSONE 10 MG Oral Tablet;TAKE 1 TABLET AS NEEDED.; RPT~Cholestyramine 4 GM Oral Packet;MIX THE CONTENTS OF 1 POWDER PACKET WITH 2 TO 6 OZ OF NONCARBONATED BEVERAGE AND DRINK 3 TIMES DAILY.; RPT~Methotrexate 2.5 MG Oral Tablet;TAKE 1 TABLET WEEKLY.; RPT~Citracal Plus Oral Tablet;TAKE 2 TABLET DAILY; RPT~Multi Vitamin Daily TABS;TAKE 1 TABLET DAILY.; RPT~Miscellaneous Medication;Schiff "Move Free". 400 MG taken once daily; RPT"

    {
      "begin": 0,
      "end": 10,
      "type": "de.averbis.types.health.ClinicalSectionKeyword",
      "coveredText": "Medication",
      "id": 16279,
      "negatedBy": null,
      "matchedTerm": "Medication",
      "dictCanon": "Medication",
      "conceptID": "29549-3",
      "source": "clinical_sections_en",
      "uniqueID": "clinical_sections_en:29549-3"
    },
    {
      "begin": 676,
      "end": 686,
      "type": "de.averbis.types.health.ClinicalSectionKeyword",
      "coveredText": "Medication",
      "id": 16280,
      "negatedBy": null,
      "matchedTerm": "Medication",
      "dictCanon": "Medication",
      "conceptID": "29549-3",
      "source": "clinical_sections_en",
      "uniqueID": "clinical_sections_en:29549-3"
    }

3.4. Clinical Section 

3.4.1. Description

This component detects sections in medical documents. These sections can refer to diagnoses, medications, therapies, etc.

3.4.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.4.3. Output

Annotation Type: de.averbis.types.health.ClinicalSection

3.4.4. Terminology Binding

3.4.5. Web Service Example

Text Example: "Medication Citation|Active|CM| TraMADol HCl - 50 MG Oral Tablet;TAKE 1 TABLET 3 TIMES DAILY.; RPT~Tylenol Arthritis Ext Relief 650 MG TBCR;TAKE 1 TABLET 3-4 TIMES DAILY.; RPT~CeleBREX 200 MG Oral Capsule;TAKE 1 CAPSULE DAILY.; RPT~Folbic TABS;; RPT~Folic Acid 1 MG Oral Tablet;TAKE 1 TABLET DAILY.; RPT~PredniSONE 10 MG Oral Tablet;TAKE 1 TABLET AS NEEDED.; RPT~Cholestyramine 4 GM Oral Packet;MIX THE CONTENTS OF 1 POWDER PACKET WITH 2 TO 6 OZ OF NONCARBONATED BEVERAGE AND DRINK 3 TIMES DAILY.; RPT~Methotrexate 2.5 MG Oral Tablet;TAKE 1 TABLET WEEKLY.; RPT~Citracal Plus Oral Tablet;TAKE 2 TABLET DAILY; RPT~Multi Vitamin Daily TABS;TAKE 1 TABLET DAILY.; RPT~Miscellaneous Medication;Schiff "Move Free". 400 MG taken once daily; RPT"

 {
      "begin": 0,
      "end": 734,
      "type": "de.averbis.types.health.ClinicalSection",
      "coveredText": "Medication Citation|Active|CM\nTraMADol HCl - 50 MG Oral Tablet;TAKE 1 TABLET 3 TIMES DAILY.; RPT~Tylenol Arthritis Ext Relief 650 MG TBCR;TAKE 1 TABLET 3-4 TIMES DAILY.; RPT~CeleBREX 200 MG Oral Capsule;TAKE 1 CAPSULE DAILY.; RPT~Folbic TABS;; RPT~Folic Acid 1 MG Oral Tablet;TAKE 1 TABLET DAILY.; RPT~PredniSONE 10 MG Oral Tablet;TAKE 1 TABLET AS NEEDED.; RPT~Cholestyramine 4 GM Oral Packet;MIX THE CONTENTS OF 1 POWDER PACKET WITH 2 TO 6 OZ OF NONCARBONATED BEVERAGE AND DRINK 3 TIMES DAILY.; RPT~Methotrexate 2.5 MG Oral Tablet;TAKE 1 TABLET WEEKLY.; RPT~Citracal Plus Oral Tablet;TAKE 2 TABLET DAILY; RPT~Multi Vitamin Daily TABS;TAKE 1 TABLET DAILY.; RPT~Miscellaneous Medication;Schiff \"Move Free\". 400 MG taken once daily; RPT",
      "id": 16310,
      "label": "Medication",
      "keyword": {
        "begin": 0,
        "end": 10,
        "type": "de.averbis.types.health.ClinicalSectionKeyword",
        "coveredText": "Medication",
        "id": 16311,
        "negatedBy": null,
        "matchedTerm": "Medication",
        "dictCanon": "Medication",
        "conceptID": "29549-3",
        "source": "clinical_sections_en",
        "uniqueID": "clinical_sections_en:29549-3"
 }

3.5. Diagnoses

3.5.1. Description

This component detects a condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern. Optional: As an additional annotation to the diagnoses component  DiagnosisCandidate can be visualized too. This component can be optionally activated which specifically detect diagnosis candidates to optimize DRG coding.

3.5.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• LabValues

To get the full functionality, the following annotators should also be included below this annotator in the given order:

• Enumerations

• Negations
  

• DiagnosisStatus

• Disambiguation

3.5.3. Output

Annotation Type: de.averbis.types.health.Diagnosis

Annotation Type (optional): de.averbis.types.health.DiagnosisCandidate

3.5.4. Terminology Binding

3.5.5. Web Service Example

Text Example for Diagnosis: "suspected history of appendicitis"

    {
      "begin": 10,
      "end": 33,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "history of appendicitis",
      "id": 788,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "History of appendicitis",
      "verificationStatus": "SUSPECTED",
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": "RESOLVED",
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Personal history of other diseases of the digestive system",
      "conceptID": "Z87.19",
      "belongsTo": null,
      "uniqueID": "ICD10CM_2021:Z87.19"
    }

Text Example for DiagnosisCandidate: "suspected history of appendicitis"

    {
      "begin": 10,
      "end": 33,
      "type": "de.averbis.types.health.DiagnosisCandidate",
      "coveredText": "history of appendicitis",
      "id": 788,
      "verificationStatus": "SUSPECTED",
      "confidence": 0,
      "clinicalStatus": "RESOLVED",
      "approach": "DictionaryLookup",
      "dictCanon": "Personal history of other diseases of the digestive system",
      "conceptID": "Z87.19",
      "belongsTo": null,
    }

3.6. Diagnosis Status

3.6.1. Description

The annotator recognizes the status of diagnoses. Different status includes, for example, "suspected" or "history of".

3.6.2. Input

Above this annotator, the following annotator must be included in the pipeline:

• Diagnoses
  

3.6.3. Output

This annotator sets the features belongsTo, verificationStatus and clinicalStatus in annotations of type Diagnosis and changes conceptID and uniqueID if the diagnosis does not belong to the patient but e.g. to a family member.

3.6.4. Web Service Example

Text Example 1 (ClinicalStatus): "history of appendicitis"

    {
      "begin": 0,
      "end": 23,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "history of appendicitis",
      "id": 750,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "History of appendicitis",
      "verificationStatus": null,
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": "RESOLVED",
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Personal history of other diseases of the digestive system",
      "conceptID": "Z87.19",
      "belongsTo": null,
      "uniqueID": "ICD10CM_2021:Z87.19"
    }

Text Example 2 (FamilyDiagnosis): "father has diabetes mellitus"

    {
      "begin": 11,
      "end": 28,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "diabetes mellitus",
      "id": 820,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Diabetes mellitus",
      "verificationStatus": null,
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": null,
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Family history of diabetes mellitus",
      "conceptID": "Z83.3",
      "belongsTo": "FAMILY",
      "uniqueID": "ICD10CM_2021:Z83.3"
    }

3.7. Disambiguation

3.7.1. Description

In case of ambiguous annotations this component decides which annotations should be valid in the given context, e.g. within a list of laboratory values the parameter 'Calcium' represents a laboratory parameter and not an ingredient.

3.7.2. Input

This component requires annotations of at least one of the following types:

• Medications
  

• Diagnoses
  

• LabValues

3.7.3. Output

Only the annotation which is evaluated as valid is maintained the other(s) are discarded.

3.7.4. Web Service Example

There is no special web service return for Disambiguation.

3.8. Enumerations

3.8.1. Description

This component detects enumerations. The enumerations are recognized based on atomic text units (e.g. chunks) and conjunctions (e.g. the word "and").

3.8.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• any components which include concept annotators like LabValues, Diagnoses , Medications, Morphology or Topography.

3.8.3. Output

This component sets the following internal type that is not visible in the annotation editor:

Annotation Type*: de.averbis.types.Enumeration

3.8.4. Web Service Example

*The enumeration itself is not returned in the web service. However, the following example shows that both diagnoses are assigned the status "SUSPECTED".

Text Example: "suspicion of bronchitis or asthma bronchiale"

    {
      "begin": 13,
      "end": 23,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "bronchitis",
      "id": 1137,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Bronchitis",
      "verificationStatus": "SUSPECTED",
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": null,
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Bronchitis, not specified as acute or chronic",
      "conceptID": "J40",
      "belongsTo": null,
      "uniqueID": "ICD10CM_2021:J40"
    },
    {
      "begin": 27,
      "end": 44,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "asthma bronchiale",
      "id": 1138,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Bronchial asthma",
      "verificationStatus": "SUSPECTED",
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": null,
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Unspecified asthma, uncomplicated",
      "conceptID": "J45.909",
      "belongsTo": null,
      "uniqueID": "ICD10CM_2021:J45.909"
    }

3.9. GenericTerminologyAnnotator

3.9.1. Description

The generic Terminology Annotator recognizes terms from terminologies created in Health Discovery’s Terminology Editor module.

3.9.2. Input

Above this annotator, the following annotator must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.9.3. Output

The component creates annotations of type:

Annotation Type: de.averbis.extraction.types.Concept

The exact type depends on the terminology files used and the concept types specified in them.

3.9.4. Configuration

The GenericTerminologyAnnotator has various parameters to annotate texts to terms from the terminologies defined and maintained in the terminology modules of Health Discovery. The various parameters are listed in table below.

3.9.4.1. Configuration Example 1: useStemLookup and useSegmentLookup inactived.

Let us first consider the case where the parameters useSegmentLookup and useStemLookup are disabled. In these cases, a mapping still takes place, namely a basic, simple mapping. In this case, all terms from the terminology are mapped as follows:

• Mapping Modus: Simple
• Case Sensitivity: Upper and lower case, some punctuation and the occurrence of stop words (e.g. 'of', 'the', 'a', ',') are ignored.
• Word Order: The word order in text and terminology is not important for a match.

Example: the term "Appendix Inflammation" is mapped to the text snippet "inflammation of the appendix".

3.9.4.2. Configuration Example 2: useStemLookup activated

Now we activate the mode "useStemLookup". This will now apply a stemming to the mapping, which reduces inflected (or sometimes derived) words to their word stems, base or root forms:

• Mapping Modus: Stemming
• Case Sensitivity: Upper and lower case, some punctuation and the occurrence of stop words (e.g. 'of', 'the', 'a', ',') are ignored.
• Word Order: The word order in text and terminology is not important for a match.

Example: the term "Inflamed Appendix" is mapped to the text snipped "inflammation of the appendix".

3.9.4.3. Configuration Example 3: useSegmentLookup actived

The segment lookup mode uses a dictionary-based approach to decompose compound words into their word components. The term "decompounding" is often used for this purpose. It can be helpful in so-called agglutinating languages, which combine many words into new compound words. Conversely, however, there is a risk that only parts of words in texts are mapped to a term, resulting in false positive hits. Therefore, the segment mode should only be used in exceptional cases.

• Mapping Modus: Segmenting (Decompounding)
• Case Sensitivity: Upper and lower case, some punctuation and the occurrence of stop words (e.g. 'of', 'the', 'a', ',') are ignored.
• Word Order: The word order in text and terminology is not important for a match.

3.9.4.4. Activating the "Exact mode" in terminology administration

The Exact Mode is, like the simple mode, automatically activated in each pipeline, so you will not find a parameter for this in the GenericTerminologyAnnotator. The user has special influence on the terms to be mapped in exact mode. This mode is only applied to a specific part of the terminology, namely to exactly those terms for which the user has actively set the mapping mode to "EXACT" in the terminology editor. The "EXACT" mapping mode ensures that the corresponding term is found in exactly the same spelling as the term, i.e. in the same uppercase and lowercase letters, in the same word order and without any pre-processing in the form of e.g. stemming:

• Mapping Modus: Exact
• Case Sensitivity: Upper and lower case is considered, stop words are preserved.
• Word Order: The word order in text and terminology must be the same.

3.9.5. Web Service Example

Text Example: "appendicitis"

{
   "begin": 0,
   "end": 12,
   "type": "de.averbis.types.health.Concept",
   "coveredText": "Appendizitis",
   "id": 303,
   "matchedTerm": "Appendizitis",
   "dictCanon": "Appendizitis",
   "conceptID": "2",
   "source": "test_1.0",
   "uniqueID": "test_1.0:2"
}

3.10. Gleason Score

3.10.1. Description

This component recognizes Gleason score annotations.

3.10.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter
• HealthPreprocessing

3.10.3. Output

Annotation Type: de.averbis.types.health.GleasonScore

3.10.4. Web Service Example

Text Example: "Gleason Pattern 3(60%) + 4(40%) = 7"

    {
      "begin": 0,
      "end": 35,
      "type": "de.averbis.types.health.GleasonScore",
      "coveredText": "Gleason Pattern 3(60%) + 4(40%) = 7",
      "id": 1855,
      "score": "7",
      "primaryGrade": "3",
      "secondaryGrade": "4"
    }

3.11. GvHD

3.11.1. Description

This component recognizes information about the occurrence of a GvHD (Graft-versus-Host-Disease).

3.11.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• Diagnoses

3.11.3. Output

Annotation Type: de.averbis.types.health.GvHD

3.11.4. Web Service Example

Text Example: "Akute Transplantat-gegen-Wirt Erkrankung Stadium 3 der Haut, Schweregrad III"

    {
      "begin": 0,
      "end": 76,
      "type": "de.averbis.types.health.GvHD",
      "coveredText": "Akute Transplantat-gegen-Wirt Erkrankung Stadium 3 der Haut, Schweregrad III",
      "id": 1346,
      "date": null,
      "organ": "SKIN",
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Akute Transplantat-gegen-Wirt Erkrankung Stadium 3 der Haut",
      "verificationStatus": null,
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10GM_2021",
      "clinicalStatus": null,
      "approach": "DictionaryLookup",
      "laterality": null,
      "stage": "3",
      "dictCanon": "Stadium 3 der akuten Haut-Graft-versus-Host-Krankheit",
      "grade": "III",
      "continuanceStatus": "ACUTE",
      "conceptID": "L99.13*",
      "belongsTo": null,
      "uniqueID": "ICD10GM_2021:L99.13*"
    }

3.12. Health Measurements

3.12.1. Description

This component detects measurements in medical texts.

3.12.2. Input

Above this annotator, the following annotator must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

When generating a measurement annotation a NumericValue and a unit is combined. The LaboratoryParameter annotation allows the generation of a measurement even when a unit is missing, e.g. Hb 11.

3.12.3. Output

Annotation Type: de.averbis.types.health.Measurement

3.12.4. Web Service Example

Health Measurements are only returned in the context of a LabValues and Medications.

3.13. Health Preprocessing

3.13.1. Description

This pipeline block is responsible for preprocessing the input documents and preparing the minimal set of required annotations which serve as input for the subsequenet components. Among others, this pipeline block recognizes and annotates words, sentences, abbreviations, temporal expressions and numerical values. Additionally, it filters out the stopwords (i.e, commonly used words which carry no important significance) and improves the sentence segmentation altered by abbreviations.

3.13.2. Input

Above this annotator, one of the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

3.13.3. Output

This component generates annotations which will be processed by the subsequent components, e.g. words, sentences, abbreviations, temporal expressions and numerical values.

3.13.4. Web Service Example

The annotations generated by the preprocessing pipeline block are not returned in the web service.

3.14. HealthPostProcessing

3.14.1. Description

This pipeline block contains annotators that can be used for postprocessing annotations of previous pipeline components. The first element provided in postprocessing is the "Blacklist Removal Annotator", which is described in more detail below.

3.14.2. Input

This pipeline block is based on the fact that the annotators, whose output is changed by a post-processing component, are previously included in the pipeline.

3.14.3. Output

The output of this pipeline block depends on the components which are used as part of the postprocessing.

3.14.4. Web Service Example

The annotations generated by the postprocessing pipeline block are not returned in the web service.

3.14.5. Blacklist Removal Annotator

3.14.5.1. Description

This annotator is a component of the HealthPostProcessing pipeline block. It can be used to remove annotations using a blacklist. The blacklist consists of several blacklist terms that can be set via parameters in the pipeline configuration on the Health Discovery User Interface.

By default, only the following annotation types are removed by the annotator:

• CodingCandidate
• Diagnosis
• Drug
• Ingredient
• LaboratoryParameter
• LaboratoryValue
• Medications

3.14.5.2. Input

This component does not require any specific annotators. It relies on the assumption that the affected annotators (see above) are defined in the typesystem.

3.14.5.3. How to use the Blacklist Removal Annotator

Step 1: Go to "Pipeline Configuration"

Step 2: Stop the pipeline in which you would like to use the Blacklist Annotator and click the button "edit pipeline".

Step 3: Select from the list of available annotators on the right panel the component "HealthPostProcessing" and add the component as last position to your pipeline.

S tep 4: Click on the HealthPostProcessing component in your pipeline to display the containing components.

Step 5: Click on "BlacklistAnnotationRemover" and fill in the text passages you would like to remove from the text analysis output.

Step 6: Save and restart the pipeline.

3.14.5.4. Output

This component only removes annotations, no new annotations are added.

3.14.5.5. Web Service Example

This component removes annotations, thus there is no return in the web service.

3.15. HLA

3.15.1. Description

This component annotates information about HLA (human leukocyte antigen).

3.15.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.15.3. Output

Annotation Type: de.averbis.types.health.HLA

Annotation Type: de.averbis.types.health.HLAValue

3.15.4. Web Service Example

Example of HLA in a medical record (table view)

Example of HLA table converted to text:

HLA-A

Patient

0101,6801

Donor

0101,6802

Output when text send to Web Service:

    {
      "begin": 0,
      "end": 5,
      "type": "de.averbis.types.health.HLA",
      "coveredText": "HLA-A",
      "id": 1272,
      "date": null,
      "negatedBy": null,
      "matchedTerm": "HLA-A",
      "dictCanon": "HLA-A",
      "receiptDate": null,
      "conceptID": "LP18319-1",
      "source": "Averbis-Lab-Terminology_2.0",
      "female": {
        "begin": 19,
        "end": 23,
        "type": "de.averbis.types.health.HLAValue",
        "coveredText": "6801",
        "id": 1274,
        "alleleGroup": "68",
        "noncodingRegionVariant": null,
        "protein": "01",
        "synonymousDNA": null,
        "expressionNote": null
      },
      "samplingDate": null,
      "belongsTo": "RECIPIENT",
      "uniqueID": "Averbis-Lab-Terminology_2.0:LP18319-1",
      "male": {
        "begin": 14,
        "end": 18,
        "type": "de.averbis.types.health.HLAValue",
        "coveredText": "0101",
        "id": 1273,
        "alleleGroup": "01",
        "noncodingRegionVariant": null,
        "protein": "01",
        "synonymousDNA": null,
        "expressionNote": null
      }
    },
    {
      "begin": 0,
      "end": 5,
      "type": "de.averbis.types.health.HLA",
      "coveredText": "HLA-A",
      "id": 1275,
      "date": null,
      "negatedBy": null,
      "matchedTerm": "HLA-A",
      "dictCanon": "HLA-A",
      "receiptDate": null,
      "conceptID": "LP18319-1",
      "source": "Averbis-Lab-Terminology_2.0",
      "female": {
        "begin": 35,
        "end": 39,
        "type": "de.averbis.types.health.HLAValue",
        "coveredText": "6802",
        "id": 1277,
        "alleleGroup": "68",
        "noncodingRegionVariant": null,
        "protein": "02",
        "synonymousDNA": null,
        "expressionNote": null
      },
      "samplingDate": null,
      "belongsTo": "DONOR",
      "uniqueID": "Averbis-Lab-Terminology_2.0:LP18319-1",
      "male": {
        "begin": 30,
        "end": 34,
        "type": "de.averbis.types.health.HLAValue",
        "coveredText": "0101",
        "id": 1276,
        "alleleGroup": "01",
        "noncodingRegionVariant": null,
        "protein": "01",
        "synonymousDNA": null,
        "expressionNote": null
      }

3.16. Irradiation

3.16.1. Description

This component recognizes information about a previous irradiation therapy.

3.16.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• HealthMeasurements

• Medications
  

3.16.3. Output

Annotation Type: de.averbis.types.health.Irradiation

Annotation Type: de.averbis.types.health.IrradiationDose

3.16.4. Web Service Example

Text Example (Irradiation): "Fraktionierte Ganzkörperbestrahlung (TBI) über opponierende Felder mit einer Gesamtdosis von 12 Gy vom 18.11. bis 20.11.2008"

    {
      "begin": 0,
      "end": 41,
      "type": "de.averbis.types.health.Irradiation",
      "coveredText": "Fraktionierte Ganzkörperbestrahlung (TBI)",
      "id": 1854,
      "negatedBy": null,
      "matchedTerm": "Ganzkörperbestrahlung",
      "dictCanon": "Bestrahlung",
      "irradiationDose": {
        "begin": 93,
        "end": 98,
        "type": "de.averbis.types.health.IrradiationDose",
        "coveredText": "12 Gy",
        "id": 1855,
        "dose": {
          "begin": 93,
          "end": 98,
          "type": "de.averbis.types.health.Measurement",
          "coveredText": "12 Gy",
          "id": 1856,
          "unit": "Gy",
          "normalizedUnit": "m²/s²",
          "normalizedValue": 12,
          "value": 12,
          "dimension": "[L]²/[T]²"
        },
        "kind": "FRACTIONAL"
      },
      "conceptID": "10037794",
      "source": "Averbis-Therapy_1.0",
      "uniqueID": "Averbis-Therapy_1.0:10037794",
      "dateInterval": {
        "begin": 99,
        "end": 124,
        "type": "de.averbis.types.health.DateInterval",
        "coveredText": "vom 18.11. bis 20.11.2008",
        "id": 1857,
        "endDate": "2008-11-20",
        "kind": "DATEINTERVAL",
        "value": "[2008-11-18, 2008-11-20]",
        "startDate": "2008-11-18"
      }

3.17. Lab Values

3.17.1. Description

This component detects laboratory values and vital signs, such as blood pressure levels, ECOG (Eastern Cooperative Oncology Group) and NYHA (New York Heart Association) performance status, left ventricular ejection fraction and many more.

3.17.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• Language Detection or LanguageSetter

• HealthPreprocessing

3.17.3. Output

Annotation Type: de.averbis.types.health.LaboratoryValue

Annotation Type: de.averbis.types.health.LaboratoryParameter

Annotation Type: de.averbis.types.health.QualitativeValue

Annotation Type: de.averbis.types.health.BloodPressure

Annotation Type: de.averbis.types.health.ECOG

Annotation Type: de.averbis.types.health.NYHA

Annotation Type: de.averbis.types.health.Organism

                  
                    negatedBy
                  
                

3.17.4. Terminology Binding

3.17.5. Web Service Example

Example 1 (LabValue with interpretation): "Uric acid 9.6 mg/dl (3.5-7.0)"

    {
      "begin": 0,
      "end": 29,
      "type": "de.averbis.types.health.LaboratoryValue",
      "coveredText": "Uric acid 9.6 mg/dl (3.5-7.0)",
      "id": 2247,
      "factAssessment": null,
      "fact": {
        "begin": 10,
        "end": 19,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "9.6 mg/dl",
        "id": 2248,
        "unit": "mg/dL",
        "normalizedUnit": "kg/m³",
        "normalizedValue": 0.096,
        "value": 9.6,
        "dimension": "[M]/[L]³"
      },
      "interpretation": "high",
      "parameter": {
        "begin": 0,
        "end": 9,
        "type": "de.averbis.types.health.LaboratoryParameter",
        "coveredText": "Uric acid",
        "id": 2246,
        "negatedBy": null,
        "matchedTerm": "Uric Acid",
        "dictCanon": "Urate",
        "conceptID": "LP15935-7",
        "source": "Averbis-Lab-Terminology_2.1",
        "uniqueID": "Averbis-Lab-Terminology_2.1:LP15935-7"
      },
      "upperLimit": {
        "begin": 25,
        "end": 28,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "7.0",
        "id": 2250,
        "unit": "mg/dL",
        "normalizedUnit": "kg/m³",
        "normalizedValue": 0.07,
        "value": 7,
        "dimension": "[M]/[L]³"
      },
      "qualitativeValue": null,
      "lowerLimit": {
        "begin": 21,
        "end": 24,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "3.5",
        "id": 2249,
        "unit": "mg/dL",
        "normalizedUnit": "kg/m³",
        "normalizedValue": 0.035,
        "value": 3.5,
        "dimension": "[M]/[L]³"
      },
      "belongsTo": null
    }

Text Example 2 (QualitativeValue): "CMV antibody strong positive"

    {
      "begin": 0,
      "end": 28,
      "type": "de.averbis.types.health.LaboratoryValue",
      "coveredText": "CMV antibody strong positive",
      "id": 838,
      "factAssessment": null,
      "fact": null,
      "interpretation": null,
      "parameter": {
        "begin": 0,
        "end": 12,
        "type": "de.averbis.types.health.LaboratoryParameter",
        "coveredText": "CMV antibody",
        "id": 837,
        "negatedBy": null,
        "matchedTerm": "CMV antibody",
        "dictCanon": "Cytomegalovirus Ab",
        "conceptID": "LP37878-3",
        "source": "Averbis-Lab-Terminology_2.1",
        "uniqueID": "Averbis-Lab-Terminology_2.1:LP37878-3"
      },
      "upperLimit": null,
      "qualitativeValue": {
        "begin": 13,
        "end": 28,
        "type": "de.averbis.types.health.QualitativeValue",
        "coveredText": "strong positive",
        "id": 839,
        "modifier": "STRONG",
        "value": "POSITIVE"
      },
      "lowerLimit": null,
      "belongsTo": null
    }

Text Example 3 (BloodPressure): "BP 129/61 mmHg"

    {
      "begin": 0,
      "end": 14,
      "type": "de.averbis.types.health.BloodPressure",
      "coveredText": "BP 129/61 mmHg",
      "id": 1072,
      "systolic": {
        "begin": 3,
        "end": 6,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "129",
        "id": 1073,
        "unit": "mmHg",
        "normalizedUnit": "kg/(m·s²)",
        "normalizedValue": 17198.538,
        "value": 129,
        "dimension": "[M]/([L]·[T]²)"
      },
      "diastolic": {
        "begin": 7,
        "end": 14,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "61 mmHg",
        "id": 1074,
        "unit": "mmHg",
        "normalizedUnit": "kg/(m·s²)",
        "normalizedValue": 8132.642,
        "value": 61,
        "dimension": "[M]/([L]·[T]²)"
      },
      "interpretation": null
    }

Text Example 4 (ECOG Performance Status): "Patient's performance status is ECOG 2."

    {
      "begin": 32,
      "end": 38,
      "type": "de.averbis.types.health.ECOG",
      "coveredText": "ECOG 2",
      "id": 1008,
      "stage": "2"
    }

Text Example 5 (NYHA Classification): "NYHA Class II"

    {
      "begin": 0,
      "end": 13,
      "type": "de.averbis.types.health.NYHA",
      "coveredText": "NYHA Class II",
      "id": 675,
      "stage": "2"
    }

Text Example 6 (Organism, LabValue): "Klebsiella pneumoniae positiv"

    {
      "begin": 0,
      "end": 29,
      "type": "de.averbis.types.health.LaboratoryValue",
      "coveredText": "Klebsiella pneumoniae positiv",
      "id": 832,
      "factAssessment": null,
      "fact": null,
      "interpretation": null,
      "parameter": {
        "begin": 0,
        "end": 21,
        "type": "de.averbis.types.health.LaboratoryParameter",
        "coveredText": "Klebsiella pneumoniae",
        "id": 833,
        "negatedBy": null,
        "matchedTerm": "Klebsiella pneumoniae",
        "dictCanon": "Klebsiella pneumoniae",
        "conceptID": "56415008",
        "source": "SNOMED-CT-Bacteria_2020",
        "uniqueID": "SNOMED-CT-Bacteria_2020:56415008"
      },
      "upperLimit": null,
      "qualitativeValue": {
        "begin": 22,
        "end": 29,
        "type": "de.averbis.types.health.QualitativeValue",
        "coveredText": "positiv",
        "id": 834,
        "modifier": null,
        "value": "POSITIVE"
      },
      "lowerLimit": null,
      "belongsTo": null
    }
    {
      "begin": 0,
      "end": 21,
      "type": "de.averbis.types.health.Organism",
      "coveredText": "Klebsiella pneumoniae",
      "id": 835,
      "negatedBy": null,
      "matchedTerm": "Klebsiella pneumoniae",
      "dictCanon": "Klebsiella pneumoniae",
      "kind": "Bacterium",
      "conceptID": "56415008",
      "source": "SNOMED-CT-Bacteria_2020",
      "uniqueID": "SNOMED-CT-Bacteria_2020:56415008"
    }

3.18. Language Detection

3.18.1. Description

This component recognizes and sets the text language. It currently supports German and English. In contrast to the LanguageSetter, this component decides individually for each document which language it is and sets the language accordingly.

If no language can be detected the language is set to 'German'.

3.18.2. Input

The component does not expect any annotations.

3.18.3. Output

The component sets the parameter 'documentLanguage' in the type

de.averbis.types.health.DocumentAnnotation

3.18.4. Web Service Example

Text Example: "this is a sample text."

    {
      "begin": 0,
      "end": 22,
      "type": "de.averbis.types.health.DocumentAnnotation",
      "coveredText": "this is a sample text.",
      "id": 678,
      "language": "en",
      "version": null
    }

3.19. LanguageSetter

3.19.1. Description

A language setter sets the text language in a document. It should only be used if the language is the same for all documents that are sent to this pipeline.

3.19.2. Input

The component does not expect any annotations.

3.19.3. Output

The component sets the parameter documentLanguage.

3.19.4. Configuration

3.19.5. Web Service Example

The language is currently not returned in the web service.

3.20. Laterality

3.20.1. Description

This component annotates the laterality or body site of different annotation types, e.g. Diagnosis , Procedure and Ophthalmology.

3.20.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• HealthPreprocessing

• ClinicalSections

3.20.3. Output

This annotator sets the feature 'side' in above mentioned annotation types.

3.20.4. Web Service Example

As a standalone component, this doesn’t return anything in the web service.

3.21. Medications

3.21.1. Description

This component detects medications, which are a combination of the active ingredient or preparation, a strength, a dose frequency, the dose form, the route of administration and date intervals or a single date.

3.21.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• HealthMeasurements or LabValues

For the annotation of measurements either the LabValues block or the HealthMeasurements block should be executed beforehand.

3.21.3. Output

Annotation Type: de.averbis.types.health.Medication

Annotation Type: de.averbis.types.health.Date

Annotation Type: de.averbis.types.health.DateInterval

Annotation Type: de.averbis.types.health.Drug

Annotation Type: de.averbis.types.health.Ingredient

Annotation Type: de.averbis.types.health.strength

Annotation Type: de.averbis.types.health.DoseForm

Annotation Type: de.averbis.types.health.DoseFrequency

negatedBy               

Annotation Type: de.averbis.types.health.TTY

3.21.4. Terminology Binding

3.21.5. Web Service Example

Text Example1: "Medication on discharge: Aspirin 100 mg 1-0-1 TAB from 01/01 to 01/30/2018"

    {
      "begin": 25,
      "end": 49,
      "type": "de.averbis.types.health.Medication",
      "coveredText": "Aspirin 100 mg 1-0-1 TAB",
      "id": 2421,
      "date": {
        "begin": 50,
        "end": 74,
        "type": "de.averbis.types.health.DateInterval",
        "coveredText": "from 01/01 to 01/30/2018",
        "id": 2430,
        "endDate": "2018-01-30",
        "kind": "DATEINTERVAL",
        "value": "[2018-01-01, 2018-01-30]",
        "startDate": "2018-01-01"
      },
      "administrations": [],
      "drugs": [
        {
          "begin": 25,
          "end": 39,
          "type": "de.averbis.types.health.Drug",
          "coveredText": "Aspirin 100 mg",
          "id": 2422,
          "ingredient": {
            "begin": 25,
            "end": 32,
            "type": "de.averbis.types.health.Ingredient",
            "coveredText": "Aspirin",
            "id": 2423,
            "negatedBy": null,
            "matchedTerm": "Aspirin",
            "dictCanon": "Aspirin",
            "conceptID": "1191",
            "source": "RxNorm_2020_08",
            "uniqueID": "RxNorm_2020_08:1191"
          },
          "strength": {
            "begin": 33,
            "end": 39,
            "type": "de.averbis.types.health.Strength",
            "coveredText": "100 mg",
            "id": 2424,
            "negatedBy": null,
            "unit": "mg",
            "matchedTerm": "100 MG",
            "dictCanon": "100 MG",
            "conceptID": "STR4",
            "normalizedUnit": "kg",
            "source": "RxNormStrength_2019071",
            "normalizedValue": 0.0001,
            "value": 100,
            "dimension": "[M]",
            "uniqueID": "RxNormStrength_2019071:STR4"
          }
        }
      ],
      "termTypes": null,
      "doseForm": {
        "begin": 46,
        "end": 49,
        "type": "de.averbis.types.health.DoseForm",
        "coveredText": "TAB",
        "id": 2427,
        "negatedBy": null,
        "matchedTerm": "Tabs",
        "dictCanon": "Oral tablet (qualifier value)",
        "conceptID": "SCT421026006",
        "source": "AverbisDoseForm_1.0",
        "uniqueID": "AverbisDoseForm_1.0:SCT421026006"
      },
      "rateQuantity": "NaN",
      "doseFrequency": {
        "begin": 40,
        "end": 45,
        "type": "de.averbis.types.health.DayTimeDoseFrequency",
        "coveredText": "1-0-1",
        "id": 2428,
        "negatedBy": null,
        "midday": 0,
        "matchedTerm": null,
        "source": null,
        "totalCount": 2,
        "atNight": "NaN",
        "morning": 1,
        "totalDose": {
          "begin": 40,
          "end": 45,
          "type": "de.averbis.types.health.Measurement",
          "coveredText": "1-0-1",
          "id": 2429,
          "unit": "mg",
          "normalizedUnit": null,
          "normalizedValue": "NaN",
          "value": 200,
          "dimension": "[M]"
        },
        "dictCanon": null,
        "conceptID": null,
        "interval": "daytime",
        "evening": 1,
        "uniqueID": null
      },
      "status": "DISCHARGE"
    },
    {
      "begin": 0,
      "end": 74,
      "type": "de.averbis.types.health.ClinicalSection",
      "coveredText": "Medication on discharge: Aspirin 100 mg 1-0-1 TAB from 01/01 to 01/30/2018",
      "id": 2418,
      "label": "DischargeMedication",
      "keyword": {
        "begin": 0,
        "end": 23,
        "type": "de.averbis.types.health.ClinicalSectionKeyword",
        "coveredText": "Medication on discharge",
        "id": 2419,
        "negatedBy": null,
        "matchedTerm": "Medication on discharge",
        "dictCanon": "Medication on discharge",
        "conceptID": "10183-2",
        "source": "clinical_sections_en",
        "uniqueID": "clinical_sections_en:10183-2"
      }
    }

Text Example 2: "Lisinopril 5 MG tablet Take 5 mg by mouth daily."

    {
      "begin": 0,
      "end": 47,
      "type": "de.averbis.types.health.Medication",
      "coveredText": "Lisinopril 5 MG tablet Take 5 mg by mouth daily",
      "id": 1812,
      "date": null,
      "administrations": [
        "by mouth"
      ],
      "drugs": [
        {
          "begin": 0,
          "end": 15,
          "type": "de.averbis.types.health.Drug",
          "coveredText": "Lisinopril 5 MG",
          "id": 1813,
          "ingredient": {
            "begin": 0,
            "end": 10,
            "type": "de.averbis.types.health.Ingredient",
            "coveredText": "Lisinopril",
            "id": 1814,
            "negatedBy": null,
            "matchedTerm": "Lisinopril",
            "dictCanon": "Lisinopril",
            "conceptID": "29046",
            "source": "RxNorm_2020_08",
            "uniqueID": "RxNorm_2020_08:29046"
          },
          "strength": {
            "begin": 11,
            "end": 15,
            "type": "de.averbis.types.health.Strength",
            "coveredText": "5 MG",
            "id": 1815,
            "negatedBy": null,
            "unit": "mg",
            "matchedTerm": "5 MG",
            "dictCanon": "5 MG",
            "conceptID": "STR133",
            "normalizedUnit": "kg",
            "source": "RxNormStrength_2019071",
            "normalizedValue": 0.000005,
            "value": 5,
            "dimension": "[M]",
            "uniqueID": "RxNormStrength_2019071:STR133"
          }
        }
      ],
      "termTypes": null,
      "doseForm": {
        "begin": 16,
        "end": 22,
        "type": "de.averbis.types.health.DoseForm",
        "coveredText": "tablet",
        "id": 1818,
        "negatedBy": null,
        "matchedTerm": "Tablets",
        "dictCanon": "Tablet dose form (qualifier value)",
        "conceptID": "SCT385055001",
        "source": "AverbisDoseForm_1.0",
        "uniqueID": "AverbisDoseForm_1.0:SCT385055001"
      },
      "rateQuantity": "NaN",
      "doseFrequency": {
        "begin": 42,
        "end": 47,
        "type": "de.averbis.types.health.TimeMeasurementDoseFrequency",
        "coveredText": "daily",
        "id": 1819,
        "negatedBy": null,
        "totalDose": {
          "begin": 42,
          "end": 47,
          "type": "de.averbis.types.health.Measurement",
          "coveredText": "daily",
          "id": 1820,
          "unit": "mg",
          "normalizedUnit": null,
          "normalizedValue": "NaN",
          "value": 5,
          "dimension": "[M]"
        },
        "matchedTerm": "Daily",
        "dictCanon": "Daily (qualifier value)",
        "conceptID": "69620002",
        "interval": "1/day",
        "source": "DoseFrequency_1.0",
        "totalCount": 1,
        "uniqueID": "DoseFrequency_1.0:69620002"
      },
      "status": null
    }

3.22. Medication Status

3.22.1. Description

The annotator recognizes the status of medications. Different status includes, for example, "INTENDED" or "FAMILY".

3.22.2. Input

Above this annotator, the following annotator must be included in the pipeline:

• Medications
  

3.22.3. Output

This annotator sets the feature status in annotations of type Medication .

3.22.4. Web Service Example

Text Example: "A very good alternative, if the tumor is ER positive, is treatment with Tamoxifen."

    {
      "begin": 72,
      "end": 81,
      "type": "de.averbis.types.health.Medication",
      "coveredText": "Tamoxifen",
      "id": 1552,
      "date": null,
      "administrations": [],
      "drugs": [
        {
          "begin": 72,
          "end": 81,
          "type": "de.averbis.types.health.Drug",
          "coveredText": "Tamoxifen",
          "id": 1553,
          "ingredient": {
            "begin": 72,
            "end": 81,
            "type": "de.averbis.types.health.Ingredient",
            "coveredText": "Tamoxifen",
            "id": 1554,
            "negatedBy": null,
            "matchedTerm": "Tamoxifen",
            "dictCanon": "Tamoxifen",
            "conceptID": "10324",
            "source": "RxNorm_2020_08",
            "uniqueID": "RxNorm_2020_08:10324"
          },
          "strength": null
        }
      ],
      "termTypes": null,
      "doseForm": null,
      "rateQuantity": "NaN",
      "doseFrequency": null,
      "status": "CONSIDERED"
    }

3.23. Morphology

3.23.1. Description

This component detects morphologys. It is mainly used in pathology reports.

3.23.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.23.3. Output

The component creates annotations of type:

Annotation Type: de.averbis.types.health.Morphology

3.23.4. Terminology Binding

3.23.5. Web Service Example

Text Example: "Adenocarcinoma of the rectum"

    {
      "begin": 0,
      "end": 14,
      "type": "de.averbis.types.health.Morphology",
      "coveredText": "Adenocarcinoma",
      "id": 974,
      "negatedBy": null,
      "matchedTerm": "Adenocarcinoma",
      "dictCanon": "Adenocarcinoma, NOS",
      "confidence": 0,
      "conceptID": "8140/3",
      "source": "ICD-O-Morphology-EN_3.1",
      "uniqueID": "ICD-O-Morphology-EN_3.1:8140/3"
    }

3.24. Negations

3.24.1. Description

This component detects negated expressions. The negations are detected and assigned to concept annotations that are affected by these expressions. The negation detection component is optimized for medical texts.

3.24.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• all components which include concept annotators like LabValues, Diagnoses, Medications, Morphology or Topography .

3.24.3. Output

This component sets the following internal type that is not visible in the annotation editor:

Annotation Type*: de.averbis.types.health.MedicalNegation

If a concept is successfully negated, the feature negatedBy will be set to the corresponding negation term. If the DiagnosisStatus annotator is included behind it, the’verificationStatus' feature is additionally set to NEGATED.

3.24.4. Web Service Example

Text Example: "No Crohn’s disease"

    {
      "begin": 3,
      "end": 18,
      "type": "de.averbis.types.health.Diagnosis",
      "coveredText": "Crohn’s disease",
      "id": 832,
      "negatedBy": "No",
      "side": null,
      "matchedTerm": "Crohn's disease",
      "verificationStatus": "NEGATED",
      "kind": null,
      "confidence": 0,
      "onsetDate": null,
      "source": "ICD10CM_2021",
      "clinicalStatus": null,
      "approach": "DictionaryLookup",
      "laterality": null,
      "dictCanon": "Crohn's disease, unspecified, without complications",
      "conceptID": "K50.90",
      "belongsTo": null,
      "uniqueID": "ICD10CM_2021:K50.90"
    }

3.25. Ophthalmology

3.25.1. Description

This component detects indicators for the left and the right eye, the intraocular pressure, mentions of visual acuity and concepts concerning the field of ophthalmology.

3.25.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• HealthMeasurements

3.25.3. Output

Annotation Type: de.averbis.types.health.Ophthalmology

Annotation Type: de.averbis.types.health.Tensio

Annotation Type: de.averbis.types.health.RelevantVisualAcuity

Best or actual visual acuity, selected from multiple VisualAcuity- or VisualAcuityValues.

Annotation Type: de.averbis.types.health.VisualAcuity

Annotation Type: de.averbis.types.health.VisualAcuityValue

Annotation Type: de.averbis.types.health.Refraction

Annotation Type: de.averbis.types.health. VisualAcuityAdditionalInformation

3.25.4. Web Service Example

Text Example1 (Tensio): "Tensio RA 13 mmHg LA 14 mmHg"

    {
      "begin": 7,
      "end": 28,
      "type": "de.averbis.types.health.Tensio",
      "coveredText": "RA 13 mmHg LA 14 mmHg",
      "id": 1580,
      "rightEye": {
        "begin": 10,
        "end": 17,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "13 mmHg",
        "id": 1582,
        "unit": "mmHg",
        "normalizedUnit": "kg/(m·s²)",
        "normalizedValue": 1733.1860000000001,
        "value": 13,
        "dimension": "[M]/([L]·[T]²)"
      },
      "leftEye": {
        "begin": 21,
        "end": 28,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "14 mmHg",
        "id": 1581,
        "unit": "mmHg",
        "normalizedUnit": "kg/(m·s²)",
        "normalizedValue": 1866.508,
        "value": 14,
        "dimension": "[M]/([L]·[T]²)"
      }

Text Example 2 (Visual Acuity): "Visus RA 0,16 (AR +1,0 -3,25 84) LA sc 1/35 (AR nicht möglich)"

    {
      "begin": 0,
      "end": 62,
      "type": "de.averbis.types.health.VisualAcuity",
      "coveredText": "Visus RA 0,16 (AR +1,0 -3,25 84) LA sc 1/35 (AR nicht möglich)",
      "id": 3043,
      "rightEye": {
        "begin": 9,
        "end": 32,
        "type": "de.averbis.types.health.VisualAcuityValue",
        "coveredText": "0,16 (AR +1,0 -3,25 84)",
        "id": 3046,
        "additionalInformation": null,
        "pinHole": false,
        "fact": "0.16",
        "refraction": {
          "begin": 14,
          "end": 32,
          "type": "de.averbis.types.health.Refraction",
          "coveredText": "(AR +1,0 -3,25 84)",
          "id": 3047,
          "sphere": 1,
          "cylinder": -3.25,
          "axis": 84
        },
        "meter": false,
        "correction": "AR"
      },
      "leftEye": {
        "begin": 36,
        "end": 62,
        "type": "de.averbis.types.health.VisualAcuityValue",
        "coveredText": "sc 1/35 (AR nicht möglich)",
        "id": 3044,
        "additionalInformation": {
          "begin": 44,
          "end": 62,
          "type": "de.averbis.types.health.VisualAcuityAdditionalInformation",
          "coveredText": "(AR nicht möglich)",
          "id": 3045,
          "normalized": "AR_NOT_POSSIBLE"
        },
        "pinHole": false,
        "fact": "1/35",
        "refraction": null,
        "meter": true,
        "correction": "SC"
      }
    }

Text Example 3 (Relevant Visual Acuity): "Visus RA 0,16 (AR +1,0 -3,25 84) LA sc 1/35 (AR nicht möglich)"

    {
      "begin": 0,
      "end": 62,
      "type": "de.averbis.types.health.RelevantVisualAcuity",
      "coveredText": "Visus RA 0,16 (AR +1,0 -3,25 84) LA sc 1/35 (AR nicht möglich)",
      "id": 3048,
      "rightEye": {
        "begin": 9,
        "end": 32,
        "type": "de.averbis.types.health.VisualAcuityValue",
        "coveredText": "0,16 (AR +1,0 -3,25 84)",
        "id": 3046,
        "additionalInformation": null,
        "pinHole": false,
        "fact": "0.16",
        "refraction": {
          "begin": 14,
          "end": 32,
          "type": "de.averbis.types.health.Refraction",
          "coveredText": "(AR +1,0 -3,25 84)",
          "id": 3047,
          "sphere": 1,
          "cylinder": -3.25,
          "axis": 84
        },
        "meter": false,
        "correction": "AR"
      },
      "leftEye": {
        "begin": 36,
        "end": 62,
        "type": "de.averbis.types.health.VisualAcuityValue",
        "coveredText": "sc 1/35 (AR nicht möglich)",
        "id": 3044,
        "additionalInformation": {
          "begin": 44,
          "end": 62,
          "type": "de.averbis.types.health.VisualAcuityAdditionalInformation",
          "coveredText": "(AR nicht möglich)",
          "id": 3045,
          "normalized": "AR_NOT_POSSIBLE"
        },
        "pinHole": false,
        "fact": "1/35",
        "refraction": null,
        "meter": true,
        "correction": "SC"
      }
    }

Text Example 4 (Ophthalmology): "Kataraktoperation"

  {
      "begin": 0,
      "end": 17,
      "type": "de.averbis.types.health.Ophthalmology",
      "coveredText": "Kataraktoperation",
      "id": 624,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Kataraktoperation",
      "dictCanon": "Katarakt-Operation",
      "conceptID": "110473004",
      "source": "Ophthalmologie_1.0",
      "uniqueID": "Ophthalmologie_1.0:110473004"
    },

3.26. Organizations

3.26.1. Description

This component detects types of organizations and gives correspondance information, e.g. if the organization is the sender of a clinical note. Please note: at present, this annotator is used exclusively to identify if the sender of a record is a German hospital and to assign a hospital type (e.g. university hospital, general hospital...) to this sender.

3.26.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection

• HealthPreprocessing

3.26.3. Output

Annotation Type: de.averbis.types.health.Organization

*please note: at present, organizations are extracted only, if detected as "sender".

3.26.4. Terminology Binding

3.26.5. Web Service Example

Text Example (organizations): "Zentrum für Psychiatrie Emmendingen"

    {
      "begin": 0,
      "end": 35,
      "type": "de.averbis.types.health.Organization",
      "coveredText": "Zentrum für Psychiatrie Emmendingen",
      "id": 765,
      "organizationType": "specialist clinic",
      "correspondence": "sender"
    },

3.26.6. Departments

3.26.6.1. Description

This component is part of the Organizations Annotator and annotates medical departments in clinical notes, e.g. Paediatrics, Neurology, Orthodontics...

3.26.6.2. Input

3.26.6.3. Output

Annotation Type: de.averbis.types.health.Department

3.26.6.4. Terminology Binding

3.26.6.5. Web Service Examples

Example Text (departments): Service: "Division of Hematology and Oncology"

    {
      "begin": 0,
      "end": 22,
      "type": "de.averbis.types.health.Department",
      "coveredText": "Division of Hematology",
      "id": 923,
      "negatedBy": null,
      "matchedTerm": "Hematology",
      "dictCanon": "Haematology",
      "conceptID": "394916005",
      "source": "SpecialistDepartment_1.0",
      "departmentType": "sender",
      "uniqueID": "SpecialistDepartment_1.0:394916005"
    },
    {
      "begin": 27,
      "end": 35,
      "type": "de.averbis.types.health.Department",
      "coveredText": "Oncology",
      "id": 924,
      "negatedBy": null,
      "matchedTerm": "Oncology",
      "dictCanon": "Medical oncology",
      "conceptID": "394593009",
      "source": "SpecialistDepartment_1.0",
      "departmentType": "sender",
      "uniqueID": "SpecialistDepartment_1.0:394593009"
    }

3.27. Pathology Documentation

3.27.1. Description

The component aggregates relevant information from pathology reports (e.g. diagnosis, topography, morhology, TNM, grading and others) into one annotation type. Hereby, the PathologyDocumentation Annotator determines a single valid value for each pathology feature per pathology report based on various rule-based and machine-learning based methods. This information can be used, for example, to encode reports in cancer registries.

3.27.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection

• HealthPreprocessing

• ClinicalSections

• Laterality
• PatientInformation
• HealthMeasurements
• TNM

• Diagnoses

• Topography

• Morphology
  

• GleasonScore

• Enumerations

• Negations

• TumorStage
• Receptors
• Specimen
  
• DiagnosisStatus
  

• Disambiguation

3.27.3. Output

Annotation Type: de.averbis.types.health.PathologyDocumentation

For the annotation types Diagnoses, Morphology and Topography the following features a referenced in the PathologyDocumentation type.

For the tumor thickness the following features are referenced in the PathologyDocumentation type.

The category has the following features referenced in the PathologyDocumentation type:

The pathologyScores has the following features referenced in the PathologyDocumentation type.

3.27.4. Web Service Example

Text Example (german only): "Klinische Angaben: Mammakarzinom links, cT1a bei 0,5 cm Größe. Tumorklassifikation: TNM (7.Aufl.): pT1b, pN1 (1/1 sn), L0, V0, Pn0 Grading: G2, R-Klassifikation (lokal): R0, ICD-O: 8500/3, ICD-10: C50.9."

    {
      "begin": 0,
      "end": 203,
      "type": "de.averbis.types.health.PathologyDocumentation",
      "coveredText": "Klinische Angaben: Mammakarzinom links, cT1a bei 0,5 cm Größe. Tumorklassifikation: TNM (7.Aufl.): pT1b, pN1 (1/1 sn), L0, V0, Pn0 Grading: G2, R-Klassifikation (lokal): R0, ICD-O: 8500/3, ICD-10: C50.9.",
      "id": 6775,
      "side": "L",
      "grading": "2",
      "morphology": {
        "begin": 181,
        "end": 187,
        "type": "de.averbis.types.health.Morphology",
        "coveredText": "8500/3",
        "id": 6781,
        "negatedBy": null,
        "matchedTerm": "8500/3",
        "dictCanon": "Invasives duktales Karzinom",
        "confidence": 0.999591052532196,
        "conceptID": "8500/3",
        "source": "ICD-O-DE_3.1",
        "uniqueID": "ICD-O-DE_3.1:8500/3"
      },
      "thickness": null,
      "topography": {
        "begin": 197,
        "end": 202,
        "type": "de.averbis.types.health.Topography",
        "coveredText": "C50.9",
        "id": 6779,
        "negatedBy": null,
        "matchedTerm": "C50.9",
        "dictCanon": "Brust",
        "confidence": 0.9736150503158569,
        "conceptID": "C50.9",
        "source": "ICD-O-DE_3.1",
        "uniqueID": "ICD-O-DE_3.1:C50.9"
      },
      "diagnosis": {
        "begin": 0,
        "end": 203,
        "type": "de.averbis.types.health.Diagnosis",
        "coveredText": "Klinische Angaben: Mammakarzinom links, cT1a bei 0,5 cm Größe. Tumorklassifikation: TNM (7.Aufl.): pT1b, pN1 (1/1 sn), L0, V0, Pn0 Grading: G2, R-Klassifikation (lokal): R0, ICD-O: 8500/3, ICD-10: C50.9.",
        "id": 6778,
        "negatedBy": null,
        "side": null,
        "matchedTerm": null,
        "verificationStatus": null,
        "kind": null,
        "confidence": 0.9736150503158569,
        "onsetDate": null,
        "source": "ICD10GM_2021",
        "clinicalStatus": null,
        "approach": null,
        "laterality": null,
        "dictCanon": "Bösartige Neubildung: Brustdrüse, nicht näher bezeichnet",
        "conceptID": "C50.9",
        "belongsTo": null,
        "uniqueID": "ICD10GM_2021:C50.9"
      },
      "lymphnodesTested": 1,
      "resultDate": null,
      "rClass": "R0",
      "sentinelLymphnodesTested": 1,
      "node": "pN1",
      "sentinelLymphnodesAffected": 1,
      "lymphnodesAffected": 1,
      "metastasis": "pMu",
      "tumor": "pT1b",
      "lymphaticInvasion": "L0",
      "vascularInvasion": "V0",
      "location": null,
      "category": {
        "begin": 0,
        "end": 203,
        "type": "de.averbis.types.health.TumorCategory",
        "coveredText": "Klinische Angaben: Mammakarzinom links, cT1a bei 0,5 cm Größe. Tumorklassifikation: TNM (7.Aufl.): pT1b, pN1 (1/1 sn), L0, V0, Pn0 Grading: G2, R-Klassifikation (lokal): R0, ICD-O: 8500/3, ICD-10: C50.9.",
        "id": 6776,
        "confidence": 0.9995457743445415,
        "label": "MAMMA"
      },
      "perineuralInvasion": "Pn0"
    }

3.28. Patient Information

3.28.1. Description

With this component, different information about the patient shall be detected, such as admission and discharge dates, the gender of the patient and the information as to whether the patient is deceased. In addition, if a list of patient names was imported as terminology to Averbis Health Discovery, these patient names can be extracted, too.

3.28.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

The HealthPreprocessing pipeline block provides the prerequisite annotation types to ensure the proper functionality of this annotator.

3.28.3. Annotation of patient names

Patient names can only be extracted from clinical notes, if they exist as an entry in a terminology called "patientnames". Therefore, the following preparations are necessary to annotate patient names.

Step 1: Create a terminology in the "Terminology Administration" with the Terminology-ID "patientnames", Concept-Type “de.averbis.textanalysis.types.health.PatientNameConcept" and language "Miscellaneous". Label and Version can be set freely. See Create your own Terminology for more details on how to create a terminology.

Step 2: Import your list of patient names into the terminology using OBO-Format or enter the patient names manually into the terminology using the "Terminology Editor". In order to distinguish between first names and last names, the terms must follow the following syntax: Firstname[semicolon]Lastname, e.g. John;Doe.

Your OBO-file with patient names may look like:

[Term]

id: 1
name: Sue;Miller

[Term]
id: 2
name: John;Doe

....

Step 3: View the results of your import/editing in the "Terminology Editor" to make sure everything worked out smoothly. The imported terminology/OBO-file should contain the patients' first and last name as preferred term. Synonyms do not need to be added.

Step 4: Switch to the "Terminology Administration" and submit the terminology to the text analytics module.

Step 5: Reuse an existing pipeline where "Patient Information" is included or create a pipeline and include the following annotators:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• PatientInformation

Step 6: (Re)Start the pipeline. After completing steps 1 through 5, the pipeline is now ready to annotate the imported patient names.

3.28.4. Output

Annotation Type: de.averbis.types.health.PatientInformation

PatientName

String

Date

Boolean

String

String

String

Annotation Type: de.averbis.types.health.Hospitalisation

3.28.5. Terminology Binding for patientnames

3.28.6. Web Service Example

Example text (Hopitalisation, PatientInformation): "We're reporting on the patient John Doe. He stayed in our hospital from 1/01/2018 until 2/01/2018."

   {
      "begin": 72,
      "end": 97,
      "type": "de.averbis.types.health.Hospitalisation",
      "coveredText": "1/01/2018 until 2/01/2018",
      "id": 1648,
      "admissionDate": "2018-01-01",
      "dischargeDate": "2018-02-01"
    },
    {
      "begin": 0,
      "end": 98,
      "type": "de.averbis.types.health.PatientInformation",
      "coveredText": "We're reporting on the patient John Doe. He stayed in our hospital from 1/01/2018 until 2/01/2018.",
      "id": 1650,
      "firstName": null,
      "lastName": null,
      "deceased": false,
      "gender": "male",
      "deathDate": null
    }

Example text (death date): "The patient died on 2/01/2018 in the course of a multiorgan failure."

    {
      "begin": 0,
      "end": 68,
      "type": "de.averbis.types.health.PatientInformation",
      "coveredText": "The patient died on 2/01/2018 in the course of a multiorgan failure.",
      "id": 1285,
      "firstName": null,
      "lastName": null,
      "deceased": true,
      "gender": null,
      "deathDate": "2018-02-01"
    }

3.29. PHI

3.29.1. Description

Protected health information (PHI), also referred to as personal health information, generally refers to demographic information, medical histories, test and laboratory results, mental health conditions, insurance information, and other data that a healthcare professional collects to identify an individual and determine appropriate care.

This component identifies protected health information like names, dates, locations, IDs, contact information, professions and others.

3.29.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• ClinicalSections
• Laterality
• PatientInformation

3.29.3. Output

Annotation Type: de.averbis.types.health.Age

Age mentioned in the document.

Annotation Type: de.averbis.types.health.Date

All dates in the document.

Annotation Type: de.averbis.types.health.Name

Annotation Type: de.averbis.types.health.Location

Annotation Type: de.averbis.types.health.Id

Annotation Type: de.averbis.types.health.Contact

Annotation Type: de.averbis.types.health.Profession

The profession of the patient or his relatives.

Annotation Type: de.averbis.types.health.PHIOther

Other protected health informations.

Annotation Type: de.averbis.types.health.DeidentifiedDocument

This type returns the deidentified text. By default it replaces the recognized PHI concepts with "X".

3.29.4. Configuration

The PHI module consists of two compounds which can be configured to influence the output.

3.29.4.1. Configuration of PHIAnnotator

The PHI Annotator is provided with configuration parameters, as shown in the diagram below. Please keep the default values of the configuration parameters and not to make any changes.

3.29.4.2. Configuration of PHIDeidentifier

The PHI Deidentifier compound is provided with a parameter called "deidentificationMethod".

The default value for the deidendifiation method is "crossout". The second method is named "tag", by which identified PHIs are replaced by a tag name.

3.29.5. Web Service Example

Text Example for Deidentification: "Mr. Jim Jack was born on 25/10/1990 in Boston."

Method: crossout

{
    "begin": 0,
    "end": 46,
    "type": "de.averbis.types.health.DeidentifiedDocument",
    "coveredText": "Mr. Jim Jack was born on 25/10/1990 in Boston.",
    "id": 5133,
    "kind": "crossout",
    "deidentifiedText": "Mr. XXX XXXX was born on XXXXXXXXXX in XXXXXX."
}

Method: tag

{
    "begin": 0,
    "end": 46,
    "type": "de.averbis.types.health.DeidentifiedDocument",
    "coveredText": "Mr. Jim Jack was born on 25/10/1990 in Boston.",
    "id": 4933,
    "kind": "tag",
    "deidentifiedText": "Mr. <NAME/> was born on <DATE/> in <LOCATION/>."
}

Text Example for further PHI-Types:

"Universitätsklinik Denzlingen, Abteilung Innere Medizin, Elzstraße 165, 54679 Denzlingen, Telefon: +49 6789 - 1234 00, Telefax: +49 6789 - 1234 01, IBAN DE89 4568 2145 5698 4565 12, http://www.uniklinik-denzlingen.de

An:
Dr. med. Markus Bernoulli
Philipp-Furtwängler-Straße 89
32568 Waldkirch

betrifft Patienten:
Hr. Fieseler, Benjamin
geboren am 5.10.53
Libellenallee 34
65432 Reute

Denzlingen, den 28. Januar 2016

Sehr geehrter Kollege,

Wir bedanken uns für die Überweisung von Herrn Benjamin Fieseler (PatientenID: 123456789) zur Entnahme der Schilddrüse und berichten Ihnen nachfolgend über dessen Aufenthalt in unserem Hause."

{
    "begin": 164,
    "end": 182,
    "type": "de.averbis.types.health.Contact",
    "coveredText": "+49 6789 - 1234 00",
    "id": 61978,
    "kind": "PHONE"
},
{   
    "begin": 211,
    "end": 245,
    "type": "de.averbis.types.health.Contact",
    "coveredText": "http://www.uniklinik-denzlingen.de",
    "id": 62076,
    "kind": "URL"
},
{
    "begin": 192,
    "end": 210,
    "type": "de.averbis.types.health.Contact",
    "coveredText": "+49 6789 - 1234 01",
    "id": 62032,
    "kind": "FAX"
},
{
    "begin": 382,
    "end": 389,
    "type": "de.averbis.types.health.Date",
    "coveredText": "5.10.53",
    "id": 43922
},
{
    "begin": 437,
    "end": 452,
    "type": "de.averbis.types.health.Date",
    "coveredText": "28. Januar 2016",
    "id": 43936
},
{
    "begin": 558,
    "end": 567,
    "type": ""de.averbis.types.health.ID",
    "coveredText": "123456789",
    "id": 44649
    "kind": "PATIENTID"
},
{
    "begin": 0,
    "end": 29,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Universitätsklinik Denzlingen",
    "id": 67425,
    "kind": "HOSPITAL"
},
{
    "begin": 123,
    "end": 136,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Elzstraße 165",
    "id": 69052,
    "kind": "STREET"
},
{
    "begin": 138,
    "end": 143,
    "type": "de.averbis.types.health.Location",
    "coveredText": "54679",
    "id": 70568,
    "kind": "ZIP"
},
{
   "begin": 144,
   "end": 154,
   "type": "de.averbis.types.health.Location",
   "coveredText": "Denzlingen",
   "id": 70772,
   "kind": "CITY" 
},
{
   "begin": 280,
   "end": 309,
   "type": "de.averbis.types.health.Location",
   "coveredText": "Philipp-Furtwängler-Straße 89",
   "id": 69194,
   "kind": "STREET"
},
{
    "begin": 310,
    "end": 315,
    "type": "de.averbis.types.health.Location",
    "coveredText": "32568",
    "id": 70598,
    "kind": "ZIP"
},
{
    "begin": 316,
    "end": 325,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Waldkirch",
    "id": 70790,
    "kind": "CITY"
},
{
    "begin": 390,
    "end": 406,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Libellenallee 34",
    "id": 69280,
    "kind": "STREET"
},
{
    "begin": 407,
    "end": 412,
    "type": "de.averbis.types.health.Location",
    "coveredText": "65432",
    "id": 70612,
    "kind": "ZIP"
},
{
    "begin": 413,
    "end": 418,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Reute",
    "id": 70804,
    "kind": "CITY"
},
{
    "begin": 421,
    "end": 431,
    "type": "de.averbis.types.health.Location",
    "coveredText": "Denzlingen",
    "id": 70818,
    "kind": "CITY"
},
{
    "begin": 263,
    "end": 279,
    "type": "de.averbis.types.health.Name",
    "coveredText": "Markus Bernoulli",
    "id": 65723,
    "kind": "DOCTOR"
},
{
    "begin": 352,
    "end": 370,
    "type": "de.averbis.types.health.Name",
    "coveredText": "Fieseler, Benjamin",
    "id": 65785,
    "kind": "PATIENT"
}

3.30. Physical Therapies

3.30.1. Description

The component annotates physical therapies (e.g. cryotherapy, occupational therapy) from clinical notes.

3.30.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.30.3. Output

Annotation Type: de.averbis.types.health.PhysicalTherapy

String

String

String

                  
                    conceptID
                  
                

String

                  
                    source
                  
                

String

String

String

3.30.4. Terminology Binding

3.30.5. Web Service Example

Text Example: "Ergotherapy terminated at patient's request."

    {
      "begin": 0,
      "end": 11,
      "type": "de.averbis.types.health.PhysicalTherapy",
      "coveredText": "Ergotherapy",
      "id": 949,
      "negatedBy": null,
      "matchedTerm": "ergotherapy",
      "dictCanon": "ergotherapy",
      "conceptID": "PT000003",
      "source": "AverbisTherapies_1.0",
      "uniqueID": "AverbisTherapies_1.0:PT000003",
      "status": "CANCELED"
    },

3.31. Procedures

3.31.1. Description

The component annotates surgical procedures from clinical notes. Optional: As an additional annotation to the procedures component  ProcedureCandidate can be visualized too. This component can be optionally activated which specifically detect procedures candidates to optimize DRG coding.

3.31.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

To get the full functionality, the following annotators should also be included below this annotator in the given order:

• Negations

• Procedures

• Disambiguation
  

3.31.3. Output

Annotation Type: de.averbis.types.health.Procedure

Annotation Type (optional): de.averbis.types.health.ProcedureCandidate

3.31.4. Terminology Binding

3.31.5. Web Service Example

Text example for Procedure: "Hysterectomy was not performed due to hypertension of the patient."

    {
      "begin": 0,
      "end": 12,
      "type": "de.averbis.types.health.Procedure",
      "coveredText": "Hysterectomy",
      "id": 1052,
      "date": null,
      "negatedBy": null,
      "side": null,
      "matchedTerm": "Hysterectomy",
      "dictCanon": "Hysterectomy (procedure)",
      "conceptID": "236886002",
      "source": "SNOMED-CT-Procedures_20180901",
      "uniqueID": "SNOMED-CT-Procedures_20180901:236886002",
      "status": "CANCELED"
    }

Text example for ProcedureCandidate: "Hysterectomy was not performed due to hypertension of the patient."

    {
      "begin": 0,
      "end": 12,
      "type": "de.averbis.types.health.ProcedureCandidate",
      "coveredText": "Hysterectomy",
      "id": 1052,
      "dictCanon": "Hysterectomy (procedureCandidate)",
      "conceptID": "236886002",
      "approach": "DocumentClassification",
      "confidence": 0,
    }

3.32. Receptors

3.32.1. Description

This component detects different receptors important in oncology. Currently the annotation is restricted to the receptors HER2 (human epidermal growth factor receptor 2), Progesterone and Estrogen. Additionally, an interpretation and the percentage will be extracted, if available.

3.32.2. Input

Before this annotator, the following annotator must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• HealthMeasurements

3.32.3. Output

Annotation Type: de.averbis.types.health.HER2

String

Annotation Type: de.averbis.types.health.EstrogenReceptor

String

Annotation Type: de.averbis.types.health.ProgesteroneReceptor

String

3.32.4. Web Service Example

Example Text (Her2): "Her2 positive (45%)"

    {
      "begin": 0,
      "end": 18,
      "type": "de.averbis.types.health.HER2",
      "coveredText": "Her2 positive (45%)",
      "id": 1119,
      "percentage": {
        "begin": 15,
        "end": 18,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "45%",
        "id": 1120,
        "unit": "%",
        "normalizedUnit": "",
        "normalizedValue": 0.45,
        "value": 45,
        "dimension": ""
      },
      "status": "++"
    }

Example Text (Progesterone): "PROGESTERONE RECEPTOR: POSITIVE (10%)"

    {
      "begin": 0,
      "end": 36,
      "type": "de.averbis.types.health.ProgesteroneReceptor",
      "coveredText": "PROGESTERONE RECEPTOR: POSITIVE (10%",
      "id": 1222,
      "percentage": {
        "begin": 33,
        "end": 36,
        "type": "de.averbis.types.health.Measurement",
        "coveredText": "10%",
        "id": 1223,
        "unit": "%",
        "normalizedUnit": "",
        "normalizedValue": 0.1,
        "value": 10,
        "dimension": ""
      },
      "status": "++"
    }

3.33. RutaEngine

3.33.1. Description

The RutaEngine is a generic annotator which interprets and executes a rule-based scripting language for Apache UIMA, called UIMA Ruta. Due to its generic nature, the annotator is able create and modify all available types of annotations.

Detailed documentation on the use of Ruta can be found at the Apache UIMA official manual.

3.33.2. Input

This general RutaEngine annotator does not expect any annotations.

If special characters are to be annotated - before this annotator, the following annotator must be included in the pipeline:

• HealthPreprocessing

In addition, the typesystem "de.averbis.textanalysis.typesystems.AverbisTypeSystem" should be imported as well (see figure below).

3.33.3. Output

The Entity type is described here as a exemplary and recommended placeholder for possible types of annotations that are created by this annotator. Entity is a generic type which semantics are specified by its features label and value.

Annotation Type: de.averbis.extraction.types.Entity

3.33.4. Configuration

3.33.5. Web Service Example

Example Ruta Script:

"pack years|py|pack year" -> Keyword; 
(n:NUM k:Keyword){-> CREATE(Entity, "label" = k.ct, "value" = n.ct)};

Example Text (Ruta Script applied): "40 pack years"

{
    "begin": 0,
    "end": 12,
    "type": "de.averbis.types.health.Entity",
    "coveredText": "40 pack years",
    "id": 626,
    "label": "pack years",
    "value": "40" 
}

3.34. Specimen 

3.34.1. Description

During surgical procedures or biospies, tissue or fluid samples are often taken. In pathological reports, these samples or so-called specimens are often listed and described individually. This annotator extracts specimen information in pathology reports. The specimen annotator is a so-called complex annotator and contains several individual annotators such as Morphology, Topography and Diagnoses.

3.34.2. Input

Before this annotator, the following annotator must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

• ClinicalSections
• Diagnoses
• Topography
• Morphology

3.34.3. Output

Annotation Type: de.averbis.types.health.Specimen

3.34.4. Web Service Example

Example Text: "SKIN, LEFT FOREARM (BIOPSY): BASAL CELL CARCINOMA EXTENDING TO THE EXCISION MARGINS"

    {
      "begin": 0,
      "end": 83,
      "type": "de.averbis.types.health.Specimen",
      "coveredText": "SKIN, LEFT FOREARM (BIOPSY): BASAL CELL CARCINOMA EXTENDING TO THE EXCISION MARGINS",
      "id": 1444,
      "identifier": "SINGLE",
      "morphology": {
        "begin": 29,
        "end": 49,
        "type": "de.averbis.types.health.Morphology",
        "coveredText": "BASAL CELL CARCINOMA",
        "id": 1443,
        "negatedBy": null,
        "matchedTerm": "Basal cell carcinoma",
        "dictCanon": "Basal cell carcinoma, NOS",
        "confidence": 0,
        "conceptID": "8090/3",
        "source": "ICD-O-Morphology-EN_3.1",
        "uniqueID": "ICD-O-Morphology-EN_3.1:8090/3"
      },
      "topography": {
        "begin": 0,
        "end": 18,
        "type": "de.averbis.types.health.Topography",
        "coveredText": "SKIN, LEFT FOREARM",
        "id": 1446,
        "negatedBy": null,
        "matchedTerm": "Skin left forearm",
        "dictCanon": "Skin of upper limb and shoulder",
        "confidence": 0,
        "conceptID": "C44.6",
        "source": "ICD-O-Topography-EN_3.1",
        "uniqueID": "ICD-O-Topography-EN_3.1:C44.6"
      },
      "diagnosis": {
        "begin": 0,
        "end": 83,
        "type": "de.averbis.types.health.Diagnosis",
        "coveredText": "SKIN, LEFT FOREARM (BIOPSY): BASAL CELL CARCINOMA EXTENDING TO THE EXCISION MARGINS",
        "id": 1445,
        "negatedBy": null,
        "side": null,
        "matchedTerm": null,
        "verificationStatus": null,
        "kind": null,
        "confidence": 0,
        "onsetDate": null,
        "source": "ICD10CM_2021",
        "clinicalStatus": null,
        "approach": null,
        "laterality": null,
        "dictCanon": "Basal cell carcinoma of skin of left upper limb, including shoulder",
        "conceptID": "C44.619",
        "belongsTo": null,
        "uniqueID": "ICD10CM_2021:C44.619"
      },
      "descriptions": null,
      "laterality": "LEFT"
    }

3.35. TNM

3.35.1. Description

This component detects and annotates abbreviated notations and free-text remarks of the TNM classification. It is able to identify the tumor (T), node (N), metastasis (M), the grading of tumor.

3.35.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.35.3. Output

The following TNM types exist:

The TNM types "TNMTumor", "TNMNode", "TNMMetastasis" and "TNMGrading" have the following attribute:

The TNM type "TNMAdditional" has the following attributes:

3.35.4. Web Service Example

Text Example: "pTis, N0, Mx, G3, L1, V0, Pn0"

   {
      "begin": 18,
      "end": 20,
      "type": "de.averbis.types.health.TNMAdditional",
      "coveredText": "L1",
      "id": 3995,
      "label": "LymphaticInvasion",
      "value": "L1"
    },
    {
      "begin": 22,
      "end": 24,
      "type": "de.averbis.types.health.TNMAdditional",
      "coveredText": "V0",
      "id": 4003,
      "label": "VascularInvasion",
      "value": "V0"
    },
    {
      "begin": 26,
      "end": 29,
      "type": "de.averbis.types.health.TNMAdditional",
      "coveredText": "Pn0",
      "id": 4011,
      "label": "PerineuralInvasion",
      "value": "Pn0"
    },


    {
      "begin": 14,
      "end": 16,
      "type": "de.averbis.types.health.TNMGrading",
      "coveredText": "G3",
      "id": 1903,
      "value": "G3"
    },
    {
      "begin": 10,
      "end": 12,
      "type": "de.averbis.types.health.TNMMetastasis",
      "coveredText": "Mx",
      "id": 1904,
      "value": "Mx"
    },
    {
      "begin": 6,
      "end": 8,
      "type": "de.averbis.types.health.TNMNode",
      "coveredText": "N0",
      "id": 1905,
      "value": "N0"
    },
    {
      "begin": 0,
      "end": 4,
      "type": "de.averbis.types.health.TNMTumor",
      "coveredText": "pTis",
      "id": 1906,
      "value": "Tis"
    }

3.36. TumorStage

3.36.1. Description

The annotator extracts stage information concerning tumors like 'end-stage' or 'stage II-B'.

3.36.2. Input

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.36.3. Output

Annotation Type: de.averbis.types.health.TumorStage

String

3.36.4. Web Service Example

Example Text: "Mamma Ca stage IIa"

    {
      "begin": 9,
      "end": 18,
      "type": "de.averbis.types.health.TumorStage",
      "coveredText": "stage IIa",
      "id": 931,
      "stage": "2",
      "modifier": "a"
    }

3.37. Topography

3.37.1. Description

This component detects topography. It is mainly used in pathology reports.

3.37.2. Input

Above this annotator, the following annotators must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.37.3. Output

Annotation Type: de.averbis.types.health.Topography

3.37.4. Terminology Binding

3.37.5. Web Service Example

Text Example: "Adenocarcinoma of the Rectum"

    {
      "begin": 22,
      "end": 28,
      "type": "de.averbis.types.health.Topography",
      "coveredText": "Rectum",
      "id": 981,
      "negatedBy": null,
      "matchedTerm": "Rectum",
      "dictCanon": "Rectum, NOS",
      "confidence": 0,
      "conceptID": "C20.9",
      "source": "ICD-O-Topography-EN_3.1",
      "uniqueID": "ICD-O-Topography-EN_3.1:C20.9"
    }

3.38. WordlistAnnotator

3.38.1. Description

The WordlistAnnotator allows users to directly embed simple wordlists into pipelines. It identifies words from the wordlist in texts and creates an annotation of type Entity. Optionally, a 'label' and a 'value' can be specified in columns 2 and 3 of the wordlist to fill the corresponding attributes of type Entity (see example below).

3.38.2. Input

Above this annotator, the following annotator must be included in the pipeline:

• LanguageDetection or LanguageSetter

• HealthPreprocessing

3.38.3. Configuration

String

false

true

boolean

false

true

boolean

false

true

String

false

false

3.38.4. Output

The annotator creates an annotation of type Entity.

Exemplary Annotation Type: de.averbis.extraction.types.Entity

3.38.5. WebService Example

Text Example: "The lip"

{
    "begin": 4,
    "end": 7,
    "type": "de.averbis.types.health.Entity",
    "coveredText": "lip",
    "id": 306,
    "label": "Organ",
    "value": "C00",
}

3.39. AnnotationMapper

3.39.1. Description

The AnnotationMapper is an extension of WordlistAnnotator and allows the user to perform simple annotation mapping based on the predefined configuration parameter “mappingList”. The searched term and its features should be separated by a “delimiter”. Annotations of the type given by the parameter “sourceType” are investigated. If the value of their feature “sourceFeature” is present in the “mappingList”, then a new annotation of the type “targetType” is created and its features specified in “targetFeatures” are filled with values defined in the remaining columns (in the same order).

3.39.2. Input

The component expects the annotations of the types specified by the user in the configuration parameters “sourceType” and optionally “sourceFeature”.

Above this annotator, the following annotator must be included in the pipeline:

• HealthPreprocessing

3.39.3. Configuration

String

false

true

String

false

false

String

false

true

String

false

true

String

true

true

String

false

true

Boolean

false

true

String

false

true

3.39.4. Output

The component creates concepts of the types which have been set in the configuration parameter “targetType”.