# About QDM Phenotyping is a tool suite to automate the transformation of QDM/HQMF XML into Drools Rules, and execute them against a Patient data source. QDM Phenotyping actually represents a suite of inter-connected tools and REST Services. General interaction is shown in the diagram below. ![Architecture](assets/img/htp-drools-arch.png) #### Major Components #### QDM XML > __QDM__ is the National Quality Forum's (NQF) Quality Data Model. It is an information model representing the essential data needed to generate quality measures. Because it is an information model, it doesn't necessarily go into the level of detail needed in an implementation, but it certainly describes the high level structures that an implementation needs to compute quality measures. <br /> > __eMeasures__ is a term describing the electronic representation of quality measures. In common use, it often refers to the electronic measures that NQF developed to represent the quality measures required under the ONC & CMS Meaningful Use regulations. It is also used to refer to the HL7 HQMF. <br /> > __HQMF__ stands for Health Quality Measure Format. This is an HL7 Draft Standard for Trial Use (DSTU). The DSTU is presently being reballoted by HL7 for a second release. This is an electronic format for the representation of quality measures. Release 1 is currently used by NQF to deliver eMeasures for Meaningful Use. Release 2 was developed in large part based on pilot work being developed by Query Health. <br /> -- <cite>[Copyright (c) 2013 by Keith W. Boone.](http://motorcycleguy.blogspot.com/2012/11/hashtag-soup-relating-qdm-hqmf.html) #### XML -> JSON The XML -> JSON transformation accepts QDM XML and transforms it into easily parsable JSON. This functionality is provided by a REST service wrappering the [Project Cypress health-data-standards](https://github.com/projectcypress/health-data-standards) project. #### QDM JSON The JSON representation of the QDM/HQMF XML provided by [Project Cypress health-data-standards](https://github.com/projectcypress/health-data-standards). #### JSON -> JBoss Drools Rules The _QDM JSON_ is programatically transformed into executable JBoss Drools rules by a compiler. The result of this transformation is a single Drools Rules file that can be executed by the _Drools Engine_, or other JBoss Drools environment. #### Drools Engine Using the [JBoss Drools](http://www.jboss.org/drools/) engine, the generated Drools Rules can be executed given the target Patient set. The result of this execution will be the Patent set result mapped to the given populations (such as NUMER, DENOM, etc). #### Value Set Processor Many phenotyping rules are dependent on some event being part of a larger set of event types, or a ___ValueSet___. For example: ```json "DiagnosisActiveAcutePharyngitis": { "title": "Acute Pharyngitis", "description": "Diagnosis, Active: Acute Pharyngitis", "standard_category": "diagnosis_condition_problem", "qds_data_type": "diagnosis_active", "code_list_id": "2.16.840.1.113883.3.464.1003.102.12.1011", "type": "conditions", "definition": "diagnosis", "status": "active", "hard_status": false, "negation": false, "source_data_criteria": "DiagnosisActiveAcutePharyngitis" }, ``` In this example, for this rule to be satisfied, a Patient must have a _Diagnosis_ that matches the ```code_list_id``` of ```2.16.840.1.113883.3.464.1003.102.12.1011```. It is important, then, to have a mechanism to be able to determine which codes are actually in ```2.16.840.1.113883.3.464.1003.102.12.1011```. This is done through the _Value Set Processor_ - or specifically, the ```ValueSetCodeResolver``` Interface. Interface: ````edu.mayo.qdm.executor.valueset.ValueSetCodeResolver```` An Interface through which implementations can test participation of a code in a ValueSet. # Installation ## Build/Compile - Install [Git](http://git-scm.com/book/en/Getting-Started-Installing-Git) - Install [Maven](http://maven.apache.org/download.cgi) - Ensure ```MAVEN_OPTS``` are set, and are allocated sufficient memory space. <br/> -> ___example___: ```MAVEN_OPTS="-Xmx1000m -XX:MaxPermSize=100m"``` - Clone the repository using a Git Clone ```https://github.com/SHARP-HTP/qdm-phenotyping.git``` - From the ```qdm-phenotyping``` directory, run ```mvn clean install``` Artifacts will be available in the ```target``` directory of the modules. ## Configuration The main configuration file will be located at ```${USER.HOME}/.qdm-phenotyping/qdm-phenotyping.properties``` All properties are optional, and defaults are listed below. Configuration: ```qdm-phenotyping.properties``` (example) ``` valuesets.valueSetResolver=CYPRESS security.username=admin security.password=admin drools.qdm2jsonService=http://qdm2json.phenotypeportal.org ``` __Property:__ ```valuesets.valueSetResolver``` - The ```ValueSetCodeResolver``` implementation to use. - Allowed values - ```CYPRESS``` - The Cypress JSON Value Set data implementation - ```CTS2``` - A [CTS2](http://informatics.mayo.edu/cts2) Value Set Service implementation - Default: ```CYPRESS``` __Property:__ ```drools.qdm2jsonService``` - The _QDM2JSON_ REST Service to use. - Default: ```http://qdm2json.phenotypeportal.org``` __Property:__ ```security.username``` - The user name to use to authorize execution via the REST API. __Property:__ ```security.password``` - The password to use to authorize execution via the REST API. ## Run QDM Phenotyping has two main user facing interfaces, an HTTP REST-based web application, and an Command Line Interface. ### Webapp There are two ways to run the REST-based web application, via an embedded Jetty server, or by placing the WAR file in an application container (such as JBoss or Tomcat). #### Embedded Jetty Server To start the webapp, navigate to the __qdm-webapp__ module and run: ```mvn jetty:run [-Dsecure=true] [-Dport=8888] [-Dcontext.path=/appname]``` __Parameter:__ ```secure``` - ```true``` runs the container in secure HTTPS mode, ```false``` in HTTP. - Default: ```false``` __Parameter:__ ```port``` - The port in which to run the container. - Default: ```8081``` __Parameter:__ ```context.path``` - The webapp context in which to run, or ```http://localhost:8081/{context.path}``` - Default: ```qdm-webapp``` #### WAR - Complete the ```Build/Compile``` instructions as instructed above (or [download the pre-built WAR](http://static.phenotypeportal.org/downloads/webapp/)). - Deploy the WAR to an application container. __NOTE:__ If building from source, the WAR file will be in the ```qdm-webapp/target/``` directory. ### Command Line - Complete the ```Build/Compile``` instructions as instructed above (or [download the binaries](http://static.phenotypeportal.org/downloads/cli/)). - Unzip the binary package. This will be either in ```target/dist/``` of the ```qdm-cli``` module if building from source, or downloaded from the link above. - Navigate to the ```bin``` directory. The two available commands are ```qdm-validate``` and ```qdm2drools``` #### qdm-validate - __Description:__ Runs the Cypress Validation and produces a report. - __Usage:__ ```qdm-validate``` #### qdm2drools - __Description:__ Converts QDM/HQMF XML files into JBoss Drools. - __Usage:__ ```qdm-validate -f qdmXmlFile``` - __Example:__ ```qdm-validate -f path/to/qdm.xml``` ## Maven Add the following repository to our ```pom.xml``` file: ```xml <repository> <id>informatics-releases</id> <url>http://informatics.mayo.edu/maven/content/repositories/releases</url> </repository> ``` Then add in the dependency: ```xml <dependency> <groupId>edu.mayo</groupId> <artifactId>qdm-{module}</artifactId> <version>1.0.0.RELEASE</version> </dependency> ``` ___NOTE:___ Replace the ```{module}``` placeholder with the name of one of the modules listed below. ## Downloads __Webapp WAR:__ [qdm-webapp](http://static.phenotypeportal.org/downloads/webapp/) __Commmand Line Binaries:__ [qdm-cli (zip/tar.gz)](http://static.phenotypeportal.org/downloads/cli/) __Virtual Machine Images:__ [sharp-htp.ora (~ 4.5 GB)](http://static.phenotypeportal.org/downloads/vm/) ## Virtual Image All QDM Phenotyping functionality, as well as a local image of the [Phenotype Portal](phenotypeportal.org), is available for download as a Virtual Machine Image. This image can be imported into [VirtualBox](https://www.virtualbox.org/) or [VMWare Fusion](http://www.vmware.com/products/fusion/). __Download:__ [Virtual Machine Image](http://static.phenotypeportal.org/downloads/vm/) (~ 4.5 GB) ### VM Image Details __IP Address:__ `````` __Login Username/Password:__ sharp-htp/sharp-htp ### VM Image Usage The VM contains a demonstration of the API capabilities, along with a local image of the [Phenotype Portal](http://phenotypeportal.org). __API Functionality:__ []( __Local Phenotype Portal:__ []( # Modules #### qdm-cypress A module for interacting with data from the [Cypress Project](http://projectcypress.org/). Functionality includes transforming Cypress patient data into the qdm-phenotyping model, and validating population results against expected values. #### qdm-executor QDM Executor is responsible for compiling QDM XML into executable Drools Rules and executing these rules against a patient set. #### qdm-demographics A processing module for aggregating Demographics data from a set of processed Patients. #### qdm-patient-model QDM Patient Model is a Java Bean representation of secondary use patient data. This model is optimized to be used with the ```qdm-executor``` module, and is not intended to be a standard patient data format for transport or otherwise. #### qdm-webapp A web application exposing the QDM Phenotyping API via REST Services. #### qdm-cli QDM CLI is the command-line interface into the QDM Phenotyping project. # API Guide All Phenotyping functionality is exposed through a small set of Interfaces described below. The API provides __execution__ functionality -- meaning, executing a specified QDM XML measure against a Patient population. After ___execution___, some default ___analytics___ can be done on the result. Note, however, that the provided analytics functionality is minimal, and it is expected that end users will have greater analytic needs than provided. ## Executing Interface: ````edu.mayo.qdm.executor.Executor```` The main interface for Patient rules execution. #### Getting the ```Executor``` ```java Executor executor = ExecutorFactory.instance().getExecutor(); ``` #### Sample Execution ```java ExecutorFactory factory = ExecutorFactory.instance(); Results results = factory.getExecutor().execute( patients, qdmXml, new MeasurementPeriod(startDate, true, endDate, true), valueSetDefinitions); ``` ```Results``` is the raw results of the execution. It is with this object that analytics will be performed. __NOTE:__ The ```Results``` object will contain a reference to every Patient that matched the query logic. For very large Patient sets, this may be undesireable. If this is the case, a __callback__ execution may be more appropriate: ```java ExecutorFactory factory = ExecutorFactory.instance(); factory.getExecutor().execute( patients, qdmXml, measurementPeried, valueSetDefinitions, new ResultCallback() { @Override public void hit(String population, Patient patient) { /* Process and discard the Patient here */ } } ); ``` This has the advantage of allowing for a large Patient set with constant memory useage (assuming that the Patient is process and then discarded). ## Processing Results The ```Results``` response includes a list of population identifiers (such as ```IPP``` or ```DENOM```), and a Set of Patients that belong to that population. Clients should perform need analytics on the ```Results``` object after execution. Some default functionality is provided in the form of the ```DemographicsProcessor``` class. Class: ```edu.mayo.qdm.demographics.DemographicsProcessor``` A simple population analytics processor that counts age/gender/race/etc. statistics. ##### Getting the ```DemographicsProcessor``` ```java DemographicsProcessor demographicsProcessor = new DemographicsProcessor() ``` #### Sample Analytics ```java /* 'results' is the result of an Execution. */ Demographics demographics = this.demographicsProcessor.getDemographics(results.asMap()); ``` # Cypress Validation Validation of the execution logic is handled by [Project Cypress](http://projectcypress.org/), which supplies a test set of Patient data along with expected results. The QDM Phenotyping project is currently validated against all EP Cypress measurses with the exception of two (```0710``` and ```0059```). These last two are pending further clarification from the Cypress team. There are two ways to run a validation report yourself: * Via the command-line (```qdm-cli```) * Via the REST WebApp (```qdm-webapp```) #### Validation through the Command Line - Complete the ```Build/Compile``` instructions as instructed above (or [download the binaries](http://static.phenotypeportal.org/downloads/cli/)). - Unzip the binary package. This will be either in ```target/dist/``` of the ```qdm-cli``` module if building from source, or downloaded from the link above. - Navigate to the ```bin``` directory and run: ```./qdm-validate```. This will execute all of the Cypress measures and display a PASS/FAIL report. #### Validation through the WebApp - Complete the ```Build/Compile``` instructions as instructed above. - Naviate to the ```qdm-webapp``` module (in the ```qdm-phenotyping/qdm-webapp``` directory). - Ensure ```MAVEN_OPTS``` are set. ___Example___: ```MAVEN_OPTS="-Xmx1000m -XX:MaxPermSize=100m"``` - Execute ```mvn jetty:run```. This will start the web application in an embedded web server. This may take a few minutes to start. - Navigate to the [Cypress Validation Report Page (local)](http://localhost:8081/qdm-webapp/executor/cypress/report) - This report will be generated on deman, each time this page is accessed. Note that the first pass will take some time -- this is expected, as the Drools engine is building the rules Knowledge bases for each measure. Subsequent executions will be much faster, as Knowlege bases are stored in memory. #### Validation through phenotypeportal.org Current Cypress Validation Reports are available on demand from [phenotypeportal.org](http://api.phenotypeportal.org/executor/cypress/report). # License All artifacts are licensed under the [Apache License](http://www.apache.org/licenses/LICENSE-2.0.txt). For all Cypress content license restrictions, see [Project Cypress](http://projectcypress.org/). # Acknowledgements We would like to achnowlege [Project Cypress](http://projectcypress.org/), [USHIK](https://ushik.ahrq.gov/), and the [NLM VSAC](https://vsac.nlm.nih.gov/) for tooling and services. # More Information For more information, and to see an application of this tool suite, visit the [Phenotype Portal](http://phenotypeportal.org/). All code for this project (and more) can be found on our [GitHub page](https://github.com/SHARP-HTP) Please direct all software issue reports to our [Issue Tracker](https://github.com/SHARP-HTP/qdm-phenotyping/issues) Fixes/Collaborations are welcome! Please follow the following procedures: - Create an issue in the [Issue Tracker](https://github.com/SHARP-HTP/qdm-phenotyping/issues) - Create a Fork - Send a Pull Request Fork me on GitHub