conceptql 0.6.0 → 0.7.0

data/lib/conceptql/diagram_renderer/tree_layout.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # A port of d3-hierarchy 3.1.2 (the version frontend/package-lock.json
+    # resolves): hierarchy() and tree(), the tidy tree layout of Buchheim, Jünger
+    # and Leipert (the linear-time version of Reingold-Tilford), as
+    # d3-hierarchy's src/tree.js implements it. Only the nodeSize mode is ported,
+    # because geometry.js uses only that mode.
+    #
+    # The arithmetic is the same as the JavaScript, in the same order and in
+    # Float (IEEE double, as JavaScript numbers), so the x values are the same
+    # to the last bit.
+    #
+    #   root = TreeLayout.hierarchy(data) { |d| d["children"] }
+    #   TreeLayout.new(node_size: [200, 140], separation: ->(_a, _b) { 1 }).call(root)
+    #   root.descendants.map { [it.x, it.y] }
+    class TreeLayout
+      # eachBefore and eachAfter, for Node and TreeNode (in tree.js, TreeNode
+      # inherits them from Node). Both need only `children`.
+      module Traversal
+        # Pre-order, children left to right (node.eachBefore).
+        def each_before
+          nodes = [ self ]
+          while (node = nodes.pop)
+            yield node
+            node.children&.reverse_each { nodes.push(_1) }
+          end
+          self
+        end
+
+        # Post-order, children left to right (node.eachAfter).
+        def each_after
+          nodes = [ self ]
+          after = []
+          while (node = nodes.pop)
+            after.push(node)
+            node.children&.each { nodes.push(_1) }
+          end
+          yield after.pop until after.empty?
+          self
+        end
+      end
+
+      # A node of the hierarchy (d3-hierarchy Node). `children` is nil for a
+      # leaf, as in d3: an empty child list makes no children.
+      class Node
+        include Traversal
+
+        attr_accessor :data, :depth, :height, :parent, :children, :x, :y, :data_index
+
+        def initialize(data)
+          @data = data
+          @depth = 0
+          @height = 0
+          @parent = nil
+          @children = nil
+        end
+
+        # Breadth-first, children left to right (node[Symbol.iterator] and
+        # node.descendants()).
+        def descendants
+          found = []
+          level = [ self ]
+          until level.empty?
+            found.concat(level)
+            level = level.flat_map { _1.children || [] }
+          end
+          found
+        end
+
+        # Every parent-child link, in descendants order (node.links()).
+        def links
+          descendants.drop(1).map { Link.new(_1.parent, _1) }
+        end
+      end
+
+      Link = Struct.new(:source, :target)
+
+      # d3.hierarchy(data, children): the block returns a datum's children.
+      def self.hierarchy(data, &children)
+        root = Node.new(data)
+        nodes = [ root ]
+        while (node = nodes.pop)
+          childs = children.call(node.data)
+          next if childs.nil? || childs.empty?
+
+          node.children = childs.map { Node.new(_1) }
+          node.children.reverse_each do |child|
+            nodes.push(child)
+            child.parent = node
+            child.depth = node.depth + 1
+          end
+        end
+        root.each_before { compute_height(_1) }
+      end
+
+      # computeHeight in hierarchy/index.js.
+      def self.compute_height(node)
+        height = 0
+        loop do
+          node.height = height
+          node = node.parent
+          height += 1
+          break unless node && node.height < height
+        end
+      end
+      private_class_method :compute_height
+
+      # TreeNode in tree.js: the layout's working state for one node.
+      #   z prelim, m mod, c change, s shift, t thread, a ancestor,
+      #   ancestor_default A, i number among its siblings.
+      class TreeNode
+        include Traversal
+
+        attr_accessor :node, :parent, :children, :ancestor_default, :a, :z, :m, :c, :s, :t, :i
+
+        def initialize(node, i)
+          @node = node
+          @parent = nil
+          @children = nil
+          @ancestor_default = nil
+          @a = self
+          @z = 0.0
+          @m = 0.0
+          @c = 0.0
+          @s = 0.0
+          @t = nil
+          @i = i
+        end
+      end
+
+      def initialize(node_size:, separation:)
+        @dx = Float(node_size[0])
+        @dy = Float(node_size[1])
+        @separation = separation
+      end
+
+      # tree(root): sets x and y on every node of the hierarchy and returns it.
+      def call(root)
+        t = tree_root(root)
+
+        t.each_after { first_walk(_1) }
+        t.parent.m = -t.z
+        t.each_before { second_walk(_1) }
+
+        root.each_before { size_node(_1) }
+        root
+      end
+
+      private
+
+      # treeRoot in tree.js.
+      def tree_root(root)
+        tree = TreeNode.new(root, 0)
+        nodes = [ tree ]
+        while (node = nodes.pop)
+          children = node.node.children
+          next unless children
+
+          node.children = Array.new(children.length)
+          (children.length - 1).downto(0) do |i|
+            child = node.children[i] = TreeNode.new(children[i], i)
+            nodes.push(child)
+            child.parent = node
+          end
+        end
+
+        tree.parent = TreeNode.new(nil, 0)
+        tree.parent.children = [ tree ]
+        tree
+      end
+
+      # The separation function, called with hierarchy nodes; Float like a
+      # JavaScript number.
+      def separation(a, b) = Float(@separation.call(a, b))
+
+      # nextLeft in tree.js.
+      def next_left(v) = v.children ? v.children[0] : v.t
+
+      # nextRight in tree.js.
+      def next_right(v) = v.children ? v.children[-1] : v.t
+
+      # moveSubtree in tree.js.
+      def move_subtree(wm, wp, shift)
+        change = shift / (wp.i - wm.i)
+        wp.c -= change
+        wp.s += shift
+        wm.c += change
+        wp.z += shift
+        wp.m += shift
+      end
+
+      # executeShifts in tree.js.
+      def execute_shifts(v)
+        shift = 0.0
+        change = 0.0
+        v.children.reverse_each do |w|
+          w.z += shift
+          w.m += shift
+          change += w.c
+          shift += w.s + change
+        end
+      end
+
+      # nextAncestor in tree.js.
+      def next_ancestor(vim, v, ancestor)
+        vim.a.parent.equal?(v.parent) ? vim.a : ancestor
+      end
+
+      # firstWalk in tree.js.
+      def first_walk(v)
+        children = v.children
+        siblings = v.parent.children
+        w = v.i.zero? ? nil : siblings[v.i - 1]
+        if children
+          execute_shifts(v)
+          midpoint = (children[0].z + children[-1].z) / 2
+          if w
+            v.z = w.z + separation(v.node, w.node)
+            v.m = v.z - midpoint
+          else
+            v.z = midpoint
+          end
+        elsif w
+          v.z = w.z + separation(v.node, w.node)
+        end
+        v.parent.ancestor_default = apportion(v, w, v.parent.ancestor_default || siblings[0])
+      end
+
+      # secondWalk in tree.js.
+      def second_walk(v)
+        v.node.x = v.z + v.parent.m
+        v.m += v.parent.m
+      end
+
+      # apportion in tree.js.
+      def apportion(v, w, ancestor)
+        return ancestor unless w
+
+        vip = v
+        vop = v
+        vim = w
+        vom = vip.parent.children[0]
+        sip = vip.m
+        sop = vop.m
+        sim = vim.m
+        som = vom.m
+        loop do
+          vim = next_right(vim)
+          vip = next_left(vip)
+          break unless vim && vip
+
+          vom = next_left(vom)
+          vop = next_right(vop)
+          vop.a = v
+          shift = vim.z + sim - vip.z - sip + separation(vim.node, vip.node)
+          if shift > 0
+            move_subtree(next_ancestor(vim, v, ancestor), v, shift)
+            sip += shift
+            sop += shift
+          end
+          sim += vim.m
+          sip += vip.m
+          som += vom.m
+          sop += vop.m
+        end
+        if vim && !next_right(vop)
+          vop.t = vim
+          vop.m += sim - sop
+        end
+        if vip && !next_left(vom)
+          vom.t = vip
+          vom.m += sip - som
+          ancestor = v
+        end
+        ancestor
+      end
+
+      # sizeNode in tree.js.
+      def size_node(node)
+        node.x *= @dx
+        node.y = node.depth * @dy
+      end
+    end
+  end
+end

data/lib/conceptql/diagram_renderer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "paths"
+
+module ConceptQL
+  # The ConceptQL diagram renderer: a diagram tree (ConceptQL::Diagram.render)
+  # to a standalone static SVG (render_static), a PNG (png) or the in-app SVG
+  # (render_app). See docs/diagram_renderer.md. It uses the Ruby standard
+  # library and the resvg program only. lib/conceptql.rb autoloads it, so
+  # `require "conceptql"` loads none of it, and a plain Ruby process can load
+  # it alone:
+  #
+  #   ruby -Ilib -e 'require "conceptql/diagram_renderer"; ConceptQL::DiagramRenderer::Geometry'
+  #
+  # It is a port of the JavaScript renderer of the Jigsaw diagram editor
+  # (frontend/lib/conceptql-diagram in the jigsaw-diagram-editor repository).
+  # The comments name the JavaScript files by their paths in that repository.
+  module DiagramRenderer
+    class << self
+      # The asset configuration (Configuration) that render_static and png use.
+      def configuration = @configuration ||= Configuration.new
+
+      # Replace the configuration with a new one that the block sets up.
+      def configure
+        config = Configuration.new
+        yield config
+        @configuration = config
+      end
+
+      # The standalone static SVG of a diagram tree (DiagramData.from takes the
+      # input), as text. show_counts labels each stream with its child's
+      # counts; show_options lists each node's options under its values.
+      def render_static(input, show_counts: false, show_options: false)
+        check_resvg_version
+        Static.new(configuration).render(input, show_counts:, show_options:)
+      end
+
+      # The static SVG rasterized by resvg, as PNG bytes, at the SVG's width and
+      # height.
+      def png(input, show_counts: false, show_options: false)
+        configuration.resvg.png(render_static(input, show_counts:, show_options:))
+      end
+
+      # The in-app SVG (App) of a diagram tree whose nodes have ids, as text:
+      # the svg.vis element of renderer.js, with click hooks and stable keys.
+      # Options: styles, icons, lock_nodes, summary, show_counts, show_options
+      # and css_transforms (see App#render and docs/diagram_renderer.md).
+      def render_app(tree, **options)
+        App.new(configuration).render(tree, **options)
+      end
+
+      private
+
+      # The first call in a process runs `resvg --version`. Another version
+      # than Resvg::VERSION can draw wrong diagrams, so it prints one warning
+      # to stderr and draws anyway. Later calls do not check again, even after
+      # configure. png calls render_static, so png checks too.
+      def check_resvg_version
+        return if @resvg_version_checked
+
+        @resvg_version_checked = true
+        found = configuration.resvg.version
+        return if found == Resvg::VERSION
+
+        warn "ConceptQL::DiagramRenderer: resvg #{found} is not the required version #{Resvg::VERSION}. The diagrams can be wrong."
+      end
+    end
+  end
+end
+
+require_relative "diagram_renderer/js_format"
+require_relative "diagram_renderer/tree_layout"
+require_relative "diagram_renderer/geometry"
+require_relative "diagram_renderer/resvg"
+require_relative "diagram_renderer/input_error"
+require_relative "diagram_renderer/diagram_data"
+require_relative "diagram_renderer/svg"
+require_relative "diagram_renderer/sprite"
+require_relative "diagram_renderer/configuration"
+require_relative "diagram_renderer/drawing"
+require_relative "diagram_renderer/static"
+require_relative "diagram_renderer/app"

data/lib/conceptql/lexicon/lexicon_strategy.rb

@@ -59,6 +59,22 @@ module ConceptQL
             "and #{(ids - declared).inspect} do not"
     end
 
+    # The [vocabulary_id, concept_code] pairs of the vocabularies' codes that
+    # equal one of the codes when case is ignored. Lexicon reads them to find
+    # a code given in another case than the stored one
+    # (CodeCaseMismatchError). A vocabulary that declares (?i:...) already
+    # compares without case, so it has none. A lexicon without a database has
+    # none either.
+    def case_variants(data_db, vocabulary_id, codes)
+      return [] if db.nil? || db_is_mock?(data_db) || case_insensitive?(vocabulary_id)
+
+      concepts_table(db)
+        .where(vocabulary_id: vocabulary_id)
+        .where(Sequel.function(:lower, :concept_code) => Array(codes).map { |code| code.to_s.downcase })
+        .distinct
+        .select_map(%i[vocabulary_id concept_code])
+    end
+
     def concepts_by_name(data_db, names = [])
       ds = concepts_table(data_db)
 

data/lib/conceptql/lexicon.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "forwardable"
+require_relative "code_case_mismatch_error"
 require_relative "lexicon/lexicon_gdm"
 require_relative "lexicon/lexicon_no_db"
 require_relative "lexicon/lexicon_ohdsi"
@@ -29,10 +30,8 @@ module ConceptQL
 
     def_delegators :@strategy,
                    :strategy,
-                   :concepts,
                    :concepts_table,
                    :concepts_by_name,
-                   :concepts_ds,
                    :vocabularies,
                    :vocabularies_query
 
@@ -187,40 +186,77 @@ module ConceptQL
       @cache = {} if cache
     end
 
-    (CACHED_LOOKUPS - %i[code_meanings concepts_to_codes concepts_to_codes_in_class known_codes table_is_missing?]).each do |name|
+    (CACHED_LOOKUPS - %i[code_meanings concept_ids concepts_to_codes concepts_to_codes_in_class known_codes
+                         table_is_missing?]).each do |name|
       define_method(name) do |*args|
         lookup(name, args) { @strategy.public_send(name, *args) }
       end
     end
 
+    # The lookups below take codes. Each one raises CodeCaseMismatchError for
+    # a code that matches no stored code exactly but matches one in another
+    # case (bead conceptql-rz8s). A vocabulary operator passes
+    # check_case: false, because a statement warns about such a code instead.
+
+    def concept_ids(data_db, vocabulary_id, codes = [], check_case: true)
+      ids = lookup(:concept_ids, [ data_db, vocabulary_id, codes ]) do
+        @strategy.concept_ids(data_db, vocabulary_id, codes)
+      end
+      check_case!(data_db, vocabulary_id, codes) if check_case
+      ids
+    end
+
+    # The datasets are not cached, but the check runs when they are built.
+    def concepts(data_db, vocabulary_id, codes = [], check_case: true)
+      ds = @strategy.concepts(data_db, vocabulary_id, codes)
+      check_case!(data_db, vocabulary_id, codes) if check_case
+      ds
+    end
+
+    def concepts_ds(data_db, vocabulary_id, codes, check_case: true)
+      ds = @strategy.concepts_ds(data_db, vocabulary_id, codes)
+      check_case!(data_db, vocabulary_id, codes) if check_case
+      ds
+    end
+
     # The strategy's known_codes first asks whether the vocabulary is empty.
     # It asks through the block, so that question also reaches the cache.
-    def known_codes(data_db, vocabulary_id, codes)
-      lookup(:known_codes, [ data_db, vocabulary_id, codes ]) do
+    def known_codes(data_db, vocabulary_id, codes, check_case: true)
+      known = lookup(:known_codes, [ data_db, vocabulary_id, codes ]) do
         @strategy.known_codes(data_db, vocabulary_id, codes) { vocabulary_is_empty?(data_db, vocabulary_id) }
       end
+      check_case!(data_db, vocabulary_id, Array(codes) - known) if check_case
+      known
     end
 
     # The strategy's concepts_to_codes first asks whether the concept table is
     # missing. It asks through the block, so that question also reaches the cache.
-    def concepts_to_codes(data_db, vocabulary_id, codes = [])
-      lookup(:concepts_to_codes, [ data_db, vocabulary_id, codes ]) do
+    def concepts_to_codes(data_db, vocabulary_id, codes = [], check_case: true)
+      found = lookup(:concepts_to_codes, [ data_db, vocabulary_id, codes ]) do
         @strategy.concepts_to_codes(data_db, vocabulary_id, codes) { table_is_missing?(data_db) }
       end
+      check_case!(data_db, vocabulary_id, Array(codes) - found.map(&:first)) if check_case
+      found
     end
 
     # Like concepts_to_codes, it asks about the concept table through the block.
-    def concepts_to_codes_in_class(data_db, vocabulary_id, concept_class_id, codes)
-      lookup(:concepts_to_codes_in_class, [ data_db, vocabulary_id, concept_class_id, codes ]) do
+    # A code of the vocabulary that is in another class is not in the answer,
+    # so the check finds it in its own case and does not raise.
+    def concepts_to_codes_in_class(data_db, vocabulary_id, concept_class_id, codes, check_case: true)
+      found = lookup(:concepts_to_codes_in_class, [ data_db, vocabulary_id, concept_class_id, codes ]) do
         @strategy.concepts_to_codes_in_class(data_db, vocabulary_id, concept_class_id, codes) { table_is_missing?(data_db) }
       end
+      check_case!(data_db, vocabulary_id, Array(codes) - Array(found).map(&:first)) if check_case
+      found
     end
 
     # Like concepts_to_codes, it asks about the concept table through the block.
-    def code_meanings(data_db, vocabulary_id, codes)
-      lookup(:code_meanings, [ data_db, vocabulary_id, codes ]) do
+    def code_meanings(data_db, vocabulary_id, codes, check_case: true)
+      meanings = lookup(:code_meanings, [ data_db, vocabulary_id, codes ]) do
         @strategy.code_meanings(data_db, vocabulary_id, codes) { table_is_missing?(data_db) }
       end
+      check_case!(data_db, vocabulary_id, codes) if check_case
+      meanings
     end
 
     # Only "the table is there" is kept. A missing table (or a database error,
@@ -232,6 +268,22 @@ module ConceptQL
       end
     end
 
+    # Raises CodeCaseMismatchError when a code matches no stored code of the
+    # vocabularies exactly, but matches one in another case. The caller passes
+    # only the codes that its lookup did not find, when it can tell. A strategy
+    # without case_variants (a test double) cannot check.
+    def check_case!(data_db, vocabulary_id, codes)
+      codes = Array(codes)
+      return if codes.empty? || !@strategy.respond_to?(:case_variants)
+
+      rows = lookup(:case_variants, [ data_db, vocabulary_id, codes ]) do
+        @strategy.case_variants(data_db, vocabulary_id, codes)
+      end
+      mismatches = CodeCaseMismatchError.mismatches(codes, rows)
+      raise CodeCaseMismatchError, mismatches unless mismatches.empty?
+    end
+    private :check_case!
+
     # Runs the lookup, or with caching on returns the result kept for the same
     # method and arguments. A result that keep rejects is returned, not kept.
     def lookup(name, args, keep: nil)

data/lib/conceptql/nodifier.rb

@@ -42,10 +42,12 @@ module ConceptQL
       end
     end
 
+    # The metadata of each operator that is not hidden, sorted by name
     def to_metadata(opts = {})
-      Hash[operators.map do |k, v|
-        [ k, v.to_metadata(k, opts) ]
-      end.reject { |_k, v| v[:categories].empty? }.sort_by { |_k, v| v[:name] }]
+      operators.reject { |_name, klass| klass.hidden? }
+               .map { |name, klass| [ name, klass.to_metadata(name, opts) ] }
+               .sort_by { |_name, metadata| metadata[:name] }
+               .to_h
     end
 
     # The operators this nodifier can create: its Database's registry for

data/lib/conceptql/operators/after.rb

@@ -7,9 +7,23 @@ module ConceptQL
     class After < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records with a start_date that occurs after the earliest end_date of a right hand record."
+      desc "For each patient, keeps the left-hand records whose start_date is after the earliest end_date of the patient's right-hand records. With the within option, each left-hand record is compared with every right-hand record of the patient instead."
+      returns "The left-hand records that start after a right-hand record of the same patient ends, each record once. The right-hand records are not returned."
 
       allows_at_least_option
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. The left-hand record must also start no more than this amount after the end_date of the right-hand record. With this option, each left-hand record is compared with every right-hand record of the patient, not only with the one that ends first. Use a positive amount."
+      option_meaning :at_least, "A date adjustment, such as 7d or 1w. The left-hand record must start more than this amount after the end_date of the right-hand record. Use a positive amount."
+
+      example "All MIs that occurred after a patient's first case of diabetes (250.01)",
+              [ "after", { left: [ "icd9", "412" ], right: [ "icd9", "250.01" ] } ]
+      example "Prescriptions of interest within three days after an office visit",
+              [ "after", { left: [ "ndc", "61392070054", "65084025214", "65726040125", { label: "Prescriptions of Interest" } ],
+                           right: [ "cpt", "99214", { label: "Office Visit" } ], within: "3d" } ]
+      example "Heart attack diagnoses more than 1 week after a diagnosis of diabetes",
+              [ "after", { left: [ "icd9", "410.00", "410.01", "410.10", "410.11", { label: "Heart Attack Dx" } ],
+                           right: [ "icd9", "250.01", { label: "Diabetes Dx" } ], at_least: "1w" } ]
+      example "All MIs that occurred after a male patient's 50th birthday",
+              [ "after", { left: [ "icd9", "412" ], right: [ "time_window", [ "gender", "Male" ], { start: "50y", end: "50y" } ] } ]
       within_skip :after
 
       def right_stream_query(db)

data/lib/conceptql/operators/any_overlap.rb

@@ -7,7 +7,12 @@ module ConceptQL
     class AnyOverlap < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records with a date range that overlaps in any way with a right hand record's date_range."
+      desc "For each patient, keeps the left-hand records whose date range shares at least one day with the date range of a right-hand record."
+      returns "The left-hand records that overlap the date range of at least one right-hand record of the same patient, each record once. The right-hand records are not returned."
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. Before the comparison, the date range of each right-hand record is widened by this amount in each direction: its start_date moves back and its end_date moves forward. Use a positive amount."
+
+      example "All MIs that overlap with the month of 2010-06",
+              [ "any_overlap", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-06-01", end: "2010-06-30" } ] } ]
 
       def where_clause
         ((within_start <= l_start_date) & (l_start_date <= within_end)) | ((l_start_date <= within_start) & (within_start <= l_end_date))

data/lib/conceptql/operators/before.rb

@@ -7,9 +7,19 @@ module ConceptQL
     class Before < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records with an end_date that occurs before the most recent start_date of a right hand record."
+      desc "For each patient, keeps the left-hand records whose end_date is before the latest start_date of the patient's right-hand records. With the within option, each left-hand record is compared with every right-hand record of the patient instead."
+      returns "The left-hand records that end before a right-hand record of the same patient starts, each record once. The right-hand records are not returned."
 
       allows_at_least_option
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. The left-hand record must also end no more than this amount before the start_date of the right-hand record. With this option, each left-hand record is compared with every right-hand record of the patient, not only with the one that starts last. Use a positive amount."
+      option_meaning :at_least, "A date adjustment, such as 7d or 1w. The left-hand record must end more than this amount before the start_date of the right-hand record. Use a positive amount."
+
+      example "All MIs that occurred before a patient's last case of diabetes (250.01)",
+              [ "before", { left: [ "icd9", "412" ], right: [ "icd9", "250.01" ] } ]
+      example "All MIs that occurred before a patient's first case of diabetes (250.01)",
+              [ "before", { left: [ "icd9", "412" ], right: [ "first", [ "icd9", "250.01" ] ] } ]
+      example "Heart attacks that end no more than 1 year before death",
+              [ "before", { left: [ "icd9", "410.00", "410.01", "410.10", "410.11" ], right: [ "death" ], within: "1y" } ]
       within_skip :before
 
       def right_stream_query(db)

data/lib/conceptql/operators/binary_operator_operator.rb

@@ -6,8 +6,13 @@ module ConceptQL
   module Operators
     # Base class for all operators that take two streams, a left-hand and a right-hand
     class BinaryOperatorOperator < Operator
-      option :left, type: :upstream
-      option :right, type: :upstream
+      option :left, type: :upstream,
+                    meaning: "The left-hand stream. The operator compares these records with the right-hand stream and passes on the ones that meet its condition."
+      option :right, type: :upstream,
+                     meaning: "The right-hand stream. The operator compares the left-hand records with these records and does not pass them on."
+      # The operands are the left and right options. A positional upstream
+      # would be ignored, so it is an error (Ryan ruled 2026-11-03).
+      validate_no_upstreams
       validate_no_arguments
       validate_option Array, :left, :right
       validate_required_options :left, :right
@@ -68,6 +73,11 @@ module ConceptQL
         @right = to_op(options[:right])  if options[:right].is_a?(Array)
       end
 
+      # create_upstreams leaves the positional upstreams as statements
+      def upstream_operator_names
+        @upstreams.map { |stmt| stmt.is_a?(Operator) ? stmt.op_name : stmt.first }
+      end
+
       def left_stream(db)
         left_stream_query(db)
       end

data/lib/conceptql/operators/co_reported.rb

@@ -17,10 +17,15 @@ module ConceptQL
         vocabularies.length > 1
       end
 
-      desc "Passes along the events of its upstream streams that were reported in the same source record " \
-           "(the same context). A record is kept only if every upstream stream " \
-           "has at least one event in it. If any one upstream has no event in a record, the events of all " \
-           "streams in that record are dropped, without a warning."
+      desc "Passes along the records of its upstreams that were reported in the same context as a record of every other upstream. " \
+           "In the GDM, a context is the claim or other source record that reported the record."
+
+      returns "The records of each upstream whose context also has a record of every other upstream. " \
+              "The operator does not compare dates. If one upstream has no record in a context, the records of all upstreams " \
+              "in that context are not passed along. Person and death records have no context, so they never pass."
+
+      example "Diabetes diagnoses reported as a reason for an office visit, and those office visits",
+              [ "co_reported", [ "icd9", "250.00" ], [ "cpt", "99214" ] ]
 
       allows_many_upstreams
       category "Combine Streams"

data/lib/conceptql/operators/contains.rb

@@ -7,7 +7,12 @@ module ConceptQL
     class Contains < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records with a start_date and end_date containing a right hand record's start_date and end_date."
+      desc "For each patient, keeps the left-hand records whose date range encloses the date range of a right-hand record. The left-hand record starts on or before the start_date of the right-hand record and ends on or after its end_date."
+      returns "The left-hand records that enclose the date range of at least one right-hand record of the same patient, each record once. The right-hand records are not returned."
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. Before the comparison, the date range of each left-hand record is widened by this amount in each direction: its start_date moves back and its end_date moves forward. The returned records keep their own dates. Use a positive amount."
+
+      example "All MIs occurring on 2010-06-22",
+              [ "contains", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-06-22", end: "2010-06-22" } ] } ]
 
       def where_clause
         (within_start <= r_start_date) & (r_end_date <= within_end)