Merge pull request #234295 from aahill/ta4h-rest-api

how-to articles

Author: American-Dipper

articles/cognitive-services/language-service/custom-text-analytics-for-health/how-to/create-project.md

@@ -0,0 +1,118 @@
+---
+title: Using Azure resources in custom Text Analytics for health
+titleSuffix: Azure Cognitive Services
+description: Learn about the steps for using Azure resources with custom text analytics for health.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: how-to
+ms.date: 06/03/2022
+ms.author: aahi
+ms.custom: language-service-custom-ta4h, references_regions, ignite-fall-2021, event-tier1-build-2022
+---
+
+# How to create custom Text Analytics for health project
+
+Use this article to learn how to set up the requirements for starting with custom text analytics for health and create a project.
+
+## Prerequisites
+
+Before you start using custom text analytics for health, you need:
+
+* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services).
+
+## Create a Language resource 
+
+Before you start using custom text analytics for health, you'll need an Azure Language resource. It's recommended to create your Language resource and connect a storage account to it in the Azure portal. Creating a resource in the Azure portal lets you create an Azure storage account at the same time, with all of the required permissions preconfigured. You can also read further in the article to learn how to use a pre-existing resource, and configure it to work with custom named entity recognition.
+
+You also will need an Azure storage account where you will upload your `.txt` documents that will be used to train a model to extract entities.
+
+> [!NOTE]
+>  * You need to have an **owner** role assigned on the resource group to create a Language resource.
+>  * If you will connect a pre-existing storage account, you should have an owner role assigned to it.
+
+## Create Language resource and connect storage account
+
+You can create a resource in the following ways:
+
+* The Azure portal
+* Language Studio
+* PowerShell
+
+> [!Note]
+> You shouldn't move the storage account to a different resource group or subscription once it's linked with the Language resource.
+
+[!INCLUDE [create a new resource from the Azure portal](../../includes/custom/resource-creation-azure-portal.md)]
+
+[!INCLUDE [create a new resource from Language Studio](../../includes/custom/resource-creation-language-studio.md)]
+
+[!INCLUDE [create a new resource with Azure PowerShell](../../includes/custom/resource-creation-powershell.md)]
+
+
+> [!NOTE]
+> * The process of connecting a storage account to your Language resource is irreversible, it cannot be disconnected later.
+> * You can only connect your language resource to one storage account.
+
+## Using a pre-existing Language resource
+
+[!INCLUDE [use an existing resource](../includes/use-pre-existing-resource.md)]
+
+## Create a custom Text Analytics for health project
+
+Once your resource and storage container are configured, create a new custom text analytics for health project. A project is a work area for building your custom AI models based on your data. Your project can only be accessed by you and others who have access to the Azure resource being used. If you have labeled data, you can use it to get started by [importing a project](#import-project).
+
+### [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Language Studio project creation](../includes/language-studio/create-project.md)]
+
+### [REST APIs](#tab/rest-api)
+
+[!INCLUDE [REST APIs project creation](../includes/rest-api/create-project.md)]
+
+---
+
+## Import project
+
+If you have already labeled data, you can use it to get started with the service. Make sure that your labeled data follows the [accepted data formats](../concepts/data-formats.md).
+
+### [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Import project](../includes/language-studio/import-project.md)]
+
+### [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Import project](../includes/rest-api/import-project.md)]
+
+---
+
+## Get project details
+
+### [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Language Studio project details](../../includes/custom/project-details.md)]
+
+### [REST APIs](#tab/rest-api)
+
+[!INCLUDE [REST APIs project details](../includes/rest-api/project-details.md)]
+
+---
+
+## Delete project
+
+### [Language Studio](#tab/language-studio)
+
+[!INCLUDE [Delete project using Language studio](../includes/language-studio/delete-project.md)]
+
+### [REST APIs](#tab/rest-api)
+
+[!INCLUDE [Delete project using the REST API](../includes/rest-api/delete-project.md)]
+
+---
+
+## Next steps
+
+<!--* You should have an idea of the [project schema](design-schema.md) you will use to label your data.-->
+
+* After you define your schema, you can start [labeling your data](label-data.md), which will be used for model training, evaluation, and finally making predictions.

articles/cognitive-services/language-service/custom-text-analytics-for-health/how-to/label-data.md

@@ -0,0 +1,112 @@
+---
+title: How to label your data for custom Text Analytics for health
+titleSuffix: Azure Cognitive Services
+description: Learn how to label your data for use with custom Text Analytics for health.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: how-to
+ms.date: 05/24/2022
+ms.author: aahi
+ms.custom: language-service-custom-ner, ignite-fall-2021, event-tier1-build-2022
+---
+
+# Label your data using the Language Studio
+
+Data labeling is a crucial step in development lifecycle. In this step, you  label your documents with the new entities you defined in your schema to populate their learned components. This data will be used in the next step when training your model so that your model can learn from the labeled data to know which entities to extract. If you already have labeled data, you can directly [import](create-project.md#import-project) it into your project, but you need to make sure that your data follows the [accepted data format](../concepts/data-formats.md). See [create project](create-project.md#import-project) to learn more about importing labeled data into your project. If your data isn't labeled already, you can label it in the [Language Studio](https://aka.ms/languageStudio).
+
+## Prerequisites
+
+Before you can label your data, you need:
+
+* A successfully [created project](create-project.md) with a configured Azure blob storage account
+<!--* Text data that [has been uploaded](design-schema.md#data-preparation) to your storage account.-->
+
+See the [project development lifecycle](../overview.md#project-development-lifecycle) for more information.
+
+## Data labeling guidelines
+
+After preparing your data, designing your schema and creating your project, you will need to label your data. Labeling your data is important so your model knows which words will be associated with the entity types you need to extract. When you label your data in [Language Studio](https://aka.ms/languageStudio) (or import labeled data), these labels are stored in the JSON document in your storage container that you have connected to this project. 
+
+As you label your data, keep in mind:
+
+* You can't add labels for Text Analytics for health entities as they're pretrained prebuilt entities. You can only add labels to new entity categories that you defined during schema definition. 
+
+<!--If you want to improve the recall for a prebuilt entity, you can extend it by adding a list component while you are [defining your schema](design-schema.md).-->
+
+* In general, more labeled data leads to better results, provided the data is labeled accurately.
+
+* The precision, consistency and completeness of your labeled data are key factors to determining model performance. 
+
+    * **Label precisely**: Label each entity to its right type always. Only include what you want extracted, avoid unnecessary data in your labels.
+    * **Label consistently**:  The same entity should have the same label across all the documents.
+    * **Label completely**: Label all the instances of the entity in all your documents. 
+
+   > [!NOTE]
+   > There is no fixed number of labels that can guarantee your model will perform the best. Model performance is dependent on possible ambiguity in your schema, and the quality of your labeled data. Nevertheless, we recommend having around 50 labeled instances per entity type.
+
+## Label your data
+
+Use the following steps to label your data:
+
+1. Go to your project page in [Language Studio](https://aka.ms/languageStudio).
+
+2. From the left side menu, select **Data labeling**. You can find a list of all documents in your storage container.
+
+    <!--:::image type="content" source="../media/tagging-files-view.png" alt-text="A screenshot showing the Language Studio screen for labeling data." lightbox="../media/tagging-files-view.png":::-->
+
+    >[!TIP]
+    > You can use the filters in top menu to view the unlabeled documents so that you can start labeling them.
+    > You can also use the filters to view the documents that are labeled with a specific entity type.
+
+3. Change to a single document view from the left side in the top menu or select a specific document to start labeling. You can find a list of all `.txt` documents available in your project to the left. You can use the **Back** and **Next** button from the bottom of the page to navigate through your documents.
+
+    > [!NOTE]
+    > If you enabled multiple languages for your project, you will find a **Language** dropdown in the top menu, which lets you select the language of each document. Hebrew is not supported with multi-lingual projects.
+
+4. In the right side pane, you can use the **Add entity type** button to add additional entities to your project that you missed during schema definition.
+
+    <!--:::image type="content" source="../media/tag-1.png" alt-text="A screenshot showing complete data labeling." lightbox="../media/tag-1.png":::-->
+
+5. You have two options to label your document:
+    
+    |Option |Description  |
+    |---------|---------|
+    |Label using a brush     | Select the brush icon next to an entity type in the right pane, then highlight the text in the document you want to annotate with this entity type.           |
+    |Label using a menu    | Highlight the word you want to label as an entity, and a menu will appear. Select the entity type you want to assign for this entity.        |
+    
+    The below screenshot shows labeling using a brush.
+    
+    :::image type="content" source="../media/tag-options.png" alt-text="A screenshot showing the labeling options offered in Custom NER." lightbox="../media/tag-options.png":::
+    
+6. In the right side pane under the **Labels** pivot you can find all the entity types in your project and the count of labeled instances per each. The prebuilt entities will be shown for reference but you will not be able to label for these prebuilt entities as they are pretrained.
+
+7. In the bottom section of the right side pane you can add the current document you are viewing to the training set or the testing set. By default all the documents are added to your training set. <!--Learn more about [training and testing sets](train-model.md#data-splitting) and how they are used for model training and evaluation.-->
+
+    > [!TIP]
+    > If you are planning on using **Automatic** data splitting, use the default option of assigning all the documents into your training set.
+
+7. Under the **Distribution** pivot you can view the distribution across training and testing sets. You have two options for viewing:
+   * *Total instances* where you can view count of all labeled instances of a specific entity type.
+   * *Documents with at least one label* where each document is counted if it contains at least one labeled instance of this entity.
+  
+7. When you're labeling, your changes are synced periodically, if they have not been saved yet you will find a warning at the top of your page. If you want to save manually, click on **Save labels** button at the bottom of the page.
+
+## Remove labels
+
+To remove a label
+
+1. Select the entity you want to remove a label from.
+2. Scroll through the menu that appears, and select **Remove label**.
+
+## Delete entities
+
+You cannot delete any of the Text Analytics for health pretrained entities because they have a prebuilt component. You are only permitted to delete newly defined entity categories. To delete an entity, select the delete icon next to the entity you want to remove. Deleting an entity removes all its labeled instances from your dataset. 
+
+## Next steps
+
+[Custom text analytics for health overview](../overview.md)
+
+<!--After you've labeled your data, you can begin [training a model](train-model.md) that will learn based on your data.-->

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/language-studio/delete-project.md

@@ -10,4 +10,7 @@ ms.author: aahi
 ms.custom: language-service-custom-classification, event-tier1-build-2022
 ---
 
-When you don't need your project anymore, you can delete your project using [Language Studio](https://aka.ms/custom-extraction). Select **Custom named entity recognition (NER)** from the top, select the project you want to delete, and then select **Delete** from the top menu.
+When you don't need your project anymore, you can delete your project using [Language Studio](https://aka.ms/custom-extraction). 
+1. Select the Language service feature you're using at the top of the page, s
+1. Select the project you want to delete
+1. Select **Delete** from the top menu.

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/language-studio/import-project.md

@@ -0,0 +1,46 @@
+---
+titleSuffix: Azure Cognitive Services
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.custom: event-tier1-build-2022
+ms.topic: include
+ms.date: 05/06/2022
+ms.author: aahi
+---
+
+1. Sign into the [Language Studio](https://aka.ms/languageStudio). A window will appear to let you select your subscription and Language resource. Select your Language resource. 
+
+2. Under the **Extract information** section of Language Studio, select **Custom named entity recognition**.
+
+    <!--:::image type="content" source="../../media/select-custom-ner.png" alt-text="A screenshot showing the location of the custom NER feature in the Language Studio landing page." lightbox="../../media/select-custom-ner.png":::-->
+        
+
+3. Select **Create new project** from the top menu in your projects page. Creating a project will let you tag data, train, evaluate, improve, and deploy your models. 
+
+    <!--:::image type="content" source="../../media/create-project.png" alt-text="A screenshot of the project creation page." lightbox="../../media/create-project.png":::-->
+
+
+4.  After you select **Create new project**, a screen will appear to let you connect your storage account. If you can’t find your storage account, make sure you created a resource using the recommended steps. If you've already connected a storage account to your Language resource, you will see your storage account connected.
+
+    >[!NOTE]
+    > * You only need to do this step once for each new language resource you use. 
+    > * This process is irreversible, if you connect a storage account to your Language resource you cannot disconnect it later.
+    > * You can only connect your Language resource to one storage account.
+
+    :::image type="content" source="../../media/connect-storage.png" alt-text="A screenshot of the storage connection screen for new projects." lightbox="../../media/connect-storage.png":::
+
+4. Enter the project information, including a name, description, and the language of the files in your project. You won’t be able to change the name of your project later. Click **Next**.
+       
+    >[!TIP]
+    > Your dataset doesn't have to be entirely in the same language. You can have multiple documents, each with different supported languages. If your dataset contains documents of different languages or if you expect text from different languages during runtime, select **enable multi-lingual dataset** option when you enter the basic information for your project. This option can be enabled later from the **Project settings** page.
+
+5. Select the container where you have uploaded your dataset. 
+
+7. Click on **Yes, my files are already labeled and I have formatted JSON labels file** and select the labels file from the drop-down menu below to import your JSON labels file. Make sure it follows the [supported format](../../concepts/data-formats.md).
+
+8.   Click **Next**.
+
+9. Review the data you entered and select **Create Project**.

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/create-project.md

@@ -57,9 +57,9 @@ Use the following JSON in your request. Replace the placeholder values below wit
 |Key  |Placeholder|Value  | Example |
 |---------|---------|---------|--|
 | projectName | `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
-| language | `{LANGUAGE-CODE}` |  A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. See [language support](../../language-support.md) to learn more about supported language codes. |`en-us`|
+| language | `{LANGUAGE-CODE}` |  A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. <!--See [language support](../../language-support.md) to learn more about supported language codes.--> |`en-us`|
 | projectKind | `CustomHealthcare` | Your project kind. | `CustomHealthcare` |
-| multilingual | `true`| A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. See [language support](../../language-support.md) to learn more about multilingual support.  | `true`|
+| multilingual | `true`| A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. <!--See [language support](../../language-support.md) to learn more about multilingual support.-->  | `true`|
 | storageInputContainerName | `{CONTAINER-NAME` | The name of your Azure storage container where you have uploaded your documents.   | `myContainer` |
 
 

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/project-details.md

@@ -53,7 +53,7 @@ Use the following header to authenticate your request.
 | `projectKind` | `CustomHealthcare` | Your project kind. | `CustomHealthcare` |
 | `storageInputContainerName` | `{CONTAINER-NAME}` | The name of your Azure storage container where you have uploaded your documents.   | `myContainer` |
 | `projectName` | `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
-| `multilingual` | `true`| A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. For more information about multilingual support, see [Language support](../../language-support.md). | `true`|
-| `language` | `{LANGUAGE-CODE}` |  A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the [language code](../../language-support.md) of the majority of the documents. |`en`|
+| `multilingual` | `true`| A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. <!--For more information about multilingual support, see [Language support](../../language-support.md).--> | `true`|
+| `language` | `{LANGUAGE-CODE}` |  A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. |`en`|
 
 Once you send your API request, you will receive a `200` response indicating success and JSON response body with your project details.