conceptql 0.1.1 → 0.2.0

data/lib/conceptql/operators/one_in_two_out.rb

@@ -0,0 +1,62 @@
+require_relative 'operator'
+require_relative 'visit_occurrence'
+
+module ConceptQL
+  module Operators
+    class OneInTwoOut < Operator
+      desc <<-EOF
+Represents a common pattern in research algorithms: searching for a condition
+that appears either two times in an outpatient setting with a 30-day gap or once
+in an inpatient setting
+      EOF
+      allows_one_upstream
+      category %w(Temporal Relative)
+
+      def types
+        [:visit_occurrence]
+      end
+
+      def query(db)
+        inpatient = select_it(visit_query(db).where(place_of_service_concept_id: 8717), :visit_occurrence).from_self
+        outpatient = select_it(visit_query(db).exclude(place_of_service_concept_id: 8717), :visit_occurrence).from_self
+
+        gap = options[:gap] || 30
+        valid_outpatient_people = outpatient
+          .group_by(:person_id)
+          .select(:person_id)
+          .select_append(Sequel.expr(Sequel.function(:max, :start_date) - Sequel.function(:min, :end_date)).as(:date_diff))
+          .from_self
+            .where{ date_diff >= gap}
+
+        relevant_outpatient = outpatient.where(person_id: valid_outpatient_people.select(:person_id))
+        earliest(db, inpatient.union(relevant_outpatient))
+      end
+
+      private
+      def visit_query(db)
+        VisitOccurrence.new(FakeOperator.new(stream.evaluate(db).from_self, stream.types)).query(db)
+      end
+
+      def earliest(db, query)
+        db[:earliest]
+          .with(:earliest,
+            query.select_append { |o| o.row_number(:over, partition: :person_id, order: [Sequel.asc(:start_date), :criterion_type, :criterion_id]){}.as(:rn) })
+          .where(rn: 1)
+          .from_self
+      end
+
+      class FakeOperator < Operator
+        attr :types
+        def initialize(query, types)
+          @query = query
+          @types = types
+        end
+
+        def query(db)
+          @query
+        end
+      end
+    end
+  end
+end
+

data/lib/conceptql/{nodes/node.rb → operators/operator.rb}

@@ -1,27 +1,48 @@
 require 'zlib'
-require 'active_support/core_ext/hash'
+require_relative '../behaviors/metadatable'
+require 'facets/array/extract_options'
+require 'facets/hash/deep_rekey'
+require 'forwardable'
+
 module ConceptQL
-  module Nodes
-    class Node
+  module Operators
+    class Operator
+      extend Forwardable
+      extend Metadatable
       COLUMNS = [
         :person_id,
         :criterion_id,
         :criterion_type,
         :start_date,
         :end_date,
-        :value_as_numeric,
+        :value_as_number,
         :value_as_string,
-        :value_as_concept_id
+        :value_as_concept_id,
+        :units_source_value,
+        :source_value
       ]
-      attr :values, :options
-      attr_accessor :tree
+
+      attr :values, :options, :arguments, :upstreams
+
+      option :label, type: :string
+
       def initialize(*args)
-        args.flatten!
-        if args.last.is_a?(Hash)
-          @options = args.pop.symbolize_keys
-        end
-        @options ||= {}
-        @values = args.flatten
+        set_values(*args)
+      end
+
+      def values=(*args)
+        set_values(*args)
+      end
+
+      def set_values(*args)
+        @options = args.extract_options!.deep_rekey
+        @upstreams, @arguments = args.partition { |arg| arg.is_a?(Operator) }
+        @values = args
+      end
+
+      def scope=(scope)
+        @scope = scope
+        scope.add_operator(self)
       end
 
       def evaluate(db)
@@ -34,23 +55,19 @@ module ConceptQL
 
       def select_it(query, specific_type = nil)
         specific_type = type if specific_type.nil? && respond_to?(:type)
-        query.select(*columns(query, specific_type))
+        q = query.select(*columns(query, specific_type))
+        if scope && scope.person_ids && upstreams.empty?
+          q = q.where(person_id: scope.person_ids).from_self
+        end
+        q
       end
 
       def types
         @types ||= determine_types
       end
 
-      def children
-        @children ||= values.select { |v| v.is_a?(Node) }
-      end
-
       def stream
-        @stream ||= children.first
-      end
-
-      def arguments
-        @arguments ||= values.reject { |v| v.is_a?(Node) }
+        @stream ||= upstreams.first
       end
 
       def columns(query, local_type = nil)
@@ -62,25 +79,15 @@ module ConceptQL
                     type_id(local_type),
                     criterion_type]
         columns += date_columns(query, local_type)
-        columns += value_columns(query)
+        columns += value_columns(query, local_type)
+      end
+
+      def label
+        options[:label]
       end
 
       private
-      # There have been a few times now that I've wanted a node to be able
-      # to pass information to another node that is not directly a child
-      #
-      # Since tree is only object that touches each node in a statement,
-      # I'm going to employ tree as a way to communicate between nodes
-      #
-      # This is an ugly hack, but the use case for this hack is I'm changing
-      # the way `define` and `recall` nodes pass type information between
-      # each other.  They used to take the type information onto the
-      # database connection, but there were issues where sometimes the
-      # type information was needed before we passed around the database
-      # connection.
-      #
-      # At least this way we don't have timing issues when reading types
-      attr :tree
+      attr :scope
 
       def criterion_id
         :criterion_id
@@ -100,17 +107,19 @@ module ConceptQL
         "#{table}___tab".to_sym
       end
 
-      def value_columns(query)
+      def value_columns(query, type)
         [
           numeric_value(query),
           string_value(query),
-          concept_id_value(query)
+          concept_id_value(query),
+          units_source_value(query),
+          source_value(query, type)
         ]
       end
 
       def numeric_value(query)
-        return :value_as_numeric if query.columns.include?(:value_as_numeric)
-        Sequel.cast_numeric(nil, Float).as(:value_as_numeric)
+        return :value_as_number if query.columns.include?(:value_as_number)
+        Sequel.cast_numeric(nil, Float).as(:value_as_number)
       end
 
       def string_value(query)
@@ -123,13 +132,23 @@ module ConceptQL
         Sequel.cast_numeric(nil).as(:value_as_concept_id)
       end
 
+      def units_source_value(query)
+        return :units_source_value if query.columns.include?(:units_source_value)
+        Sequel.cast_string(nil).as(:units_source_value)
+      end
+
+      def source_value(query, type)
+        return :source_value if query.columns.include?(:source_value)
+        Sequel.cast_string(source_value_column(query, type)).as(:source_value)
+      end
+
       def date_columns(query, type = nil)
         return [:start_date, :end_date] if (query.columns.include?(:start_date) && query.columns.include?(:end_date))
         return [:start_date, :end_date] unless type
         sd = start_date_column(query, type)
         sd = Sequel.expr(sd).cast(:date).as(:start_date) unless sd == :start_date
         ed = end_date_column(query, type)
-        ed = Sequel.expr(ed).cast(:date).as(:end_date) unless ed == :end_date
+        ed = Sequel.function(:coalesce, Sequel.expr(ed).cast(:date), Sequel.expr(start_date_column(query, type))).as(:end_date) unless ed == :end_date
         [sd, ed]
       end
 
@@ -144,6 +163,7 @@ module ConceptQL
           procedure_occurrence: :procedure_date,
           procedure_cost: nil,
           observation: :observation_date,
+          observation_period: :observation_period_start_date,
           visit_occurrence: :visit_start_date
         }[type]
       end
@@ -159,10 +179,27 @@ module ConceptQL
           procedure_occurrence: :procedure_date,
           procedure_cost: nil,
           observation: :observation_date,
+          observation_period: :observation_period_end_date,
           visit_occurrence: :visit_end_date
         }[type]
       end
 
+      def source_value_column(query, type)
+        {
+          condition_occurrence: :condition_source_value,
+          death: :cause_of_death_source_value,
+          drug_exposure: :drug_source_value,
+          drug_cost: nil,
+          payer_plan_period: :payer_plan_period_source_value,
+          person: :person_source_value,
+          procedure_occurrence: :procedure_source_value,
+          procedure_cost: nil,
+          observation: :observation_source_value,
+          observation_period: nil,
+          visit_occurrence: :place_of_service_source_value
+        }[type]
+      end
+
       def person_date_of_birth(query)
         assemble_date(query, :year_of_birth, :month_of_birth, :day_of_birth)
       end
@@ -184,21 +221,16 @@ module ConceptQL
       end
 
       def determine_types
-        if children.empty?
+        if upstreams.empty?
           if respond_to?(:type)
             [type]
           else
-            raise "Node doesn't seem to specify any type"
+            raise "Operator doesn't seem to specify any type"
           end
         else
-          children.map(&:types).flatten.uniq
+          upstreams.map(&:types).flatten.uniq
         end
       end
-
-      def namify(name)
-        digest = Zlib.crc32 name
-        ('_' + digest.to_s).to_sym
-      end
     end
   end
 end

data/lib/conceptql/operators/overlapped_by.rb

@@ -0,0 +1,23 @@
+require_relative 'temporal_operator'
+
+module ConceptQL
+  module Operators
+    class OverlappedBy < TemporalOperator
+      desc <<-EOF
+Compares all results on a person-by-person basis between the left hand results (LHR) and the right hand resuls (RHR).
+For any result in the LHR whose start_date occurs between the start_date and end_date of a result from the RHR, that result is passed through.
+All other results are discarded, including all results in the RHR.
+L-------N-------L
+         R-----R
+  L-----Y----L
+      EOF
+      def where_clause
+        if inclusive?
+          [Proc.new { r__start_date <= l__start_date}, Proc.new { l__start_date <= r__end_date }]
+        else
+          [Proc.new { r__start_date <= l__start_date}, Proc.new { l__start_date <= r__end_date }, Proc.new { r__end_date <= l__end_date }]
+        end
+      end
+    end
+  end
+end

data/lib/conceptql/operators/overlaps.rb

@@ -0,0 +1,19 @@
+require_relative 'temporal_operator'
+
+module ConceptQL
+  module Operators
+    class Overlaps < TemporalOperator
+      desc <<-EOF
+Compares all results on a person-by-person basis between the left hand results (LHR) and the right hand resuls (RHR).
+For any result in the LHR whose end_date occurs between the start_date and end_date of a result from the RHR, that result is passed through.
+All other results are discarded, including all results in the RHR.
+L-------Y-------L
+            R-----R
+L-----N----L
+      EOF
+      def where_clause
+        [Proc.new { l__start_date <= r__start_date}, Proc.new { r__start_date <= l__end_date }, Proc.new { l__end_date <= r__end_date }]
+      end
+    end
+  end
+end

data/lib/conceptql/operators/pass_thru.rb

@@ -0,0 +1,11 @@
+require_relative 'operator'
+
+module ConceptQL
+  module Operators
+    class PassThru < Operator
+      def types
+        upstreams.map(&:types).flatten.uniq
+      end
+    end
+  end
+end

data/lib/conceptql/{nodes → operators}/person.rb

@@ -1,8 +1,12 @@
-require_relative 'casting_node'
+require_relative 'casting_operator'
 
 module ConceptQL
-  module Nodes
-    class Person < CastingNode
+  module Operators
+    class Person < CastingOperator
+      desc 'Returns all people in the database, or if given a upstream, converts all results to the set of patients contained in those results.'
+      allows_one_upstream
+      types :person
+
       def my_type
         :person
       end
@@ -16,7 +20,7 @@ module ConceptQL
         # when there is no explicit casting defined, is to convert everything to
         # person IDs
         #
-        # So by defining no known castable relationships in this node, all
+        # So by defining no known castable relationships in this operator, all
         # types will be converted to person
         []
       end

data/lib/conceptql/operators/person_filter.rb

@@ -0,0 +1,13 @@
+require_relative 'binary_operator_operator'
+
+module ConceptQL
+  module Operators
+    class PersonFilter < BinaryOperatorOperator
+      desc 'Only passes through a result from the LHR if the person appears in the RHR.'
+      def query(db)
+        db.from(left.evaluate(db))
+          .where(person_id: right.evaluate(db).select_group(:person_id))
+      end
+    end
+  end
+end

data/lib/conceptql/{nodes → operators}/place_of_service_code.rb

@@ -1,17 +1,17 @@
-require_relative 'node'
+require_relative 'operator'
 
 module ConceptQL
-  module Nodes
-    # Represents a node that will grab all person rows that match the given place_of_service_codes
+  module Operators
+    # Represents a operator that will grab all person rows that match the given place_of_service_codes
     #
     # PlaceOfServiceCode parameters are passed in as a set of strings.  Each string represents
     # a single place_of_service_code.  The place_of_service_code string must match one of the values in the
     # concept_name column of the concept table.  If you misspell the place_of_service_code name
     # you won't get any matches
-    class PlaceOfServiceCode < Node
-      def type
-        :visit_occurrence
-      end
+    class PlaceOfServiceCode < Operator
+      desc 'Finds all visit_occurrences that match the Place of Service codes'
+      argument :places_of_service, type: :codelist, vocab: 'Place of Service'
+      types :visit_occurrence
 
       def query(db)
         db.from(:visit_occurrence___v)

data/lib/conceptql/operators/procedure_occurrence.rb

@@ -0,0 +1,25 @@
+require_relative 'casting_operator'
+
+module ConceptQL
+  module Operators
+    class ProcedureOccurrence < CastingOperator
+      desc 'Generates all procedure_occurrence records, or, if fed a stream, fetches all procedure_occurrence records for the people represented in the incoming result set.'
+      types :procedure_occurrence
+      allows_one_upstream
+
+      def my_type
+        :procedure_occurrence
+      end
+
+      def i_point_at
+        [ :person ]
+      end
+
+      def these_point_at_me
+        %i[
+          procedure_cost
+        ]
+      end
+    end
+  end
+end

data/lib/conceptql/operators/prodcode.rb

@@ -0,0 +1,29 @@
+require_relative 'source_vocabulary_operator'
+
+module ConceptQL
+  module Operators
+    class Prodcode < SourceVocabularyOperator
+      desc 'Searches the drug_exposure table for all conditions with matching Prodcodes'
+      argument :prodcodes, type: :codelist, vocab_id: '203'
+      predominant_types :drug_exposure
+
+      def table
+        :drug_exposure
+      end
+
+      def vocabulary_id
+        200
+      end
+
+      def source_column
+        :drug_source_value
+      end
+
+      def concept_column
+        :drug_concept_id
+      end
+    end
+  end
+end
+
+

data/lib/conceptql/{nodes → operators}/race.rb

@@ -1,17 +1,17 @@
-require_relative 'node'
+require_relative 'operator'
 
 module ConceptQL
-  module Nodes
-    # Represents a node that will grab all person rows that match the given races
+  module Operators
+    # Represents a operator that will grab all person rows that match the given races
     #
     # Race parameters are passed in as a set of strings.  Each string represents
     # a single race.  The race string must match one of the values in the
     # concept_name column of the concept table.  If you misspell the race name
     # you won't get any matches
-    class Race < Node
-      def type
-        :person
-      end
+    class Race < Operator
+      desc 'Finds all people that match the races'
+      argument :races, type: :codelist, vocab: 'Race'
+      types :person
 
       def query(db)
         db.from(:person___p)

data/lib/conceptql/operators/recall.rb

@@ -0,0 +1,38 @@
+require_relative 'pass_thru'
+
+module ConceptQL
+  module Operators
+    # Mimics using a variable that has been set via "define" operator
+    #
+    # The idea is that a concept might be very complex and it helps to break
+    # that complex concept into a set of sub-concepts to better understand it.
+    #
+    # This operator will look for a sub-concept that has been created through the
+    # "define" operator and will fetch the results cached in the corresponding table
+    class Recall < Operator
+      desc <<-EOF
+Recalls a set of named results that were previously stored using the Define operator.
+Must be surrounded by the same Let operator as surrounds the corresponding Define operator.
+      EOF
+      argument :name, type: :string
+      category 'Variable Assignment'
+
+      def query(db)
+        scope.from(db, source)
+      end
+
+      def columns(query, local_type)
+        COLUMNS
+      end
+
+      def types
+        scope.types(source)
+      end
+
+      def source
+        arguments.first
+      end
+    end
+  end
+end
+

data/lib/conceptql/operators/rxnorm.rb

@@ -0,0 +1,24 @@
+require_relative 'standard_vocabulary_operator'
+
+module ConceptQL
+  module Operators
+    class Rxnorm < StandardVocabularyOperator
+      preferred_name 'RxNorm'
+      desc 'Finds all drug_exposures by RxNorm codes'
+      argument :rxnorms, type: :codelist, vocab: 'RxNorm'
+
+      def table
+        :drug_exposure
+      end
+
+      def vocabulary_id
+        8
+      end
+
+      def concept_column
+        :drug_concept_id
+      end
+    end
+  end
+end
+

data/lib/conceptql/operators/snomed.rb

@@ -0,0 +1,24 @@
+require_relative 'standard_vocabulary_operator'
+
+module ConceptQL
+  module Operators
+    class Snomed < StandardVocabularyOperator
+      preferred_name 'SNOMED'
+      desc 'Find all condition_occurrences by SNOMED codes'
+      argument :snomeds, type: :codelist, vocab: 'SNOMED'
+      predominant_types :condition_occurrence
+
+      def table
+        :condition_occurrence
+      end
+
+      def vocabulary_id
+        1
+      end
+
+      def concept_column
+        :condition_concept_id
+      end
+    end
+  end
+end

data/lib/conceptql/operators/snomed_condition.rb

@@ -0,0 +1,26 @@
+require_relative 'standard_vocabulary_operator'
+
+module ConceptQL
+  module Operators
+    class SnomedCondition < StandardVocabularyOperator
+      preferred_name 'SNOMED'
+      desc 'Find all condition_occurrences by SNOMED codes'
+      argument :snomeds, type: :codelist, vocab: 'SNOMED'
+      predominant_types :condition_occurrence
+
+      def table
+        :condition_occurrence
+      end
+
+      def vocabulary_id
+        1
+      end
+
+      def concept_column
+        :condition_concept_id
+      end
+    end
+  end
+end
+
+

data/lib/conceptql/{nodes/source_vocabulary_node.rb → operators/source_vocabulary_operator.rb}

@@ -1,8 +1,8 @@
-require_relative 'node'
+require_relative 'operator'
 
 module ConceptQL
-  module Nodes
-    # A SourceVocabularyNode is a superclass for a node that represents a criterion whose column stores information associated with a source vocabulary.
+  module Operators
+    # A SourceVocabularyOperator is a superclass for a operator that represents a criterion whose column stores information associated with a source vocabulary.
     #
     # If that seems confusing, then think of ICD-9 or NDC criteria.  That type of criterion takes a set of values that are mapped via the source_to_concept_map table into a standard vocabulary.
     #
@@ -25,7 +25,10 @@ module ConceptQL
     # * vocabulary_id
     #   * The vocabulary ID of the source vocabulary for the criterion
     #   * e.g. for ICD-9, a value of 2 (for ICD-9-CM)
-    class SourceVocabularyNode < Node
+    class SourceVocabularyOperator < Operator
+      category 'Source Vocabulary'
+      category 'Code Lists'
+
       def query(db)
         db.from(table_name)
           .join(:vocabulary__source_to_concept_map___scm, scm__target_concept_id: table_concept_column)

data/lib/conceptql/{nodes/standard_vocabulary_node.rb → operators/standard_vocabulary_operator.rb}

@@ -1,8 +1,8 @@
-require_relative 'node'
+require_relative 'operator'
 
 module ConceptQL
-  module Nodes
-    # A StandardVocabularyNode is a superclass for a node that represents a criterion whose column stores information associated with a standard vocabulary.
+  module Operators
+    # A StandardVocabularyOperator is a superclass for a operator that represents a criterion whose column stores information associated with a standard vocabulary.
     #
     # If that seems confusing, then think of CPT or SNOMED criteria.  That type of criterion takes a set of values that live in the OMOP concept table.
     #
@@ -18,7 +18,9 @@ module ConceptQL
     # * vocabulary_id
     #   * The vocabulary ID of the source vocabulary for the criterion
     #   * e.g. for CPT, a value of 4 (for CPT-4)
-    class StandardVocabularyNode < Node
+    class StandardVocabularyOperator < Operator
+      category 'Standard Vocabulary'
+      category 'Code Lists'
       def query(db)
         db.from(table_name)
           .join(:vocabulary__concept___c, c__concept_id: table_concept_column)

data/lib/conceptql/{nodes → operators}/started_by.rb

@@ -1,8 +1,14 @@
-require_relative 'temporal_node'
+require_relative 'temporal_operator'
 
 module ConceptQL
-  module Nodes
-    class StartedBy < TemporalNode
+  module Operators
+    class StartedBy < TemporalOperator
+      desc <<-EOF
+If LHR has the same start date as RHR, but LHR's end_date falls on or after end_date of RHR, LHR is passed through.
+L----Y----L
+R-------R
+L--N--L
+      EOF
       def where_clause
         [ { l__start_date: :r__start_date } ] + \
         if inclusive?