quality-measure-engine 0.2.0 → 0.8.0

data/README.md

@@ -1,7 +1,22 @@
-This project will provide a library that can ingest HITSP C32's and ASTM CCR's and extract values needed to compute heath quality measures for a population. It will then be able to query over a population to compute how many people within a population conform to the measure.
+This project is a library designed to calculate clinical quality measures over a given population. Quality measures are described via JSON and provide the details on what information is needed from a patient record to calculate a quality measure. The logic of the measure is described in JavaScript using the MapReduce algorithmic framework.
+
+Usage
+=====
+
+Extracting Measure Data from a HITSP C32
+----------------------------------------
+
+Each quality measure will need to extract specific information from a HITSP C32 for calculation. First, for each quality measure, a QME::Importer::GenericImporter should be created by passing in the JSON definition of the quality measure.
+
+Next, an instance of QME::Importer::PatientImporter should be obtained by calling instance (it follows the singleton pattern). Add the GenericImporters for each desired measure with the add measure method. Finally, you can get a JSON representation of a patient record with the necessary information extracted by calling parse_c32.
+
+Calculating Quality Measures
+----------------------------
+
+Results of quality measures are represented by QME::QualityReport. This class provides ways to determine if a report has been calculated for a population in the database as well as ways to create jobs to run the calculations.
 
 Environment
------------
+===========
 
 This project currently uses Ruby 1.9.2 and is built using [Bundler](http://gembundler.com/). To get all of the dependencies for the project, first install bundler:
 
@@ -11,12 +26,25 @@ Then run bundler to grab all of the necessary gems:
 
     bundle install
 
-The Quality Measure engine relies on a MongoDB [MongoDB](http://www.mongodb.org/) running a minimum of version 1.6.* or higher.  To get and install Mongo refer to :
+The Quality Measure engine relies on a MongoDB [MongoDB](http://www.mongodb.org/) running a minimum of version 1.8.* or higher.  To get and install Mongo refer to:
+
+    http://www.mongodb.org/display/DOCS/Quickstart
 
-	http://www.mongodb.org/display/DOCS/Quickstart
+It also relies on [Redis](http://redis.io/) for background jobs via [Resque](https://github.com/defunkt/resque). To install Redis, please refer to:
+
+    http://redis.io/download
+
+You can also find information on Redis at the [Resque homepage](https://github.com/defunkt/resque). Resque is used by this project to calculate quality measures in  background jobs. We also use [resque-status](https://github.com/quirkey/resque-status). Please consult the resque-status instructions for working with the resque-web application if you would like to use it to monitor status.
+
+Running Resque Workers
+----------------------
+
+QME::QualityReport will kick off background jobs with Resque. For these jobs to to actually get performed, you need to be running resque workers. This can be done with the following:
+
+    QUEUE=* bundle exec rake resque:work
 
 Testing
--------
+=======
 
 This project uses [RSpec](http://github.com/rspec/rspec-core) for testing. To run the suite, just enter the following:
 
@@ -56,6 +84,6 @@ This project uses [metric_fu](http://metric-fu.rubyforge.org/) for source code a
 The project is currently configured to run Flay, Flog, Churn, Reek and Roodi
 
 Project Practices
-------------------
+=================
 
 Please try to follow our [Coding Style Guides](http://github.com/eedrummer/styleguide). Additionally, we will be using git in a pattern similar to [Vincent Driessen's workflow](http://nvie.com/posts/a-successful-git-branching-model/). While feature branches are encouraged, they are not required to work on the project.

data/Rakefile

@@ -1,8 +1,10 @@
 require 'rspec/core/rake_task'
 require 'yard'
 require 'metric_fu'
+require 'resque/tasks'
 
 ENV['MEASURE_DIR'] = ENV['MEASURE_DIR'] || File.join('fixtures', 'measure_defs')
+ENV['MEASURE_PROPS'] = ENV['MEASURE_PROPS'] || File.join('fixtures', 'measure_props')
 
 Dir['lib/tasks/*.rake'].sort.each do |ext|
   load ext

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.8.0

data/js/{map-reduce-utils.js → map_reduce_utils.js}

@@ -1,16 +1,24 @@
+function() {
 // Adds common utility functions to the root JS object. These are then
 // available for use by the map-reduce functions for each measure.
 // lib/qme/mongo_helpers.rb executes this function on a database
 // connection.
-(function() {
 
   var root = this;
 
+  // Takes an arbitrary number of arrays and single values and returns a flattened
+  // array of all of the elements with any null values removed. For efficiency, if 
+  // called with just a single array then it simply returns that array
+  root.normalize = function() {
+    if (arguments.length==1 && _.isArray(arguments[0]))
+      return arguments[0];
+    return _.compact(_.flatten(arguments));
+  }
+
   // returns the number of values which fall between the supplied limits
   // value may be a number or an array of numbers
   root.inRange = function(value, min, max) {
-    if (!_.isArray(value))
-      value = [value];
+    value = normalize(value);
     var count = 0;
     for (i=0;i<value.length;i++) {
       if ((value[i]>=min) && (value[i]<=max))
@@ -21,8 +29,7 @@
   
   // returns the largest member of value that is within the supplied range
   root.maxInRange = function(value, min, max) {
-    if (value==null)
-      return null;
+    value = normalize(value);
     var allInRange = _.select(value, function(v) {return v>=min && v<=max;});
     return _.max(allInRange);
   }
@@ -30,77 +37,63 @@
   // returns the number of values which are less than the supplied limit
   // value may be a number or an array of numbers
   root.lessThan = function(value, max) {
-    if (!_.isArray(value))
-      value = [value];
-    var count = 0;
-    for (i=0;i<value.length;i++) {
-      if (value[i]<=max)
-        count++;
-    }
-    return count;
+    value = normalize(value);
+    var matching = _.select(value, function(v) {return v<=max;});
+    return matching.length;
   };
   
-  // Returns the a boolean true when any entry within conditions[i].end is 
-  // ever less than the endDate. If no conditions meet this criteria, this
-  // function always returns false
+  // Returns true if any conditions[i].end is within the specified period,
+  // false otherwise
   root.conditionResolved = function(conditions, startDate, endDate) {
-    if (conditions) {
-      return _.any(conditions, function(condition) {
-          return inRange(condition.end, startDate, endDate) > 0;
-      });
-    } else {
-      return false
+    conditions = normalize(conditions);
+    var resolvedWithinPeriod = function(condition) {
+      return (condition.end>=startDate && condition.end<=endDate);
     };
+    return _.any(conditions, resolvedWithinPeriod);
   };
   
   // Returns the minimum of readings[i].value where readings[i].date is in
   // the supplied startDate and endDate. If no reading meet this criteria,
   // returns defaultValue.
   root.minValueInDateRange = function(readings, startDate, endDate, defaultValue) {
+    readings = normalize(readings);
+    
     var readingInDateRange = function(reading) {
-      var result = inRange(reading.date, startDate, endDate);
-      return result;
+      return (reading.date>=startDate && reading.date<=endDate);
     };
     
-    if (!readings || readings.length<1)
-      return defaultValue;
-  
     var allInDateRange = _.select(readings, readingInDateRange);
-    var min = _.min(allInDateRange, function(reading) {return reading.value;});
-    if (min)
-      return min.value;
-    else
+    if (allInDateRange.length==0)
       return defaultValue;
+    var min = _.min(allInDateRange, function(reading) {return reading.value;});
+    return min.value;
   };
   
   // Returns the most recent readings[i].value where readings[i].date is in
   // the supplied startDate and endDate. If no reading meet this criteria,
   // returns defaultValue.
   root.latestValueInDateRange = function(readings, startDate, endDate, defaultValue) {
+    readings = normalize(readings);
+  
     var readingInDateRange = function(reading) {
-      var result = inRange(reading.date, startDate, endDate);
-      return result;
+      return (reading.date>=startDate && reading.date<=endDate);
     };
     
-    if (!readings || readings.length<1)
-      return defaultValue;
-  
     var allInDateRange = _.select(readings, readingInDateRange);
-    var latest = _.max(allInDateRange, function(reading) {return reading.date;});
-    if (latest)
-      return latest.value;
-    else
+    if (allInDateRange.length==0)
       return defaultValue;
+    var latest = _.max(allInDateRange, function(reading) {return reading.date;});
+    return latest.value;
   };
   
   // Returns the number of actions that occur within the specified time period of
   // something. The first two arguments are arrays or single-valued time stamps in
   // seconds-since-the-epoch, timePeriod is in seconds.
   root.actionFollowingSomething = function(something, action, timePeriod) {
-    if (!_.isArray(something))
-      something = [something];
-    if (!_.isArray(action))
-      action = [action];
+    something = normalize(something);
+    action = normalize(action);
+    if (timePeriod===undefined)
+      timePeriod=Infinity;
     
     var result = 0;
     for (i=0; i<something.length; i++) {
@@ -114,61 +107,33 @@
     return result;
   }
     
-  // Returns the number of actions that occur after
-  // something. The first two arguments are arrays or single-valued time stamps in
-  // seconds-since-the-epoch.
-  root.actionAfterSomething = function(something, action) {
-    if (!_.isArray(something))
-      something = [something];
-    if (!_.isArray(action))
-      action = [action];
-   
-    var result = 0;
-    for (i=0; i<something.length; i++) {
-      var timeStamp = something[i];
-      for (j=0; j<action.length;j++) {
-        if (action[j]>=timeStamp )
-          result++;
-      }
-    }
-    return result;
-  }
-  
   // Returns all members of the values array that fall between min and max inclusive
   root.selectWithinRange = function(values, min, max) {
+    values = normalize(values);
     return _.select(values, function(value) { return value<=max && value>=min; });
   }
     
   root.map = function(record, population, denominator, numerator, exclusion) {
-    var value = {population: [], denominator: [], numerator: [], exclusions: [], antinumerator: []};
+    var value = {population: false, denominator: false, numerator: false, 
+                 exclusions: false, antinumerator: false, patient_id: record._id,
+                 first: record.first, last: record.last, gender: record.gender,
+                 birthdate: record.birthdate};
     var patient = record._id;
     if (population()) {
-      value.population.push(patient);
+      value.population = true;
       if (denominator()) {
-        value.denominator.push(patient);
+        value.denominator = true;
         if (numerator()) {
-          value.numerator.push(patient);
+          value.numerator = true;
         } else if (exclusion()) {
-          value.exclusions.push(patient);
-          value.denominator.pop();
+          value.exclusions = true;
+          value.denominator = false;
         } else {
-          value.antinumerator.push(patient);
+          value.antinumerator = true;
         }
       }
     }
-    emit(null, value);
-  };
-
-  root.reduce = function (key, values) {
-    var total = {population: [], denominator: [], numerator: [], exclusions: [], antinumerator: []};
-    for (var i = 0; i < values.length; i++) {
-      total.population = total.population.concat(values[i].population);
-      total.denominator = total.denominator.concat(values[i].denominator);
-      total.numerator = total.numerator.concat(values[i].numerator);
-      total.exclusions = total.exclusions.concat(values[i].exclusions);
-      total.antinumerator = total.antinumerator.concat(values[i].antinumerator);
-    }
-    return total;
+    emit(ObjectId(), value);
   };
 
-})();
+}

data/js/{underscore-min.js → underscore_min.js}

@@ -1,3 +1,4 @@
+function(){
 // Underscore.js 1.1.2
 // (c) 2010 Jeremy Ashkenas, DocumentCloud Inc.
 // Underscore is freely distributable under the MIT license.
@@ -5,7 +6,7 @@
 // Oliver Steele's Functional, and John Resig's Micro-Templating.
 // For all details and documentation:
 // http://documentcloud.github.com/underscore
-(function(){var o=this,A=o._,r=typeof StopIteration!=="undefined"?StopIteration:"__break__",k=Array.prototype,m=Object.prototype,i=k.slice,B=k.unshift,C=m.toString,p=m.hasOwnProperty,s=k.forEach,t=k.map,u=k.reduce,v=k.reduceRight,w=k.filter,x=k.every,y=k.some,n=k.indexOf,z=k.lastIndexOf;m=Array.isArray;var D=Object.keys,c=function(a){return new l(a)};if(typeof exports!=="undefined")exports._=c;o._=c;c.VERSION="1.1.2";var j=c.each=c.forEach=function(a,b,d){try{if(s&&a.forEach===s)a.forEach(b,d);else if(c.isNumber(a.length))for(var e=
+var o=this,A=o._,r=typeof StopIteration!=="undefined"?StopIteration:"__break__",k=Array.prototype,m=Object.prototype,i=k.slice,B=k.unshift,C=m.toString,p=m.hasOwnProperty,s=k.forEach,t=k.map,u=k.reduce,v=k.reduceRight,w=k.filter,x=k.every,y=k.some,n=k.indexOf,z=k.lastIndexOf;m=Array.isArray;var D=Object.keys,c=function(a){return new l(a)};if(typeof exports!=="undefined")exports._=c;o._=c;c.VERSION="1.1.2";var j=c.each=c.forEach=function(a,b,d){try{if(s&&a.forEach===s)a.forEach(b,d);else if(c.isNumber(a.length))for(var e=
 0,f=a.length;e<f;e++)b.call(d,a[e],e,a);else for(e in a)p.call(a,e)&&b.call(d,a[e],e,a)}catch(g){if(g!=r)throw g;}return a};c.map=function(a,b,d){if(t&&a.map===t)return a.map(b,d);var e=[];j(a,function(f,g,h){e[e.length]=b.call(d,f,g,h)});return e};c.reduce=c.foldl=c.inject=function(a,b,d,e){var f=d!==void 0;if(u&&a.reduce===u){if(e)b=c.bind(b,e);return f?a.reduce(b,d):a.reduce(b)}j(a,function(g,h,E){d=!f&&h===0?g:b.call(e,d,g,h,E)});return d};c.reduceRight=c.foldr=function(a,b,d,e){if(v&&a.reduceRight===
 v){if(e)b=c.bind(b,e);return d!==void 0?a.reduceRight(b,d):a.reduceRight(b)}a=(c.isArray(a)?a.slice():c.toArray(a)).reverse();return c.reduce(a,b,d,e)};c.find=c.detect=function(a,b,d){var e;j(a,function(f,g,h){if(b.call(d,f,g,h)){e=f;c.breakLoop()}});return e};c.filter=c.select=function(a,b,d){if(w&&a.filter===w)return a.filter(b,d);var e=[];j(a,function(f,g,h){if(b.call(d,f,g,h))e[e.length]=f});return e};c.reject=function(a,b,d){var e=[];j(a,function(f,g,h){b.call(d,f,g,h)||(e[e.length]=f)});return e};
 c.every=c.all=function(a,b,d){b=b||c.identity;if(x&&a.every===x)return a.every(b,d);var e=true;j(a,function(f,g,h){(e=e&&b.call(d,f,g,h))||c.breakLoop()});return e};c.some=c.any=function(a,b,d){b=b||c.identity;if(y&&a.some===y)return a.some(b,d);var e=false;j(a,function(f,g,h){if(e=b.call(d,f,g,h))c.breakLoop()});return e};c.include=c.contains=function(a,b){if(n&&a.indexOf===n)return a.indexOf(b)!=-1;var d=false;j(a,function(e){if(d=e===b)c.breakLoop()});return d};c.invoke=function(a,b){var d=i.call(arguments,
@@ -21,4 +22,4 @@ b.multiline;if(d!=="object")return false;if(a.length&&a.length!==b.length)return
 a.callee)};c.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};c.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};c.isNumber=function(a){return a===+a||C.call(a)==="[object Number]"};c.isBoolean=function(a){return a===true||a===false};c.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};c.isRegExp=function(a){return!!(a&&a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};c.isNaN=function(a){return c.isNumber(a)&&isNaN(a)};c.isNull=function(a){return a===
 null};c.isUndefined=function(a){return typeof a=="undefined"};c.noConflict=function(){o._=A;return this};c.identity=function(a){return a};c.times=function(a,b,d){for(var e=0;e<a;e++)b.call(d,e)};c.breakLoop=function(){throw r;};c.mixin=function(a){j(c.functions(a),function(b){F(b,c[b]=a[b])})};var G=0;c.uniqueId=function(a){var b=G++;return a?a+b:b};c.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g};c.template=function(a,b){var d=c.templateSettings;d="var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push('"+
 a.replace(/\\/g,"\\\\").replace(/'/g,"\\'").replace(d.interpolate,function(e,f){return"',"+f.replace(/\\'/g,"'")+",'"}).replace(d.evaluate||null,function(e,f){return"');"+f.replace(/\\'/g,"'").replace(/[\r\n\t]/g," ")+"__p.push('"}).replace(/\r/g,"\\r").replace(/\n/g,"\\n").replace(/\t/g,"\\t")+"');}return __p.join('');";d=new Function("obj",d);return b?d(b):d};var l=function(a){this._wrapped=a};c.prototype=l.prototype;var q=function(a,b){return b?c(a).chain():a},F=function(a,b){l.prototype[a]=function(){var d=
-i.call(arguments);B.call(d,this._wrapped);return q(b.apply(c,d),this._chain)}};c.mixin(c);j(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var b=k[a];l.prototype[a]=function(){b.apply(this._wrapped,arguments);return q(this._wrapped,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];l.prototype[a]=function(){return q(b.apply(this._wrapped,arguments),this._chain)}});l.prototype.chain=function(){this._chain=true;return this};l.prototype.value=function(){return this._wrapped}})();
+i.call(arguments);B.call(d,this._wrapped);return q(b.apply(c,d),this._chain)}};c.mixin(c);j(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var b=k[a];l.prototype[a]=function(){b.apply(this._wrapped,arguments);return q(this._wrapped,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];l.prototype[a]=function(){return q(b.apply(this._wrapped,arguments),this._chain)}});l.prototype.chain=function(){this._chain=true;return this};l.prototype.value=function(){return this._wrapped}}

data/lib/qme/database_access.rb

@@ -0,0 +1,30 @@
+module QME
+  module DatabaseAccess
+    
+    # Set up the information to connect to the database. Database host
+    # and port may be set using the environment variables TEST_DB_HOST
+    # and TEST_DB_PORT which default to localhost and 27017 respectively.
+    # @param [String] db_name the name of the database to use
+    def determine_connection_information(db_name = nil)
+      @db_name = ENV['DB_NAME'] || db_name || 'test'
+      @db_host = ENV['TEST_DB_HOST'] || 'localhost'
+      @db_port = ENV['TEST_DB_PORT'] ? ENV['TEST_DB_PORT'].to_i : 27017
+    end
+    
+    # Directly inject an instance of a database
+    # @param [Mongo::Database] db the database that you would like the object to use
+    def inject_db(db)
+      @db = db
+    end
+
+    # Lazily creates a connection to the database and initializes the
+    # JavaScript environment
+    # @return [Mongo::Connection]
+    def get_db
+      if @db == nil
+        @db = Mongo::Connection.new(@db_host, @db_port).db(@db_name)
+      end
+      @db
+    end
+  end
+end

data/lib/qme/importer/code_system_helper.rb

@@ -7,11 +7,13 @@ module QME
         '2.16.840.1.113883.6.1' =>    'LOINC',
         '2.16.840.1.113883.6.96' =>   'SNOMED-CT',
         '2.16.840.1.113883.6.12' =>   'CPT',
+        #'2.16.840.1.113883.3.88.12.80.32' => 'CPT',
         '2.16.840.1.113883.6.88' =>   'RxNorm',
         '2.16.840.1.113883.6.103' =>  'ICD-9-CM',
         '2.16.840.1.113883.6.104' =>  'ICD-9-CM',
         '2.16.840.1.113883.6.90' =>   'ICD-10-CM',
-        '2.16.840.1.113883.6.14' =>   'HCPCS'
+        '2.16.840.1.113883.6.14' =>   'HCPCS',
+        '2.16.840.1.113883.6.59' =>   'CVX'
       }
       
       # Returns the name of a code system given an oid

data/lib/qme/importer/entry.rb

@@ -2,15 +2,14 @@ module QME
   module Importer
     # Object that represents a CDA Entry (or act, observation, etc.)
     class Entry
-      attr_accessor :start_time, :end_time, :time
-      attr_reader :status, :codes, :value
-      
+      attr_accessor :start_time, :end_time, :time, :status
+      attr_reader :codes, :value
+
       def initialize
         @codes = {}
-        @status = {}
         @value = {}
       end
-      
+
       def Entry.from_event_hash(event)
         entry = Entry.new
         entry.add_code(event['code'], event['code_set'])
@@ -18,7 +17,7 @@ module QME
         entry.set_value(event['value'], event['unit'])
         entry
       end
-      
+
       # Add a code into the Entry
       # @param [String] code the code to add
       # @param [String] code_system the code system that the code belongs to
@@ -26,15 +25,7 @@ module QME
         @codes[code_system] ||= []
         @codes[code_system] << code
       end
-      
-      # Set a status for the Entry
-      # @param [String] status_code the code to set
-      # @param [String] code_system the code system that the status_code belongs to
-      def set_status(status_code, code_system)
-        @status[:code] = status_code
-        @status[:code_system] = code_system
-      end
-      
+
       # Sets the value for the entry
       # @param [String] scalar the value
       # @param [String] units the units of the scalar value
@@ -42,24 +33,23 @@ module QME
         @value[:scalar] = scalar
         @value[:units] = units
       end
-      
+
       # Checks if a code is in the list of possible codes
       # @param [Array] code_set an Array of Hashes that describe the values for code sets
       # @return [true, false] whether the code is in the list of desired codes
       def is_in_code_set?(code_set)
         @codes.keys.each do |code_system|
-          codes_in_system = code_set.find {|set| set['set'] == code_system}
-          if codes_in_system
+          all_codes_in_system = code_set.find_all {|set| set['set'] == code_system}
+          all_codes_in_system.each do |codes_in_system|
             matching_codes = codes_in_system['values'] & @codes[code_system]
             if matching_codes.length > 0
               return true
             end
           end
         end
-        
         false
       end
-      
+
       # Tries to find a single point in time for this entry. Will first return time if it is present,
       # then fall back to start_time and finally end_time
       def as_point_in_time
@@ -71,13 +61,13 @@ module QME
           @end_time
         end
       end
-      
+
       # Checks to see if this Entry can be used as a date range
       # @return [true, false] If the Entry has a start and end time returns true, false otherwise.
       def is_date_range?
         (! @start_time.nil?) && (! @end_time.nil?) 
       end
-      
+
       # Checks to see if this Entry is usable for measure calculation. This means that it contains
       # at least one code and has one of its time properties set (start, end or time)
       # @return [true, false]