Package: azure-healthinsights-clinicalmatching
Azure Cognitive Services Health Insights Clinical Matching client library for PythonHealth Insightsis an Azure Applied AI Service built with the Azure Cognitive Services Framework, that leverages multiple Cognitive Services, Healthcare API services and other Azure resources.
TheClinical Matching modelreceives patients data and clinical trials protocols, and provides relevant clinical trials based on eligibility criteria.Source code|Package (PyPI)|API reference documentation|Product documentation|SamplesGetting startedPrerequisitesPython 3.7 or later is required to use this package.You need anAzure subscriptionto use this package.An existing Cognitive Services Health Insights instance.Install the packagepipinstallazure-healthinsights-clinicalmatchingThis table shows the relationship between SDK versions and supported API versions of the service:SDK versionSupported API version of service1.0.0b12023-03-01-previewAuthenticate the clientGet the endpointYou can find the endpoint for your Health Insights service resource using theAzure PortalorAzure CLI# Get the endpoint for the Health Insights service resourceazcognitiveservicesaccountshow--name"resource-name"--resource-group"resource-group-name"--query"properties.endpoint"Get the API KeyYou can get theAPI Keyfrom the Health Insights service resource in the Azure Portal.
Alternatively, you can useAzure CLIsnippet below to get the API key of your resource.azcognitiveservicesaccountkeyslist--resource-group<your-resource-group-name>--name<your-resource-name>Create a ClinicalMatchingClient with an API Key CredentialOnce you have the value for the API key, you can pass it as a string into an instance ofAzureKeyCredential. Use the key as the credential parameter to authenticate the client:importosfromazure.core.credentialsimportAzureKeyCredentialfromazure.healthinsights.clinicalmatchingimportClinicalMatchingClientKEY=os.environ["HEALTHINSIGHTS_KEY"]ENDPOINT=os.environ["HEALTHINSIGHTS_ENDPOINT"]trial_matcher_client=ClinicalMatchingClient(endpoint=ENDPOINT,credential=AzureKeyCredential(KEY))Long-Running OperationsLong-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 abegin_<method-name>method that returns a poller object. Callers should wait
for the operation to complete by callingresult()on the poller object returned from thebegin_<method-name>method.
Sample code snippets are provided to illustrate using long-running operationsbelow.Key conceptsTrial Matcher provides the user of the services two main modes of operation: patients centric and clinical trial centric.On patient centric mode, the Trial Matcher model bases the patient matching on the clinical condition, location, priorities, eligibility criteria, and other criteria that the patient and/or service users may choose to prioritize. The model helps narrow down and prioritize the set of relevant clinical trials to a smaller set of trials to start with, that the specific patient appears to be qualified for.On clinical trial centric, the Trial Matcher is finding a group of patients potentially eligible to a clinical trial. The Trial Matcher narrows down the patients, first filtered on clinical condition and selected clinical observations, and then focuses on those patients who met the baseline criteria, to find the group of patients that appears to be eligible patients to a trial.ExamplesThe following section provides several code snippets covering some of the most common Health Insights - Clinical Matching service tasks, including:Match trialsMatch trialsFinding potential eligible trials for a patient.importosimportdatetimefromazure.core.credentialsimportAzureKeyCredentialfromazure.healthinsights.clinicalmatchingimportClinicalMatchingClient,modelsKEY=os.environ["HEALTHINSIGHTS_KEY"]ENDPOINT=os.environ["HEALTHINSIGHTS_ENDPOINT"]# Create a Trial Matcher client# <client>trial_matcher_client=ClinicalMatchingClient(endpoint=ENDPOINT,credential=AzureKeyCredential(KEY))# </client># Create clinical info list# <clinicalInfo>clinical_info_list=[models.ClinicalCodedElement(system="http://www.nlm.nih.gov/research/umls",code="C0032181",name="Platelet count",value="250000"),models.ClinicalCodedElement(system="http://www.nlm.nih.gov/research/umls",code="C0002965",name="Unstable Angina",value="true"),models.ClinicalCodedElement(system="http://www.nlm.nih.gov/research/umls",code="C1522449",name="Radiotherapy",value="false"),models.ClinicalCodedElement(system="http://www.nlm.nih.gov/research/umls",code="C0242957",name="GeneOrProtein-Expression",value="Negative;EntityType:GENEORPROTEIN-EXPRESSION"),models.ClinicalCodedElement(system="http://www.nlm.nih.gov/research/umls",code="C1300072",name="cancer stage",value="2")]# </clinicalInfo># Construct Patient# <PatientConstructor>patient_info=models.PatientInfo(sex=models.PatientInfoSex.MALE,birth_date=datetime.date(1965,12,26),clinical_info=clinical_info_list)patient1=models.PatientRecord(id="patient_id",info=patient_info)# </PatientConstructor># Create registry filterregistry_filters=models.ClinicalTrialRegistryFilter()# Limit the trial to a specific patient condition ("Non-small cell lung cancer")registry_filters.conditions=["non small cell lung cancer (nsclc)"]# Specify the clinical trial registry source as ClinicalTrials.Govregistry_filters.sources=[models.ClinicalTrialSource.CLINICALTRIALS_GOV]# Limit the clinical trial to a certain location, in this case California, USAregistry_filters.facility_locations=[models.GeographicLocation(country_or_region="United States",city="Gilbert",state="Arizona")]# Limit the trial to a specific recruitment statusregistry_filters.recruitment_statuses=[models.ClinicalTrialRecruitmentStatus.RECRUITING]# Construct ClinicalTrial instance and attach the registry filter to it.clinical_trials=models.ClinicalTrials(registry_filters=[registry_filters])# Create TrialMatcherRequestconfiguration=models.TrialMatcherModelConfiguration(clinical_trials=clinical_trials)trial_matcher_data=models.TrialMatcherData(patients=[patient1],configuration=configuration)poller=trial_matcher_client.begin_match_trials(trial_matcher_data)trial_matcher_result=poller.result()iftrial_matcher_result.status==models.JobStatus.SUCCEEDED:tm_results=trial_matcher_result.resultsforpatient_resultintm_results.patients:print(f"Inferences of Patient{patient_result.id}")fortm_inferencesinpatient_result.inferences:print(f"Trial Id{tm_inferences.id}")print(f"Type:{str(tm_inferences.type)}Value:{tm_inferences.value}")print(f"Description{tm_inferences.description}")else:tm_errors=trial_matcher_result.errorsiftm_errorsisnotNone:forerrorintm_errors:print(f"{error.code}:{error.message}")TroubleshootingGeneralHealth Insights Clinical Matching client library will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged atINFOlevel.DetailedDEBUGlevel logging, including request/response bodies andunredactedheaders, can be enabled on the client or per-operation with thelogging_enablekeyword argument.See full SDK logging documentation with exampleshere.Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level.
The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.Next stepsAdditional documentationFor more extensive documentation on Azure Health Insights Clinical Matching, see theClinical Matching documentationon docs.microsoft.com.ContributingThis 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, visithttps://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 theMicrosoft Open Source Code of Conduct. For more information,
see the Code of Conduct FAQ or contactopencode@microsoft.comwith any
additional questions or comments.