[Text Analytics] Expose healthcare relationships (#14038)

The service discovers relationships between healthcare entities and returns them as a list. This PR exposes this list after dereferencing the JSON pointers for healthcare entities.
Fixes #14035

sdk/textanalytics/ai-text-analytics/CHANGELOG.md

@@ -5,6 +5,7 @@
 - We are now targeting the service's v3.1-preview.4 API as the default instead of v3.1-preview.3.
 - [Breaking] Aspects in opinions mining are now called targets and each individual opinion is now called an assessment. The new naming simplifies the naming of different parts of the response.
 - `beginAnalyzeBatchActions` can now process recognize linked entities actions.
+- `beginAnalyzeHealthcareEntities` returns `entityRelations` per document, a list of relations between healthcare entities.
 - `beginAnalyzeHealthcareEntities` entities now include `assertions` instead of `isNegated` which gives more context about the respective entity.
 
 ## 5.1.0-beta.4 (2021-02-10)

sdk/textanalytics/ai-text-analytics/review/ai-text-analytics.api.md

@@ -55,6 +55,7 @@ export interface AnalyzeHealthcareEntitiesResultArray extends Array<AnalyzeHealt
 // @public
 export interface AnalyzeHealthcareEntitiesSuccessResult extends TextAnalyticsSuccessResult {
     entities: HealthcareEntity[];
+    entityRelations: HealthcareEntityRelation[];
 }
 
 // @public
@@ -230,6 +231,24 @@ export interface HealthcareEntity extends Entity {
     relatedEntities: Map<HealthcareEntity, string>;
 }
 
+// @public
+export interface HealthcareEntityRelation {
+    relationType: HealthcareEntityRelationType;
+    roles: HealthcareEntityRelationRole[];
+}
+
+// @public
+export interface HealthcareEntityRelationRole {
+    entity: HealthcareEntity;
+    name: HealthcareEntityRelationRoleType;
+}
+
+// @public
+export type HealthcareEntityRelationRoleType = string;
+
+// @public
+export type HealthcareEntityRelationType = string;
+
 // @public
 export type InnerErrorCodeValue = string;
 

sdk/textanalytics/ai-text-analytics/src/analyzeHealthcareEntitiesResult.ts

@@ -9,7 +9,9 @@ import {
   TextDocumentBatchStatistics,
   HealthcareEntity as GeneratedHealthcareEntity,
   TextAnalyticsError,
-  HealthcareAssertion
+  HealthcareAssertion,
+  RelationType,
+  HealthcareRelationEntity
 } from "./generated/models";
 import {
   makeTextAnalyticsErrorResult,
@@ -55,6 +57,39 @@ export interface HealthcareEntity extends Entity {
   relatedEntities: Map<HealthcareEntity, string>;
 }
 
+/**
+ * The type of different roles a healthcare entity can play in a relation.
+ */
+export type HealthcareEntityRelationRoleType = string;
+
+/**
+ * A healthcare entity that plays a specific role in a relation.
+ */
+export interface HealthcareEntityRelationRole {
+  /**
+   * A healthcare entity
+   */
+  entity: HealthcareEntity;
+  /**
+   * The role of the healthcare entity in a particular relation.
+   */
+  name: HealthcareEntityRelationRoleType;
+}
+
+/**
+ * A relationship between two or more healthcare entities.
+ */
+export interface HealthcareEntityRelation {
+  /**
+   * The type of the healthcare relation.
+   */
+  relationType: RelationType;
+  /**
+   * The list of healthcare entities and their roles in the healthcare relation.
+   */
+  roles: HealthcareEntityRelationRole[];
+}
+
 /**
  * The results of a successful healthcare operation for a single document.
  */
@@ -63,6 +98,10 @@ export interface AnalyzeHealthcareEntitiesSuccessResult extends TextAnalyticsSuc
    * Healthcare entities.
    */
   entities: HealthcareEntity[];
+  /**
+   * Relations between healthcare entities.
+   */
+  entityRelations: HealthcareEntityRelation[];
 }
 
 /**
@@ -174,6 +213,23 @@ function makeHealthcareEntitiesGraph(
   }
 }
 
+function makeHealthcareRelations(
+  entities: HealthcareEntity[],
+  relations: HealthcareRelation[]
+): HealthcareEntityRelation[] {
+  return relations.map(
+    (relation: HealthcareRelation): HealthcareEntityRelation => ({
+      relationType: relation.relationType,
+      roles: relation.entities.map(
+        (role: HealthcareRelationEntity): HealthcareEntityRelationRole => ({
+          entity: entities[parseHealthcareEntityIndex(role.ref)],
+          name: role.role
+        })
+      )
+    })
+  );
+}
+
 /**
  * Creates a healthcare entity in the convenience layer from the one sent by the service.
  * @param document - incoming results sent by the service for a particular document
@@ -187,7 +243,8 @@ export function makeHealthcareEntitiesResult(
   makeHealthcareEntitiesGraph(newEntities, relations);
   return {
     ...makeTextAnalyticsSuccessResult(id, warnings, statistics),
-    entities: newEntities
+    entities: newEntities,
+    entityRelations: makeHealthcareRelations(newEntities, relations)
   };
 }
 

sdk/textanalytics/ai-text-analytics/src/index.ts

@@ -84,7 +84,10 @@ export {
   AnalyzeHealthcareEntitiesSuccessResult,
   AnalyzeHealthcareEntitiesErrorResult,
   HealthcareEntity,
-  EntityDataSource
+  EntityDataSource,
+  HealthcareEntityRelation,
+  HealthcareEntityRelationRole,
+  HealthcareEntityRelationRoleType
 } from "./analyzeHealthcareEntitiesResult";
 export {
   PagedAnalyzeBatchActionsResult,
@@ -139,5 +142,6 @@ export {
   PiiCategory,
   Association,
   Certainty,
-  Conditionality
+  Conditionality,
+  RelationType as HealthcareEntityRelationType
 } from "./generated/models";

sdk/textanalytics/ai-text-analytics/test/public/apiKey.spec.ts

@@ -124,6 +124,32 @@ describe("[API Key] TextAnalyticsClient", function() {
           const doc2Entity1Edge1Label = doc2Entity1.relatedEntities.values().next().value;
           assert.equal(doc2Entity1Target1.text, "ibuprofen");
           assert.equal(doc2Entity1Edge1Label, "DosageOfMedication");
+          assert.deepEqual(doc2.entityRelations[0], {
+            relationType: "DosageOfMedication",
+            roles: [
+              {
+                entity: doc2.entities[0],
+                name: "Attribute"
+              },
+              {
+                entity: doc2.entities[1],
+                name: "Entity"
+              }
+            ]
+          });
+          assert.deepEqual(doc2.entityRelations[1], {
+            relationType: "FrequencyOfMedication",
+            roles: [
+              {
+                entity: doc2.entities[1],
+                name: "Entity"
+              },
+              {
+                entity: doc2.entities[2],
+                name: "Attribute"
+              }
+            ]
+          });
 
           const doc2Entity2 = doc2.entities[1];
           assert.equal(doc2Entity2.text, "ibuprofen");