Azure Cognitive Services Health Insights Radiology Insights client library for Python - version 1.0.0
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.
Radiology Insights is a model that aims to provide quality checks as feedback on errors and inconsistencies (mismatches) and ensures critical findings are identified and communicated using the full context of the report. Follow-up recommendations and clinical findings with measurements (sizes) documented by the radiologist are also identified.
Getting started
Prequisites
- Python 3.8+ is required to use this package.
- You need an Azure subscription to use this package.
- An existing Cognitive Services Health Insights instance.
For more information about creating the resource or how to get the location and sku information see here.
Installing the module
python -m pip install azure-healthinsights-radiologyinsights
This table shows the relationship between SDK versions and supported API versions of the service:
SDK version | Supported API version of service |
---|---|
1.0.0 | 2024-04-01 |
Authenticate the client
Get the endpoint
You can find the endpoint for your Health Insights service resource using the Azure Portal or Azure CLI
# Get the endpoint for the Health Insights service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"
Create a RadiologyInsightsClient with DefaultAzureCredential
DefaultAzureCredential provides different ways to authenticate with the service. Documentation about this can be found here
import os
from azure.identity import DefaultAzureCredential
from azure.healthinsights.radiologyinsights import RadiologyInsightsClient
credential = DefaultAzureCredential()
ENDPOINT = os.environ["AZURE_HEALTH_INSIGHTS_ENDPOINT"]
radiology_insights_client = RadiologyInsightsClient(endpoint=ENDPOINT, credential=credential)
Long-Running Operations
Long-running operations are operations which consist of an initial request sent to the service to start an operation, followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has succeeded, to get the result.
Methods that support healthcare analysis, custom text analysis, or multiple analyses are modeled as long-running operations.
The client exposes a begin_<method-name>
method that returns a poller object. Callers should wait
for the operation to complete by calling result()
on the poller object returned from the begin_<method-name>
method.
Sample code snippets are provided to illustrate using long-running operations below.
Key concepts
Once you've initialized a 'RadiologyInsightsClient', you can use it to analyse document text by displaying inferences found within the text.
- Age Mismatch
- Laterality Discrepancy
- Sex Mismatch
- Complete Order Discrepancy
- Limited Order Discrepancy
- Finding
- Critical Result
- Follow-up Recommendation
- Communication
- Radiology Procedure
Radiology Insights currently supports one document from one patient. Please take a look here for more detailed information about the inferences this service produces.
Examples
For each inference samples are available that show how to retrieve the information either in a synchronous (block until operation is complete, slower) or in an asynchronous way (non-blocking, faster). For an example how to create a client, a request and get the result see the example in the sample folder.
- Age Mismatch
- Complete Order Discrepancy
- Critical Result
- Finding
- Follow-up Communication
- Follow-up Recommendation
- Laterality Discrepancy
- Limited Order Discrepancy
- Radiology Procedure
- Sex Mismatch
Running the samples
- Open a terminal window and
cd
to the directory that the samples are saved in. - Set the environment variables specified in the sample file you wish to run.
- Run the sample. Example:
python <sample_name>.py
Create a request for the RadiologyInsights service
doc_content1 = """CLINICAL HISTORY:
20-year-old female presenting with abdominal pain. Surgical history significant for appendectomy.
COMPARISON:
Right upper quadrant sonographic performed 1 day prior.
TECHNIQUE:
Transabdominal grayscale pelvic sonography with duplex color Doppler and spectral waveform analysis of the ovaries.
FINDINGS:
The uterus is unremarkable given the transabdominal technique with endometrial echo complex within physiologic normal limits. The ovaries are symmetric in size, measuring 2.5 x 1.2 x 3.0 cm and the left measuring 2.8 x 1.5 x 1.9 cm.\n On duplex imaging, Doppler signal is symmetric.
IMPRESSION:
1. Normal pelvic sonography. Findings of testicular torsion.
A new US pelvis within the next 6 months is recommended.
These results have been discussed with Dr. Jones at 3 PM on November 5 2020."""
# Create ordered procedure
procedure_coding = models.Coding(
system="Http://hl7.org/fhir/ValueSet/cpt-all",
code="USPELVIS",
display="US PELVIS COMPLETE",
)
procedure_code = models.CodeableConcept(coding=[procedure_coding])
ordered_procedure = models.OrderedProcedure(description="US PELVIS COMPLETE", code=procedure_code)
# Create encounter
start = datetime.datetime(2021, 8, 28, 0, 0, 0, 0)
end = datetime.datetime(2021, 8, 28, 0, 0, 0, 0)
encounter = models.PatientEncounter(
id="encounter2",
class_property=models.EncounterClass.IN_PATIENT,
period=models.TimePeriod(start=start, end=end),
)
# Create patient info
birth_date = datetime.date(1959, 11, 11)
patient_info = models.PatientDetails(sex=models.PatientSex.FEMALE, birth_date=birth_date)
# Create author
author = models.DocumentAuthor(id="author2", full_name="authorName2")
create_date_time = datetime.datetime(2024, 2, 19, 0, 0, 0, 0, tzinfo=datetime.timezone.utc)
patient_document1 = models.PatientDocument(
type=models.DocumentType.NOTE,
clinical_type=models.ClinicalDocumentType.RADIOLOGY_REPORT,
id="doc2",
content=models.DocumentContent(source_type=models.DocumentContentSourceType.INLINE, value=doc_content1),
created_at=create_date_time,
specialty_type=models.SpecialtyType.RADIOLOGY,
administrative_metadata=models.DocumentAdministrativeMetadata(
ordered_procedures=[ordered_procedure], encounter_id="encounter2"
),
authors=[author],
language="en",
)
# Construct patient
patient1 = models.PatientRecord(
id="patient_id2",
details=patient_info,
encounters=[encounter],
patient_documents=[patient_document1],
)
# Create a configuration
configuration = models.RadiologyInsightsModelConfiguration(verbose=False, include_evidence=True, locale="en-US")
# Construct the request with the patient and configuration
patient_data = models.RadiologyInsightsJob(job_data=models.RadiologyInsightsData(patients=[patient1], configuration=configuration))
Get Age Mismatch Inference information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.AGE_MISMATCH:
print(f"Age Mismatch Inference found")
Get Complete Order Discrepancy Inference information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.COMPLETE_ORDER_DISCREPANCY:
print(f"Complete Order Discrepancy Inference found")
Get Critical Result Inference information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.CRITICAL_RESULT:
critical_result = ri_inference.result
print(
f"Critical Result Inference found: {critical_result.description}")
Get Finding Inference information
for patient_result in radiology_insights_result.patient_results:
counter = 0
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.FINDING:
counter += 1
print(f"Finding Inference found")
Get Follow-up Communication information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.FOLLOWUP_COMMUNICATION:
print(f"Follow-up Communication Inference found")
Get Follow-up Recommendation information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.FOLLOWUP_RECOMMENDATION:
print(f"Follow-up Recommendation Inference found")
Get Laterality Discrepancy information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.LATERALITY_DISCREPANCY:
print(f"Laterality Discrepancy Inference found")
Get Limited Order Discrepancy information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.LIMITED_ORDER_DISCREPANCY:
print(f"Limited Order Discrepancy Inference found")
Get Radiology Procedure information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.RADIOLOGY_PROCEDURE:
print(f"Radiology Procedure Inference found")
Get Sex Mismatch information
for patient_result in radiology_insights_result.patient_results:
for ri_inference in patient_result.inferences:
if ri_inference.kind == models.RadiologyInsightsInferenceType.SEX_MISMATCH:
print(f"Sex Mismatch Inference found")
For detailed conceptual information of this and other inferences please read more here.
Troubleshooting
General
Health Insights Radiology Insights client library will raise exceptions defined in Azure Core.
Logging
This library uses the standard logging library for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.
Detailed DEBUG
level logging, including request/response bodies and unredacted
headers, can be enabled on the client or per-operation with the logging_enable
keyword argument.
See full SDK logging documentation with examples here.
Next steps
Contributing
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 https://cla.microsoft.com.
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.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Azure SDK for Python