Phenotype Detection Registry System (PheDRS) User Documentation
The Phenotype Detection Registry System (PheDRS) is a tool at UAB used to assist researchers and clinicians identify populations of interest at UAB matching clinical criteria from both structured data (billing codes, medications, labs) and unstructured documents using Natural Language Processing. The user documentation described here is intended for managers and users of the PheDRS system.
Additional documentation for PheDRS is found in the following locations:
1. Project specific information is found in the appropriate git repo wikis and markdown text
2. UAB specific developer documentation is found in the UAB_BioMedInformatics\PHEDRS Box directory
Installation / Setup
Currently this is very site specific and depends on various backend systems, EHR vendors, etc... UAB specific site setup can be found in the UAB_BioMedInformatics\PHEDRS Box directory
PheDRS supports the following user roles:
The manager of a registry. Full read and write access to the registry. Can add new users as registrars or managers to the registry.
A user with read and write access to the registry.
System administrator responsible for maintaining the entire PheDRS system including all registries.
Read only access to the registry.
Former registrars no longer active.
Viewer allowed to view de-identified data (18 HIPAA Safe Harbor items removed) data.
The registry is configured by the registry manager, often in conjunction with the system administrator.
Registry Property Descriptions and Examples
|CV NAME||CV ID||Example of cvterm name for TYPE_ID||Meaning and Use of VALUE field for this type||Example of Value Field|
|UAB ICD-10-CM Codes||9||Panlobular emphysema||If patient has this billing code, assign as candidate to registry||UAB COPD Registry ICD-10-CM diagnosis criteria|
|UAB MS DRG Codes||12||COPD w CC||If patient has this DRG code, then add anchor cvterm property to this code||DRG Codes COPD Anchor Encounter criteria|
|COPD w MCC||If patient has this DRG code, then add patient to the registry as "accepted"||UAB COPD Registry DRG Codes inclusion criteria|
|PHEDRS Data Loading Criteria||23||Default NLP Pipeline Collection||This is the ID# of the default pipeline for displaying documents in this registry. Unenforced Foreign Key to db_id=14||2|
|Encounter Collection||Encounters matching the appended SQL criteria are added to the registry|| AND (SRC_ADMIT_DT_TM >= (SYSDATE-730)) AND FORMATTED_MEDICAL_RECORD_NBR IN (SELECT FORMATTED_UAB_MRN FROM REGISTRY_PATIENT WHERE REGISTRY_ID=2861)
|Encounter Intervention||Encounters matching the appended SQL criteria are added to the registry AND candidate is flagged for review||AND SRC_ADMIT_DT_TM >= (SYSDATE-30) AND ( (reason_for_visit_txt LIKE '%COPD%') OR (UPPER(reason_for_visit_txt) LIKE '%BRONCHITIS%') OR (UPPER(reason_for_visit_txt) LIKE '%BRONCHIECTASIS%') OR (UPPER(reason_for_visit_txt) LIKE '%EMPHYSEMA%') )|
|PHEDRS MetaData CV||24||Patient Review Cutoff Date||Do not retrieve any data (codes, encounters, documents) from source system before this date||1/1/17|
|Registry Application Title||Use this text here for the name of the registry||COPD Registry Control Panel|
|Display Codes Database Identifier||DB_ID permissable to display in "Diagnoses and Drgs" Panel||8|
|PHEDRS Tab CV||25||REGISTRY_INPATIENT_REVIEW||Indicates that this tab should be displayed in this registry. Value indicates display order from LEFT to RIGHT (1 for leftmost tab)||1|
|Optum UAB APR DRG Codes 2017||26|
|UAB WH CLN REF Codeset 69||27|
Developer Guide to PheDRS Data Loading Criteria
Data Loading Vocabulary
- Code - Structured data in the REGISTRY_PATIENT_CODES table including ICD-10-CM codes, DRG codes, MULTUM medication codes, etc...
- NLP - UMLS CUIs stored (currently) in the medics schema
- Encounter - Encounter data stored in REGISTRY_ENCOUNTER
- Detection - Indicates that detected patient will be added as candidates to a registry
- Intervention - Like detection, but the Intervention property will be set on the patient regardless of status
- Collection - The data type will be copied to the REGISTRY_PATIENT_CODES table or REGISTRY_ENCOUNTER from the appropriate ETL table
Data Loading Process
This table details how the PheDRS Data Loading Criteria ontology is used to by backend clients (controlled by loadAll.bsh) to set patient status and review status. Like other registry configuration criteria, the configuration information is stored in the cvterm and cvtermprop for that registry.
These scripts detect patients for the registry (updating status_id) and flag patients for review (updating review_status_id) when registry specific events occur based on registry configuration.
The server side process will never set the patient registry status to 'Under Review" or "Reviewed"
|Criteria Name||Event Description||Input Patient Registry Status||Input Patient Review Status||Input REGISTRY _PATIENT _CVTERM||Output Patient Registry Status Change||Output Patient Review Status||Output REGISTRY _PATIENT _CVTERM||Action Description||Implementation Notes|
|Diagnosis (Code_Detection)||PATIENT_CODE entry hat matches diagnosis criteria in CVTERMPROP||NULL||NULL||NULL||CANDIDATE||NEVER REVIEWED||ANY||Add candidate||CVTERMs corresponding to codes have a CVTERMPROP set on them of type registry_name (from cv_id 11) with a value containing text "diagnosis criteria"|
|Provisional||ANY||ANY||NO CHANGE||NEEDS REVIEW||ANY||Flag rejected and provisional candidates for review||Plan is to swap CVTERMs such that CVTERM_ID is the registry and the TYPE_ID is the code|
|Candidate||ANY||ANY||NO CHANGE||NO CHANGE||ANY||Ignore diagnosis criteria on accepted patients|
|NLP_Detection||NLP_HITS_EXTENDED contains CUI with detection criteria||NULL||NULL||NULL||CANDIDATE||NEVER REVIEWED||ANY||Add candidate||CVTERMS corresponding to registries have a CVTERMPROP set on them with cvterm_id (registry_id), type_id (cvterm in NLP Pipeline Parameter Ontology) with value containing a UMLS CUI|
|Provisional||ANY||ANY||NO CHANGE||NEEDS REVIEW||ANY||Flag rejected and provisional candidates for review||C98764323,C0012345,C0654321|
|Candidate||ANY||ANY||NO CHANGE||NO CHANGE||ANY||Ignore detection criteria on accepted patients||Multiple CUIs are supported as additional rows in CVTERMPROP. Contextual CUIs are supported via commas|
|NLP_Intervention||NLP_HITS_EXTENDED||ANY||ANY||Requires Intervention||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||NO CHANGE||CVTERMS corresponding to registries have a CVTERMPROP set on them with cvterm_id (registry_id), type_id (cvterm in NLP Pipeline Parameter Ontology) with value containing a UMLS CUI|
|contains CUI with||ANY||ANY||Intervention Complete < Encounter Date||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||Requires Intervention||C98764323,C0012345,C0654321|
|intervention criteria||ANY||ANY||Any other current valid cvterms||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||Requires Intervention||Multiple CUIs are supported as additional rows in CVTERMPROP. Contextual CUIs are supported via commas|
|ANY||ANY||Intervention Complete > Encounter Date||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||NO CHANGE||Compare date of code/encounter with the end(if not null) or start_date of the REGISTRY_PATIENT_CVTERM entry|
|Inclusion (Code Inclusion)||PATIENT_CODE entry that matches inclusion criteria in CVTERMPROP||All except Accepted||ANY||ANY||ACCEPTED||NEEDS REVIEW||DRG Codes generate automatic registry inclusion|
|Accepted||ANY||ANY||NO CHANGE||NEEDS REVIEW|
|Eligibility||Custom||ANY||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||Machine learning of patient eligibility MACHINE_ACCEPTANCE_SCORE in REGISTRY_PATIENT is set to a non-zero value||Custom registry specific implementation that should result in a publication… :)|
|Code_Collection||None (daily)||Candidate||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||Specify data to collect for the registry||CVTERMPROP has cvterm_id (registry_id) and type_id (data source) and value which is a regular expression specifying code_values to collect from REGISTRY_PATIENT_CODES|
|Accepted||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||Do not collect data unless patient is in registry|
|Encounter Collection||None (daily)||Candidate||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||Collect specified encounter data for people in the registry||CVTERMPROP has cvterm_id (registry_id) and type_id (sourcesystem_cd) and value in the format below|
|Accepted||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||REGEX||REGEX….|
|Encounter Intervention||Encounter||ANY||ANY||Requires Intervention||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||NO CHANGE||Encounters matching criteria specified in CVTERM_PROP (which contains WHERE clause SQL) are loaded into REGISTRY_ENCOUNTERS||CVTERMPROP has cvterm_id (registry_id) and type_id (sourcesystem_cd) and value in SQL format|
|ANY||ANY||Intervention Complete < Encounter Date||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||Requires Intervention|
|ANY||ANY||Any other current valid cvterms||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||Requires Intervention|
|ANY||ANY||Intervention Complete > Encounter Date||NO CHANGE (CANDIDATE IF NULL)||NO CHANGE||NO CHANGE||Flag patients for intervention|
|Document Loading (deprecated)||Existence of documents||Accepted||ANY||ANY||NO CHANGE||NO CHANGE||NO CHANGE||Load NLP_DOCS from source systems for registry patients||Should be a default analysis type that is used for CVTERMPROP|
Evidence Code Ontology
The evidence code ontology is used to describe how a patient's status in the registry (ACCEPTED, REJECTED, CANDIDATE OR PROVISIONAL) has been decided.
|Referred||REF||Current patient registry status has been assigned manually|
|Algorithm Discovered Patient||ALG||Current patient registry status assigned by an algorithm|
|NLP Discovered Patient||NLP||Current patient registry status has been assigned on the basis of NLP processed text.|
|Code discovered patient||DIAG||Current patient registry status has been assigned on the basis of a structured code, ex) ICD-10-CM|
|Encounter Discovered Patient||ENC||Current patient registry status has been assigned on the basis of an encounter|
Registry Cvtermprop Data Loading Values for Evidence Updating
Code Discovered Patients
- Registry cvtermprop must have property in cvtermprop starting with "Code" and ending with "Detection"
- Registry cvtermprop must have a type_id with appropriate ontology and a value that ends with "diagnosis criteria" or "inclusion criteria"
Encounter Discovered Patients
- Registry cvtermprop value must have criteria for "Encounter Intervention" or "Encounter Detection" and non-null SQL clause in the value field
NLP Discovered Patients
- Registry cvtermprop must have property in cvtermprop starting with "NLP" AND ending with ("Detection" or "Intervention" or "Inclusion")
- Registry cvtermprop must have a type_id with appropriate ontology AND a value that ends with ("detection NLP criteria" or "inclusion NLP criteria" or "intervention NLP criteria")
TODO - make separate CV for this