Merge pull request #233957 from aahill/custom-ta4h

custom health overview + quickstart

Author: v-shils

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

@@ -0,0 +1,41 @@
+---
+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: 06/29/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 the Language resource you created in the above step. 
+
+2. Under the **Extract information** section of Language Studio, select **Custom Text Analytics for health**.
+
+    <!--:::image type="content" source="../../media/select-custom-TA4H.png" alt-text="A screenshot showing the location of custom TA4H in the Language Studio landing page." lightbox="../../media/select-custom-TA4H.png":::-->
+
+3. Select **Create new project** from the top menu in your projects page. Creating a project lets you label 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. Enter the project information, including a name, description, and the language of the files in your project. If you're using the [example dataset](https://aka.ms/custom-ta4h-quickstart-samples), select **English**. You can't change the name of your project later. Select **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.  After you click **Create new project**, a window will appear to let you connect your storage account. If you've already connected a storage account, you will see the storage accounted connected. If not, choose your storage account from the dropdown that appears and click on **Connect storage account**; this will set the required roles for your storage account. This step will possibly return an error if you are not assigned as **owner** on the storage account.
+
+    >[!NOTE]
+    > * You only need to do this step once for each new 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 showing the storage connection screen." lightbox="../../media/connect-storage.png":::
+
+6. Select the container where you have uploaded your dataset.
+
+7. If you have already labeled data make sure it follows the supported format and 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. Select **Next**. If you are using the dataset from the QuickStart, there is no need to review the formatting of the JSON labels file. 
+
+8. Review the data you entered and select **Create Project**.

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

@@ -0,0 +1,13 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: include
+ms.date: 05/24/2022
+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.

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

@@ -0,0 +1,30 @@
+---
+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: 06/29/2022
+ms.author: aahi
+---
+
+To deploy your model from within the [Language Studio](https://aka.ms/LanguageStudio):
+
+1. Select **Deploying a model** from the left side menu.
+
+2. Click on **Add deployment** to start a new deployment job.
+
+    :::image type="content" source="../../media/deploy-model.png" alt-text="A screenshot showing the deployment button in Language Studio." lightbox="../../media/deploy-model.png":::
+
+3. Select **Create new deployment** to create a new deployment and assign a trained model from the dropdown below. You can also **Overwrite an existing deployment** by selecting this option and select the trained model you want to assign to it from the dropdown below.
+
+    > [!NOTE]
+    > Overwriting an existing deployment doesn't require changes to your [prediction API](https://aka.ms/ct-runtime-swagger) call but the results you get will be based on the newly assigned model.
+    
+   :::image type="content" source="../../media/add-deployment.png" alt-text="A screenshot showing the model deployment options in Language Studio." lightbox="../../media/add-deployment.png":::
+     
+4. Click on **Deploy** to start the deployment job.
+
+5. After deployment is successful, an expiration date will appear next to it. [Deployment expiration](../../../concepts/model-lifecycle.md#expiration-timeline) is when your deployed model will be unavailable to be used for prediction, which typically happens **twelve** months after a training configuration expires.

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

@@ -0,0 +1,27 @@
+---
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: language-service
+ms.topic: include
+ms.date: 06/29/2022
+ms.author: aahi
+ms.custom: language-service-custom-text-analytics-for-health-model-testing
+---
+
+To test your deployed models from within the [Language Studio](https://aka.ms/LanguageStudio):
+1. Select **Testing deployments** from the left side menu.
+
+2. Select the deployment you want to test. You can only test models that are assigned to deployments. 
+
+3. Select the deployment you want to query/test from the dropdown.
+
+4. You can enter the text you want to submit to the request or upload a `.txt` file to use.
+
+5. Click on **Run the test** from the top menu.
+
+6. In the **Result** tab, you can see the extracted entities from your text and their types. You can also view the JSON response under the **JSON** tab. <!--[learn more](../rest-api/get-results.md#response-body) about the structure of the JSON response.-->
+
+    :::image type="content" source="../../media/test-model-results.png" alt-text="A screenshot showing the deployment testing screen in Language Studio." lightbox="../../media/test-model-results.png":::
+

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

@@ -0,0 +1,34 @@
+---
+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: 04/26/2022
+ms.author: aahi
+---
+
+To start training your model from within the [Language Studio](https://aka.ms/LanguageStudio):
+
+1. Select **Training jobs** from the left side menu.
+
+2. Select **Start a training job** from the top menu.
+
+3. Select **Train a new model** and type in the model name in the text box. You can also **overwrite an existing model** by selecting this option and choosing the model you want to overwrite from the dropdown menu. Overwriting a trained model is irreversible, but it won't affect your deployed models until you deploy the new model.
+
+    :::image type="content" source="../../media/train-model.png" alt-text="A screenshot showing the training job creation screen in Language Studio." lightbox="../../media/train-model.png":::
+    
+4. Select data splitting method. You can choose **Automatically splitting the testing set from training data** where the system will split your labeled data between the training and testing sets, according to the specified percentages. Or you can **Use a manual split of training and testing data**, this option is only enabled if you have added documents to your testing set.
+
+<!-- see [data labeling](../../how-to/tag-data.md) and [how to train a model](../../how-to/train-model.md#data-splitting) for information about data splitting. -->
+
+5. Click on the **Train** button.
+
+6. If you click on the Training Job ID from the list, a side pane will appear where you can check the **Training progress**, **Job status**, and other details for this job.
+
+    > [!NOTE]
+    > * Only successfully completed training jobs will generate models.
+    > * Training can take some time between a couple of minutes and several hours based on the size of your labeled data.
+    > * You can only have one training job running at a time. You can't start other training job within the same project until the running job is completed. 

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/quickstarts/blob-storage-upload.md

@@ -0,0 +1,31 @@
+---
+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/05/2022
+ms.author: aahi
+---
+
+After you have created an Azure storage account and connected it to your Language resource, you will need to upload the documents from the sample dataset to the root directory of your container. These documents will later be used to train your model.
+
+
+1. [Download the sample dataset](https://aka.ms/custom-ta4h-quickstart-samples) from GitHub. 
+
+2. Open the .zip file, and extract the folder containing the documents. 
+
+2. In the [Azure portal](https://portal.azure.com), navigate to the storage account you created, and select it.
+
+3. In your storage account, select **Containers** from the left menu, located below **Data storage**. On the screen that appears, select **+ Container**. Give the container the name **example-data** and leave the default **Public access level**.
+
+    :::image type="content" source="../../media/storage-screen.png" alt-text="A screenshot showing the main page for a storage account." lightbox="../../media/storage-screen.png":::
+
+4. After your container has been created, select it. Then click **Upload** button to select the `.txt` and `.json` files you downloaded earlier. 
+
+    :::image type="content" source="../../media/file-upload-screen.png" alt-text="A screenshot showing the button for uploading files to the storage account." lightbox="../../media/file-upload-screen.png":::
+
+
+The provided sample dataset contains 12 clinical notes. Each clinical note includes several medical entities and the treatment location. We will use the prebuilt entities to extract the medical entities and train the custom model to extract the treatment location using the entity's learned and list components.

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

@@ -0,0 +1,83 @@
+---
+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: 01/25/2023
+ms.author: aahi
+---
+
+## Prerequisites
+
+* Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Prerequisites" target="_target">I ran into an issue</a>
+
+## Create a new Azure Language resource and Azure storage account
+
+Before you can use custom Text Analytics for health, you'll need to create an Azure Language resource, which will give you the credentials that you need to create a project and start training a model. You'll also need an Azure storage account, where you can upload your dataset that will be used to build your model.
+
+> [!IMPORTANT]
+> To quickly get started, we recommend creating a new Azure Language resource using the steps provided in this article. Using the steps in this article will let you create the Language resource and storage account at the same time, which is easier than doing it later.
+>
+<!-- If you have a pre-existing resource that you'd like to use, you will need to connect it to storage account. See [guidance to using a pre-existing resource](../../how-to/create-project.md#using-a-pre-existing-language-resource) for information.
+-->
+[!INCLUDE [create a new resource from the Azure portal](../resource-creation-azure-portal.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Create-a-new-azure-language-resource-and-storage-account" target="_target">I ran into an issue</a>
+
+## Upload sample data to blob container
+
+[!INCLUDE [Uploading sample data for custom TA4H](blob-storage-upload.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Upload-sample-data-to-blob-container" target="_target">I ran into an issue</a>
+
+## Create a custom Text Analytics for health project
+
+Once your resource and storage account are configured, create a new custom Text Analytics for health project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.
+
+[!INCLUDE [Create a custom Text Analytics for health project](../language-studio/create-project.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Create-custom-named-entity-recognition-project" target="_target">I ran into an issue</a>
+
+## Train your model
+
+Typically after you create a project, you go ahead and start labeling the documents you have in the container connected to your project. For this quickstart, you have imported a sample tagged dataset and initialized your project with the sample JSON labels file so there is no need to add additional labels.
+
+[!INCLUDE [Train a model using Language Studio](../language-studio/train-model.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Train-model" target="_target">I ran into an issue</a>
+
+## Deploy your model
+
+Generally after training a model you would review its evaluation details and make improvements if necessary. In this quickstart, you will just deploy your model, and make it available for you to try in Language studio, or you can call the [prediction API](https://aka.ms/ct-runtime-swagger).
+
+[!INCLUDE [Deploy a model using Language Studio](../language-studio/deploy-model.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Deploy-model" target="_target">I ran into an issue</a>
+
+
+## Test your model
+
+After your model is deployed, you can start using it to extract entities from your text via [Prediction API](https://aka.ms/ct-runtime-swagger). For this quickstart, you will use the [Language Studio](https://aka.ms/LanguageStudio) to submit the custom Text Analytics for health prediction task and visualize the results. In the sample dataset you downloaded earlier, you can find some test documents that you can use in this step.
+
+[!INCLUDE [Test a model using Language Studio](../language-studio/test-model.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Test-model" target="_target">I ran into an issue</a>
+
+## Clean up resources
+
+[!INCLUDE [Delete project using Language Studio](../language-studio/delete-project.md)]
+
+> [!div class="nextstepaction"]
+> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=Language-studio&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Clean-up-projects" target="_target">I ran into an issue</a>

articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/resource-creation-azure-portal.md

@@ -0,0 +1,41 @@
+---
+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: 06/02/2022
+ms.author: aahi
+---
+
+### Create a new resource from the Azure portal
+
+1. Go to the [Azure portal](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics) to create a new Azure Language resource. 
+
+1. In the window that appears, select **Custom text classification & custom named entity recognition** from the custom features. Click **Continue to create your resource** at the bottom of the screen. 
+
+    :::image type="content" source="../media/select-custom-feature-azure-portal.png" alt-text="A screenshot showing custom text classification & custom named entity recognition in the Azure portal." lightbox="../media/select-custom-feature-azure-portal.png":::
+
+1. Create a Language resource with following details.
+
+    |Name  | Description  |
+    |---------|---------|
+    | Subscription | Your Azure subscription. |
+    | Resource group | A resource group that will contain your resource. You can use an existing one, or create a new one. |
+    |Region | The region for your Language resource. For example, "West US 2". |
+    | Name | A name for your resource. |
+    |Pricing tier     | The pricing tier for your Language resource. You can use the Free (F0) tier to try the service.       |
+
+    > [!NOTE]
+    > If you get a message saying "*your login account is not an owner of the selected storage account's resource group*", your account needs to have an owner role assigned on the resource group before you can create a Language resource. Contact your Azure subscription owner for assistance.
+
+1. In the **Custom text classification & custom named entity recognition** section, select an existing storage account or select **New storage account**. These values are to help you get started, and not necessarily the [storage account values](../../../../storage/common/storage-account-overview.md) you’ll want to use in production environments. To avoid latency during building your project connect to storage accounts in the same region as your Language resource.
+
+    |Storage account value  |Recommended value  |
+    |---------|---------|
+    | Storage account name | Any name |
+    | Storage account type | Standard LRS |
+
+1. Make sure the **Responsible AI Notice** is checked. Select **Review + create** at the bottom of the page, then select **Create**.