Merge pull request #222937 from aahill/ta4h-yehia-pr

Text analytics for health updates

Author: 19BMG00

articles/cognitive-services/language-service/text-analytics-for-health/concepts/assertion-detection.md

@@ -8,25 +8,25 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: conceptual
-ms.date: 11/02/2021
+ms.date: 01/04/2023
 ms.author: jboback
 ms.custom: language-service-health, ignite-fall-2021
 ---
 
 # Assertion detection
 
-The meaning of medical content is highly affected by modifiers, such as negative or conditional assertions which can have critical implications if misrepresented. Text Analytics for health supports three categories of assertion detection for entities in the text: 
+The meaning of medical content is highly affected by modifiers, such as negative or conditional assertions, which can have critical implications if misrepresented. Text Analytics for health supports three categories of assertion detection for entities in the text: 
 
 * Certainty
 * Conditional
 * Association
 
 ## Assertion output
 
-Text Analytics for health returns assertion modifiers, which are informative attributes assigned to medical concepts that provide deeper understanding of the concepts’ context within the text. These modifiers are divided into three categories, each focusing on a different aspect, and containing a set of mutually exclusive values. Only one value per category is assigned to each entity. The most common value for each category is the Default value. The service’s output response contains only assertion modifiers that are different from the default value.
+Text Analytics for health returns assertion modifiers, which are informative attributes assigned to medical concepts that provide a deeper understanding of the concepts’ context within the text. These modifiers are divided into three categories, each focusing on a different aspect and containing a set of mutually exclusive values. Only one value per category is assigned to each entity. The most common value for each category is the Default value. The service’s output response contains only assertion modifiers that are different from the default value. In other words, if no assertion is returned, the implied assertion is the default value.
 
 **CERTAINTY**  – provides information regarding the presence (present vs. absent) of the concept and how certain the text is regarding its presence (definite vs. possible).
-*	**Positive** [Default]: the concept exists or happened.
+* **Positive** [Default]: the concept exists or has happened.
 * **Negative**: the concept does not exist now or never happened.
 * **Positive_Possible**: the concept likely exists but there is some uncertainty.
 * **Negative_Possible**: the concept’s existence is unlikely but there is some uncertainty.

articles/cognitive-services/language-service/text-analytics-for-health/concepts/health-entity-categories.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: conceptual
-ms.date: 11/02/2021
+ms.date: 01/04/2023
 ms.author: jboback
 ms.custom: language-service-health, ignite-fall-2021
 ---
@@ -17,7 +17,7 @@ ms.custom: language-service-health, ignite-fall-2021
 
 Text Analytics for health processes and extracts insights from unstructured medical data. The service detects and surfaces medical concepts, assigns assertions to concepts, infers semantic relations between concepts and links them to common medical ontologies.
 
-Text Analytics for health detects medical concepts in the following categories.
+Text Analytics for health detects medical concepts that fall under the following categories.
 
 ## Anatomy
 
@@ -58,7 +58,7 @@ Text Analytics for health detects medical concepts in the following categories.
 
 ### Entities
 
-**COURSE** - Description of a change in another entity over time, such as condition progression (e.g., improvement, worsening, resolution, remission), a course of treatment or medication (e.g., increase in medication dosage). 
+**COURSE** - Description of a change in another entity over time, such as condition progression (for example: improvement, worsening, resolution, remission), a course of treatment or medication (for example: increase in medication dosage). 
 
 :::image type="content" source="../media/entities/course-entity.png" alt-text="An example of a course entity." lightbox="../media/entities/course-entity.png":::
 
@@ -178,59 +178,7 @@ Text Analytics for health detects medical concepts in the following categories.
 :::image type="content" source="../media/entities/treatment-entities-name.png" alt-text="An example of a treatment name entity." lightbox="../media/entities/treatment-entities-name.png":::
 
 
-## Supported Assertions
-
-Assertion modifiers are divided into three categories, each one focuses on a different aspect.
-Each category contains a set of mutually exclusive values. Only one value per category is assigned to each entity. The most common value for each category is the Default value. The service’s output response contains only assertion modifiers that are different from the default value.
-
-### Certainty  
-
-provides information regarding the presence (present vs. absent) of the concept and how certain the text is regarding its presence (definite vs. possible).
-
-**Positive** (Default): the concept exists or happened.
-
-**Negative**: the concept does not exist now or never happened.
-
-:::image type="content" source="../media/entities/negative-entity.png" alt-text="An example of a negative entity." lightbox="../media/entities/negative-entity.png":::
-
-**Positive_Possible**: the concept likely exists but there is some uncertainty.
-
-:::image type="content" source="../media/entities/positive-possible-entity.png" alt-text="An example of a positive possible entity." lightbox="../media/entities/positive-possible-entity.png" :::
-
-**Negative_Possible**: the concept’s existence is unlikely but there is some uncertainty.
-
-:::image type="content" source="../media/entities/negative-possible-entity.png" alt-text="An example of a negative possible entity." lightbox="../media/entities/negative-possible-entity.png" :::
-
-**Neutral_Possible**: the concept may or may not exist without a tendency to either side.
-
-:::image type="content" source="../media/entities/neutral-possible-entity.png" alt-text="An example of a neutral possible entity." lightbox="../media/entities/neutral-possible-entity.png":::
-
-### Conditionality
-
-provides information regarding whether the existence of a concept depends on certain conditions. 
-
-**None** (Default): the concept is a fact and not hypothetical and does not depend on certain conditions.
-
-**Hypothetical**: the concept may develop or occur in the future.
-
-:::image type="content" source="../media/entities/hypothetical-entity.png" alt-text="An example of a hypothetical entity." lightbox="../media/entities/hypothetical-entity.png":::
-
-**Conditional**: the concept exists or occurs only under certain conditions.
-
-:::image type="content" source="../media/entities/conditional-entity.png" alt-text="An example of a conditional entity." lightbox="../media/entities/conditional-entity.png":::
-
-### Association
-
-describes whether the concept is associated with the subject of the text or someone else.
-
-**Subject** (Default): the concept is associated with the subject of the text, usually the patient.
-
-**Someone_Else**: the concept is associated with someone who is not the subject of the text.
-
-:::image type="content" source="../media/entities/association-entity.png" alt-text="An example of an association entity." lightbox="../media/entities/association-entity.png":::
-
-
 
 ## Next steps
 
-* [NER overview](../../named-entity-recognition/overview.md)
+* [How to call the Text Analytics for health](../how-to/call-api.md)

articles/cognitive-services/language-service/text-analytics-for-health/concepts/relation-extraction.md

@@ -8,19 +8,14 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: how-to
-ms.date: 11/02/2021
+ms.date: 01/04/2023
 ms.author: jboback
 ms.custom: language-service-health, ignite-fall-2021
 ---
 
 # Relation extraction
 
-Relation extraction identifies meaningful connections between concepts mentioned in text. For example, a "time of condition" relation is found by associating a condition name with a time or between an abbreviation and the full description.  
-
-
-## Relation extraction output
-
-Text Analytics for health recognizes relations between different concepts, including relations between attribute and entity (for example, direction of body structure, dosage of medication) and between entities (for example, abbreviation detection).
+Text Analytics for health features relation extraction, which is used to  identify meaningful connections between concepts, or entities, mentioned in the text. For example, a "time of condition" relation is found by associating a condition name with a time. Another example is a "dosage of medication" relation, which is found by relating an extracted medication to its extracted dosage. The following example shows how relations are expressed in the JSON output.
 
 > [!NOTE]
 > * Relations referring to CONDITION may refer to either the DIAGNOSIS entity type or the SYMPTOM_OR_SIGN entity type.
@@ -62,7 +57,7 @@ Relation extraction output contains URI references and assigned roles of the ent
 
 ## Recognized relations
 
-The following relations can be returned by the API. 
+The following list presents all the recognized relations by the Text Analytics for health API. 
 
 **ABBREVIATION**
 
@@ -133,3 +128,7 @@ The following relations can be returned by the API.
 **VALUE_OF_EXAMINATION**
 
 **VARIANT_OF_GENE**
+
+## Next steps
+
+* [How to call the Text Analytics for health](../how-to/call-api.md)

articles/cognitive-services/language-service/text-analytics-for-health/how-to/call-api.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: how-to
-ms.date: 09/05/2022
+ms.date: 01/04/2023
 ms.author: jboback
 ms.custom: language-service-health, ignite-fall-2021
 ---
@@ -17,22 +17,20 @@ ms.custom: language-service-health, ignite-fall-2021
 
 [!INCLUDE [service notice](../includes/service-notice.md)]
 
-Text Analytics for health can be used to extract and label relevant medical information from unstructured texts, such as: doctor's notes, discharge summaries, clinical documents, and electronic health records.  There are two ways to utilize this service: 
+Text Analytics for health can be used to extract and label relevant medical information from unstructured texts such as doctors' notes, discharge summaries, clinical documents, and electronic health records. The service performs [named entity recognition](../concepts/health-entity-categories.md), [relation extraction](../concepts/relation-extraction.md), [entity linking](https://www.nlm.nih.gov/research/umls/sourcereleasedocs/index.html), and [assertion detection](../concepts/assertion-detection.md) to uncover insights from the input text. For information  on the returned confidence scores, see the [transparency note](/legal/cognitive-services/text-analytics/transparency-note#general-guidelines-to-understand-and-improve-performance?context=/azure/cognitive-services/text-analytics/context/context). 
+
+There are two ways to call the service: 
 
-* The web-based API and client libraries (asynchronous)
 * A [Docker container](use-containers.md) (synchronous)
+* Using the web-based API and client libraries (asynchronous) 
 
-## Features
 
-Text Analytics for health performs Named Entity Recognition (NER), relation extraction, entity negation and entity linking on English-language text to uncover insights in unstructured clinical and biomedical text. 
-See the [entity categories](../concepts/health-entity-categories.md) returned by Text Analytics for health for a full list of supported entities. For information on confidence scores, see the [transparency note](/legal/cognitive-services/text-analytics/transparency-note#general-guidelines-to-understand-and-improve-performance?context=/azure/cognitive-services/text-analytics/context/context). 
 
 > [!TIP]
-> If you want to start using this feature, you can follow the [quickstart article](../quickstart.md) to get started. You can also make example requests using [Language Studio](../../language-studio.md) without needing to write code.
+> If you want to test out the feature without writing any, you can follow the [quickstart article](../quickstart.md) to get started. You can also make example requests using [Language Studio](../../language-studio.md) without needing to write code.
 
-## Determine how to process the data (optional)
 
-### Specify the Text Analytics for health model
+## Specify the Text Analytics for health model
 
 By default, Text Analytics for health will use the latest available AI model on your text. You can also configure your API requests to use a specific model version. The model you specify will be used to perform operations provided by the Text Analytics for health.
 
@@ -66,7 +64,7 @@ The Text Analytics for health supports English in addition to multiple languages
 
 ## Submitting data
 
-To send an API request, You will need your Language resource endpoint and key.
+To send an API request, you will need your Language resource endpoint and key.
 
 > [!NOTE]
 > You can find the key and endpoint for your Language resource on the Azure portal. They will be located on the resource's **Key and endpoint** page, under **resource management**. 
@@ -78,12 +76,11 @@ Analysis is performed upon receipt of the request. If you send a request using t
 
 ## Submitting a Fast Healthcare Interoperability Resources (FHIR) request
 
-To receive your result using the **FHIR** structure, you must send the FHIR version in the API request body. You can also send the **document type** as a parameter to the FHIR API request body. If the request does not specify a document type, the value is set to none.
+To receive your result using the **FHIR** structure, you must send the FHIR version in the API request body. 
 
 | Parameter Name  | Type |  Value |
 |--|--|--|
 | fhirVersion |  string  | `4.0.1` |
-| documentType | string | `ClinicalTrial`, `Consult`, `DischargeSummary`,  `HistoryAndPhysical`, `Imaging`, `None`, `Pathology`, `ProcedureNote`, `ProgressNote`|
 
 
 

articles/cognitive-services/language-service/text-analytics-for-health/includes/features.md

@@ -5,41 +5,39 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: language-service
 ms.topic: include
-ms.date: 11/02/2021
+ms.date: 01/04/2023
 ms.author: jboback
 ms.custom: ignite-fall-2021
 ---
 
 # [Named Entity Recognition](#tab/ner)
 
-Named Entity Recognition detects words and phrases mentioned in unstructured text that can be associated with one or more semantic types, such as diagnosis, medication name, symptom/sign, or age.
+Named entity recognition is used to perform a semantic extraction of words and phrases mentioned from unstructured text that are associated with any of the [supported entity types](../concepts/health-entity-categories.md), such as diagnosis, medication name, symptom/sign, or age.
 
 > [!div class="mx-imgBorder"]
 > ![Text Analytics for health NER](../media/call-api/health-named-entity-recognition.png)
 
 # [Relation Extraction](#tab/relation-extraction)
 
-Relation extraction identifies meaningful connections between concepts mentioned in text. For example, a "time of condition" relation is found by associating a condition name with a time or between an abbreviation and the full description.  
+Relation extraction is used to identify meaningful connections between concepts mentioned in text that are associated with any of the [supported relations](../concepts/relation-extraction.md), such as the "time of condition" relation, which connects a condition name with a time. 
 
 > [!div class="mx-imgBorder"]
 > ![Text Analytics for health relation extraction](../media/call-api/health-relation-extraction.png)
 
 
 # [Entity Linking](#tab/entity-linking)
 
-Entity linking disambiguates distinct entities by associating named entities mentioned in text to concepts found in a predefined database of concepts including the Unified Medical Language System (UMLS). Medical concepts are also assigned preferred naming, as an additional form of normalization.
+Entity linking is used to disambiguate the extracted entities by associating them with preferred names and codes from the biomedical vocabularies supported by the [Unified Medical Language System (UMLS) Metathesaurus](https://www.nlm.nih.gov/research/umls/sourcereleasedocs/index.html).
 
 > [!div class="mx-imgBorder"]
 > ![Text Analytics for health entity linking](../media/call-api/health-entity-linking.png)
 
-Text Analytics for health supports linking to the health and biomedical vocabularies found in the Unified Medical Language System ([UMLS](https://www.nlm.nih.gov/research/umls/sourcereleasedocs/index.html)) Metathesaurus Knowledge Source.
 
 # [Assertion Detection](#tab/assertion-detection) 
 
-The meaning of medical content is highly affected by modifiers, such as negative or conditional assertions which can have critical implications if misrepresented. Text Analytics for health supports three categories of assertion detection for entities in the text: 
-
+[Assertion detection](../concepts/assertion-detection.md) is used to preserve the meaning of medical content by   adding contextual modifiers to the extracted entities using these categories: 
 * Certainty
-* Conditional
+* Conditionality
 * Association
 
 > [!div class="mx-imgBorder"]

articles/cognitive-services/language-service/text-analytics-for-health/includes/quickstarts/csharp-sdk.md

@@ -13,7 +13,7 @@ ms.custom: ignite-fall-2021
 
 Use this quickstart to create a Text Analytics for health application with the client library for .NET. In the following example, you will create a C# application that can identify medical [entities](../../concepts/health-entity-categories.md), [relations](../../concepts/relation-extraction.md), and [assertions](../../concepts/assertion-detection.md) that appear in text.
 
-[!INCLUDE [Use Language Studio](../../../includes/use-language-studio.md)]
+
 
 
 ## Prerequisites
@@ -181,6 +181,9 @@ Results of Azure Text Analytics for health async model, version: "2022-03-01"
       Associated Entity Category: Frequency
 ```
 
+> [!TIP]
+> Fast Healthcare Interoperability Resources (FHIR) structuring is available for preview using the Language REST API. The client libraries are not currently supported. [Learn more](../../how-to/call-api.md) on how to use FHIR structuring in your API call.
+
 ## Clean up resources
 
 If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

articles/cognitive-services/language-service/text-analytics-for-health/includes/quickstarts/java-sdk.md

@@ -13,8 +13,6 @@ ms.author: jboback
 
 Use this quickstart to create a Text Analytics for health application with the client library for Java. In the following example, you will create a Java application that can identify medical [entities](../../concepts/health-entity-categories.md), [relations](../../concepts/relation-extraction.md), and [assertions](../../concepts/assertion-detection.md) that appear in text.
 
-[!INCLUDE [Use Language Studio](../../../includes/use-language-studio.md)]
-
 ## Prerequisites
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
@@ -160,6 +158,9 @@ Relation type: FrequencyOfMedication.
 	Entity text: twice daily, category: Frequency, role: Frequency.
 ```
 
+> [!TIP]
+> Fast Healthcare Interoperability Resources (FHIR) structuring is available for preview using the Language REST API. The client libraries are not currently supported. [Learn more](../../how-to/call-api.md) on how to use FHIR structuring in your API call.
+
 ## Clean up resources
 
 If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.