|
| 1 | +# Azure Cognitive Services Health Insights Cancer Profiling client library for Java |
| 2 | + |
| 3 | +[Health Insights](https://review.learn.microsoft.com/azure/azure-health-insights/?branch=release-azure-health-insights) is an Azure Applied AI Service built with the Azure Cognitive Services Framework, that leverages multiple Cognitive Services, Healthcare API services and other Azure resources. |
| 4 | + |
| 5 | +The [Cancer Profiling model][cancer_profiling_docs] receives clinical records of oncology patients and outputs cancer staging, such as clinical stage TNM categories and pathologic stage TNM categories as well as tumor site, histology. |
| 6 | + |
| 7 | + |
| 8 | +## Getting started |
| 9 | + |
| 10 | +### Prerequisites |
| 11 | + |
| 12 | +- A [Java Development Kit (JDK)][jdk_link] with version 8 or above |
| 13 | +- [Azure Subscription][azure_subscription] |
| 14 | +- An existing Cognitive Services Health Insights instance. |
| 15 | + |
| 16 | +For more information about creating the resource or how to get the location and sku information see [here][cognitive_resource_cli]. |
| 17 | + |
| 18 | +### Include the Package |
| 19 | + |
| 20 | +[//]: # ({x-version-update-start;com.azure:azure-health-insights-cancerprofiling;current}) |
| 21 | + |
| 22 | +```xml |
| 23 | +<dependency> |
| 24 | + <groupId>com.azure</groupId> |
| 25 | + <artifactId>azure-health-insights-cancerprofiling</artifactId> |
| 26 | + <version>1.0.0-beta.1</version> |
| 27 | +</dependency> |
| 28 | +``` |
| 29 | + |
| 30 | +[//]: # ({x-version-update-end}) |
| 31 | + |
| 32 | +### Authenticate the client |
| 33 | + |
| 34 | +In order to interact with the Health Insights Cancer Profiling service, you'll need to create an instance of the [`CancerProfilingClient`][cancer_profiling_client_class] class. You will need an **endpoint** and an **API key** to instantiate a client object. |
| 35 | + |
| 36 | +#### Get API Key |
| 37 | + |
| 38 | +You can obtain the endpoint and API key from the resource information in the [Azure Portal][azure_portal]. |
| 39 | + |
| 40 | +Alternatively, you can use the [Azure CLI][azure_cli] snippet below to get the API key from the Health Insights resource. |
| 41 | + |
| 42 | +```bash |
| 43 | +az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name> |
| 44 | +``` |
| 45 | + |
| 46 | +#### Create a CancerProfilingClient with an API Key Credential |
| 47 | + |
| 48 | +Once you have the value for the API key, you can pass it as a string into an instance of **AzureKeyCredential**. Use the key as the credential parameter to authenticate the client: |
| 49 | + |
| 50 | +```Java com.azure.health.insights.cancerprofiling.buildasyncclient |
| 51 | +String endpoint = Configuration.getGlobalConfiguration().get("AZURE_HEALTH_INSIGHTS_ENDPOINT"); |
| 52 | +String apiKey = Configuration.getGlobalConfiguration().get("AZURE_HEALTH_INSIGHTS_API_KEY"); |
| 53 | + |
| 54 | +CancerProfilingAsyncClient asyncClient = new CancerProfilingClientBuilder() |
| 55 | + .endpoint(endpoint) |
| 56 | + .serviceVersion(CancerProfilingServiceVersion.getLatest()) |
| 57 | + .credential(new AzureKeyCredential(apiKey)) |
| 58 | + .buildAsyncClient(); |
| 59 | +``` |
| 60 | + |
| 61 | +## Key concepts |
| 62 | + |
| 63 | +The Cancer Profiling model allows you to infer cancer attributes such as tumor site, histology, clinical stage TNM categories and pathologic stage TNM categories from unstructured clinical documents. |
| 64 | + |
| 65 | +## Examples |
| 66 | + |
| 67 | +Infer key cancer attributes such as tumor site, histology, clinical stage TNM categories and pathologic stage TNM categories from a patient's unstructured clinical documents. |
| 68 | +<!-- |
| 69 | +- [SampleInferCancerProfile.java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/healthinsights/azure-health-insights-cancerprofiling/src/samples/java/com/azure/health/insights/cancerprofiling/SampleInferCancerProfile.java). |
| 70 | +--> |
| 71 | + |
| 72 | +```Java com.azure.health.insights.cancerprofiling.infercancerprofile |
| 73 | +// Construct Patient |
| 74 | +PatientRecord patient1 = new PatientRecord("patient_id"); |
| 75 | +PatientInfo patientInfo = new PatientInfo(); |
| 76 | +patientInfo.setBirthDate(LocalDate.parse("1965-12-26")); |
| 77 | +patientInfo.setSex(PatientInfoSex.FEMALE); |
| 78 | +patient1.setInfo(patientInfo); |
| 79 | +LinkedList<PatientDocument> patientDocuments = new LinkedList<>(); |
| 80 | +patient1.setData(patientDocuments); |
| 81 | + |
| 82 | +// Add imaging document |
| 83 | +final String docContent1 = String.join(System.getProperty("line.separator"), |
| 84 | + "15.8.2021", |
| 85 | + "Jane Doe 091175-8967", |
| 86 | + "42 year old female, married with 3 children, works as a nurse. ", |
| 87 | + "Healthy, no medications taken on a regular basis.", |
| 88 | + "PMHx is significant for migraines with aura, uses Mirena for contraception.", |
| 89 | + "Smoking history of 10 pack years (has stopped and relapsed several times).", |
| 90 | + "She is in c/o 2 weeks of productive cough and shortness of breath.", |
| 91 | + "She has a fever of 37.8 and general weakness. ", |
| 92 | + "Denies night sweats and rash. She denies symptoms of rhinosinusitis, asthma, and heartburn. ", |
| 93 | + "On PE:", |
| 94 | + "GENERAL: mild pallor, no cyanosis. Regular breathing rate. ", |
| 95 | + "LUNGS: decreased breath sounds on the base of the right lung. Vesicular breathing.", |
| 96 | + " No crackles, rales, and wheezes. Resonant percussion. ", |
| 97 | + "PLAN: ", |
| 98 | + "Will be referred for a chest x-ray. ", |
| 99 | + "======================================", |
| 100 | + "CXR showed mild nonspecific opacities in right lung base. ", |
| 101 | + "PLAN:", |
| 102 | + "Findings are suggestive of a working diagnosis of pneumonia. The patient is referred to a follow-up CXR in 2 weeks."); |
| 103 | + |
| 104 | +PatientDocument patientDocument1 = new PatientDocument( |
| 105 | + DocumentType.NOTE, |
| 106 | + "doc1", |
| 107 | + new DocumentContent(DocumentContentSourceType.INLINE, docContent1)); |
| 108 | + |
| 109 | +patientDocument1.setClinicalType(ClinicalDocumentType.IMAGING); |
| 110 | +patientDocument1.setLanguage("en"); |
| 111 | +patientDocument1.setCreatedDateTime(OffsetDateTime.parse("2021-08-15T10:15:30+01:00")); |
| 112 | +patient1.getData().add(patientDocument1); |
| 113 | + |
| 114 | +// Add Pathology documents |
| 115 | +String docContent2 = String.join(System.getProperty("line.separator"), |
| 116 | + "Oncology Clinic ", |
| 117 | + "20.10.2021", |
| 118 | + "Jane Doe 091175-8967", |
| 119 | + "42-year-old healthy female who works as a nurse in the ER of this hospital. ", |
| 120 | + "First menstruation at 11 years old. First delivery- 27 years old. She has 3 children.", |
| 121 | + "Didn’t breastfeed. ", |
| 122 | + "Contraception- Mirena.", |
| 123 | + "Smoking- 10 pack years. ", |
| 124 | + "Mother- Belarusian. Father- Georgian. ", |
| 125 | + "About 3 months prior to admission, she stated she had SOB and was febrile. ", |
| 126 | + "She did a CXR as an outpatient which showed a finding in the base of the right lung- possibly an infiltrate.", |
| 127 | + "She was treated with antibiotics with partial response. ", |
| 128 | + "6 weeks later a repeat CXR was performed- a few solid dense findings in the right lung. ", |
| 129 | + "Therefore, she was referred for a PET-CT which demonstrated increased uptake in the right breast, lymph nodes on the right a few areas in the lungs and liver. ", |
| 130 | + "On biopsy from the lesion in the right breast- triple negative adenocarcinoma. Genetic testing has not been done thus far. ", |
| 131 | + "Genetic counseling- the patient denies a family history of breast, ovary, uterus, and prostate cancer. Her mother has chronic lymphocytic leukemia (CLL). ", |
| 132 | + "She is planned to undergo genetic tests because the aggressive course of the disease, and her young age. ", |
| 133 | + "Impression:", |
| 134 | + "Stage 4 triple negative breast adenocarcinoma. ", |
| 135 | + "Could benefit from biological therapy. ", |
| 136 | + "Different treatment options were explained- the patient wants to get a second opinion."); |
| 137 | + |
| 138 | +PatientDocument patientDocument2 = new PatientDocument(DocumentType.NOTE, |
| 139 | + "doc2", |
| 140 | + new DocumentContent(DocumentContentSourceType.INLINE, docContent2)); |
| 141 | +patientDocument2.setClinicalType(ClinicalDocumentType.PATHOLOGY); |
| 142 | +patientDocument2.setLanguage("en"); |
| 143 | +patientDocument2.setCreatedDateTime(OffsetDateTime.parse("2021-10-20T22:00:00.00Z")); |
| 144 | +patient1.getData().add(patientDocument2); |
| 145 | + |
| 146 | +String docContent3 = String.join(System.getProperty("line.separator"), |
| 147 | + "PATHOLOGY REPORT", |
| 148 | + " Clinical Information", |
| 149 | + "Ultrasound-guided biopsy; A. 18 mm mass; most likely diagnosis based on imaging: IDC", |
| 150 | + " Diagnosis", |
| 151 | + " A. BREAST, LEFT AT 2:00 4 CM FN; ULTRASOUND-GUIDED NEEDLE CORE BIOPSIES:", |
| 152 | + " - Invasive carcinoma of no special type (invasive ductal carcinoma), grade 1", |
| 153 | + " Nottingham histologic grade: 1/3 (tubules 2; nuclear grade 2; mitotic rate 1; total score; 5/9)", |
| 154 | + " Fragments involved by invasive carcinoma: 2", |
| 155 | + " Largest measurement of invasive carcinoma on a single fragment: 7 mm", |
| 156 | + " Ductal carcinoma in situ (DCIS): Present", |
| 157 | + " Architectural pattern: Cribriform", |
| 158 | + " Nuclear grade: 2-", |
| 159 | + " -intermediate", |
| 160 | + " Necrosis: Not identified", |
| 161 | + " Fragments involved by DCIS: 1", |
| 162 | + " Largest measurement of DCIS on a single fragment: Span 2 mm", |
| 163 | + " Microcalcifications: Present in benign breast tissue and invasive carcinoma", |
| 164 | + " Blocks with invasive carcinoma: A1", |
| 165 | + " Special studies: Pending"); |
| 166 | + |
| 167 | +PatientDocument patientDocument3 = new PatientDocument(DocumentType.NOTE, |
| 168 | + "doc3", |
| 169 | + new DocumentContent(DocumentContentSourceType.INLINE, docContent3)); |
| 170 | +patientDocument3.setClinicalType(ClinicalDocumentType.PATHOLOGY); |
| 171 | +patientDocument3.setLanguage("en"); |
| 172 | +patientDocument3.setCreatedDateTime(OffsetDateTime.parse("2022-01-01T10:15:30+01:00")); |
| 173 | + |
| 174 | +patient1.getData().add(patientDocument3); |
| 175 | + |
| 176 | +// Set configuration to include evidence for the cancer staging inferences |
| 177 | +OncoPhenotypeModelConfiguration configuration = new OncoPhenotypeModelConfiguration(); |
| 178 | +configuration.setIncludeEvidence(true); |
| 179 | + |
| 180 | +// Construct the request with the patient and configration |
| 181 | +OncoPhenotypeData oncoPhenotypeData = new OncoPhenotypeData(Arrays.asList(patient1)); |
| 182 | +oncoPhenotypeData.setConfiguration(configuration); |
| 183 | + |
| 184 | +PollerFlux<OncoPhenotypeResult, OncoPhenotypeResult> asyncPoller = asyncClient.beginInferCancerProfile(oncoPhenotypeData); |
| 185 | +``` |
| 186 | + |
| 187 | +## Troubleshooting |
| 188 | + |
| 189 | +## Next steps |
| 190 | +<!-- |
| 191 | +This code sample show common scenario operation with the Azure Health Insights Cancer Profiling library. More samples can be found under the [samples](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/healthinsights/azure-health-insights-cancerprofiling/src/samples/java/com/azure/health/insights/) directory. |
| 192 | +--> |
| 193 | + |
| 194 | +## Additional documentation |
| 195 | +For more extensive documentation on Azure Health Insights Cancer Profiling, see the [Cancer Profiling documentation][cancer_profiling_docs] on docs.microsoft.com. |
| 196 | +## Contributing |
| 197 | + |
| 198 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla]. |
| 199 | + |
| 200 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. |
| 201 | + |
| 202 | +This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. |
| 203 | + |
| 204 | +<!-- LINKS --> |
| 205 | +[cla]: https://cla.microsoft.com |
| 206 | +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ |
| 207 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 208 | +[coc_contact]: mailto:opencode@microsoft.com |
| 209 | +[azure_subscription]: https://azure.microsoft.com/free/ |
| 210 | +[cognitive_resource_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli |
| 211 | +[jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable |
| 212 | + |
| 213 | +[azure_cli]: https://docs.microsoft.com/cli/azure |
| 214 | +[azure_portal]: https://portal.azure.com |
| 215 | +[cancer_profiling_docs]: https://review.learn.microsoft.com/azure/cognitive-services/health-decision-support/oncophenotype/overview?branch=main |
| 216 | +<!-- |
| 217 | +[cancer_profiling_client_class]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/healthinsights/azure-health-insights-cancerprofiling/src/main/java/com/azure/health/cancerprofiling/CancerProfilingClient.java |
| 218 | + |
| 219 | +--> |
0 commit comments