conceptql 0.6.0 → 0.7.0

data/lib/conceptql/operators/count.rb

@@ -6,6 +6,8 @@ module ConceptQL
   module Operators
     class Count < PassThru
       register __FILE__
+      hidden
+      category "Modify Data"
 
       desc "Counts the number of records that exactly match across all columns."
       # Every stream is a set, so count returns 1 for nearly every row

data/lib/conceptql/operators/date_range.rb

@@ -18,9 +18,21 @@ module ConceptQL
 
       DATE_FORMAT = /\A#{Regexp.union([ /START/i, /END/i, /\d{4}-\d{2}-\d{2}/ ])}\z/.freeze
 
-      desc "Creates a set of all person records with the given start_date and end_date."
-      option :start, type: :string
-      option :end, type: :string
+      desc "Makes one person record for each patient, with the given start_date and end_date. " \
+           "Use it to compare other records with a fixed range of dates."
+      option :start, type: :string,
+                     meaning: "The start_date of each record. It is a date in YYYY-MM-DD format, START or END. " \
+                              "START is the earliest start date of any information period in the database, " \
+                              "and END is the latest end date. START and END are not case-sensitive."
+      option :end, type: :string,
+                   meaning: "The end_date of each record. It is a date in YYYY-MM-DD format, START or END. " \
+                            "START is the earliest start date of any information period in the database, " \
+                            "and END is the latest end date. START and END are not case-sensitive. " \
+                            "For a single day, give the same date as the start option."
+      returns "One record for each patient. The type of the records is person, " \
+              "and each record has the start_date and the end_date that the options give."
+      example "Each patient, with the dates of the year 2010", [ "date_range", { "start" => "2010-01-01", "end" => "2010-12-31" } ]
+      example "Each patient, with the dates from the start to the end of the data", [ "date_range", { "start" => "START", "end" => "END" } ]
       category "Select by Property"
       basic_type :selection
       validate_no_upstreams

data/lib/conceptql/operators/death.rb

@@ -9,7 +9,11 @@ module ConceptQL
 
       register __FILE__
 
-      desc "Selects all death records. With an upstream stream, the operator selects the death record of each person in that stream."
+      desc "Selects every death record. With one upstream operator, it selects the deaths of the patients who have a record in the upstream stream."
+      returns "One record for each selected death, from the deaths table. The type of the records is death, " \
+              "and their start_date and end_date are both the date of death."
+      example "All death records", [ "death" ]
+      example "The deaths of the patients with an old myocardial infarction (ICD-9-CM 412)", [ "death", [ "icd9cm", "412" ] ]
       domains :death
       allows_one_upstream
 

data/lib/conceptql/operators/dedup.rb

@@ -6,6 +6,8 @@ module ConceptQL
   module Operators
     class Dedup < PassThru
       register __FILE__
+      hidden
+      category "Filter Single Stream"
 
       desc "Passes along each distinct record once. Records that have the same value in every column become one record."
       allows_one_upstream

data/lib/conceptql/operators/during.rb

@@ -7,7 +7,12 @@ module ConceptQL
     class During < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records with a start_date and end_date within a right hand record's start_date and end_date."
+      desc "For each patient, keeps the left-hand records whose date range is inside the date range of a right-hand record. The left-hand record starts on or after the start_date of the right-hand record and ends on or before its end_date."
+      returns "The left-hand records that are inside 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 for the year 2010",
+              [ "during", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-01-01", end: "2010-12-31" } ] } ]
 
       def where_clause
         (within_start <= l_start_date) & (l_end_date <= within_end)

data/lib/conceptql/operators/episode.rb

@@ -7,12 +7,23 @@ module ConceptQL
     class Episode < PassThru
       register __FILE__
 
-      desc "Groups each person's records into episodes, allowing for a gap between the end_date of one record and the start_date of the next."
+      desc "Merges each patient's records into episodes: spans of time in which the records are close together. " \
+           "For example, it can turn a set of prescriptions into the spans of time in which a patient takes a drug."
+      returns "One record for each episode. Its start_date is the earliest start_date in the episode, " \
+              "and its end_date is the latest end_date. Its criterion_table and criterion_domain are episode, " \
+              "and its criterion_id is 0, because an episode merges several records."
+      example "Episodes of diabetes diagnoses", [ "episode", [ "icd9", "250.00" ], { "gap_of" => "90" } ]
 
       allows_one_upstream
       validate_one_upstream
       option :gap_of, type: :integer,
-                      instructions: "Allowed gap in days between end date of one event and start date of the next to consider them the same episode"
+                      instructions: "Enter a number of days. A record stays in the current episode when it starts no more than this many days after the latest end date of the earlier records. The default is 0.",
+                      meaning: "The largest gap in days that stays in the same episode. The operator orders each " \
+                               "patient's records by start_date and then by end_date. A record stays in the current " \
+                               "episode when its start_date is no more than this many days after the latest end_date " \
+                               "of the earlier records, not only of the record just before. Otherwise it starts a " \
+                               "new episode. A record without an end_date counts as ending on its start_date. " \
+                               "The default is 0."
       category "Modify Data"
       basic_type :temporal
 

data/lib/conceptql/operators/equal.rb

@@ -7,10 +7,20 @@ module ConceptQL
     class Equal < TemporalOperator
       register __FILE__
 
-      desc "For each person, passes along left hand records that have the same value_as_number as a right hand record."
+      desc "For each patient, keeps the left-hand records whose value_as_number equals the value_as_number of a right-hand record. It does not compare dates."
+      returns "The left-hand records that have a right-hand record of the same patient with the same value_as_number, each record once. Left-hand records without a value_as_number (NULL) are not returned. The right-hand records are not returned."
+
+      # The test data has only one record with a value_as_number, so this
+      # example returns no rows there and stays out of the help.
+      example "HbA1c results (LOINC 4548-4) with the same value as an HbA1c result by HPLC (LOINC 17856-6) of the same patient",
+              [ "equal", { left: [ "loinc", "4548-4" ], right: [ "loinc", "17856-6" ] } ], help: false
 
       require_column :value_as_number
 
+      # Equal compares only value_as_number, so the within option that it
+      # inherits from TemporalOperator would have no effect (seed conceptql-ufn)
+      unsupported_options :within
+
       def where_clause
         { Sequel[:r][:value_as_number] => Sequel[:l][:value_as_number] }
       end

data/lib/conceptql/operators/ethnicity.rb

@@ -7,11 +7,19 @@ module ConceptQL
     class Ethnicity < Operator
       register __FILE__
 
-      desc "Selects person records that match the given set of Ethnicity codes."
+      desc "Selects the patients with the given ethnicities."
       domains :person
       category "Select by Property"
       basic_type :selection
-      argument :ethnicity, type: :string, options: [ "Hispanic or Latino", "Not Hispanic or Latino" ]
+      argument :ethnicity, type: :string, options: [ "Hispanic or Latino", "Not Hispanic or Latino" ],
+                           meaning: "One or more ethnicities. A value that starts with Hispanic selects the " \
+                                    "Hispanic or Latino patients, and a value that starts with Not Hispanic selects " \
+                                    "the patients who are not Hispanic or Latino. A value that contains Unknown " \
+                                    "selects the patients who have no ethnicity or ethnicity concept ID 0. Case does not matter, " \
+                                    "and any other value selects no patients."
+      returns "One person record for each patient whose ethnicity is one of the given ethnicities. " \
+              "The start_date and the end_date of each record are the patient's birth date."
+      example "All patients recorded as Hispanic", [ "ethnicity", "Hispanic" ]
       validate_no_upstreams
       validate_at_least_one_argument
 
@@ -24,21 +32,25 @@ module ConceptQL
       end
 
       def query(db)
-        db.from(source_table)
-          .where(ethnicity_concept_id: ethnicity_concept_ids)
+        ids = ethnicity_concept_ids
+        condition = Sequel.expr(ethnicity_concept_id: ids)
+        # Unknown (ID 0) also means no ethnicity, and IN never matches NULL.
+        condition = Sequel.|(condition, { ethnicity_concept_id: nil }) if ids.include?(0)
+
+        db.from(source_table).where(condition)
       end
 
       def ethnicity_concept_ids
-        arguments.map do |words|
+        arguments.filter_map do |words|
           case words
           when /^Not Hispanic/i
             38_003_564
           when /^Hispanic/i
             38_003_563
           when /unknown/i
-            [ 0, nil ]
+            0
           end
-        end.flatten
+        end
       end
     end
   end

data/lib/conceptql/operators/except.rb

@@ -7,7 +7,16 @@ module ConceptQL
     class Except < BinaryOperatorOperator
       register __FILE__
 
-      desc "Removes all incoming records that appear in the right hand set of records."
+      desc "Removes each left-hand record that also appears in the right-hand stream. Two records are the same when they have the same criterion_table, criterion_id, start_date and end_date."
+      returns "The left-hand records that have no right-hand record with the same criterion_table, criterion_id, start_date and end_date. A left-hand record whose table has no right-hand record passes through unchanged. The right-hand records are not returned."
+      option_meaning :right, "The right-hand stream. The operator removes each left-hand record that is also in this stream, and does not pass these records on."
+
+      example "All males who are not white",
+              [ "except", { left: [ "gender", "male" ], right: [ "race", "white" ] } ]
+      example "All Conditions that are MI",
+              [ "except", { left: [ "icd9", "412" ], right: [ "cpt", "99214" ] } ]
+      example "Passes two types downstream: Conditions that are MI (unaffected by the right-hand stream) and People that are Male but not White",
+              [ "except", { left: [ "union", [ "icd9", "412" ], [ "gender", "Male" ] ], right: [ "race", "White" ] } ]
       default_query_columns
 
       # An `as` option would cast both streams before the comparison. Except

data/lib/conceptql/operators/filter.rb

@@ -7,7 +7,12 @@ module ConceptQL
     class Filter < BinaryOperatorOperator
       register __FILE__
 
-      desc "Keeps left hand records that share the same person, criterion_id, criterion_table, and criterion_domain with a right hand side record."
+      desc "Keeps each left-hand record that also appears in the right-hand stream. Two records are the same when they have the same person_id, criterion_id, criterion_table, criterion_domain, start_date and end_date."
+      returns "The left-hand records that have a right-hand record with the same person_id, criterion_id, criterion_table, criterion_domain, start_date and end_date. The right-hand records are not returned."
+      option_meaning :right, "The right-hand stream. The operator keeps each left-hand record that is also in this stream, and does not pass these records on."
+
+      example "MIs that are a patient's first diagnosis of MI or diabetes",
+              [ "filter", { left: [ "icd9", "412" ], right: [ "first", [ "union", [ "icd9", "412" ], [ "icd9", "250.01" ] ] ] } ]
       default_query_columns
 
       # An `as` option would cast both streams before the comparison. Filter

data/lib/conceptql/operators/first.rb

@@ -6,13 +6,15 @@ module ConceptQL
   module Operators
     # Represents a operator that will grab the first occurrence of something
     #
-    # The operator treats all streams as a single, large stream.  It partitions
-    # that larget stream by person_id, then sorts within those groupings
-    # by start_date and then select at most one row per person, regardless
-    # of how many different types of streams enter the operator
+    # The operator takes exactly one upstream. It partitions the records of
+    # that upstream by person_id, sorts the records of each person by
+    # start_date, and selects at most one row per person, even when the
+    # upstream mixes records from several criterion tables
     #
-    # If two rows have the same start_date, the order of their ranking
-    # is arbitrary
+    # If two rows have the same start_date, the row with the lowest
+    # criterion_id comes first. criterion_id is unique within one
+    # criterion_table, so only rows from two different tables with the same
+    # id and start_date still rank in arbitrary order
     #
     # If we ask for the first occurrence of something and a person has no
     # occurrences, this operator returns nothing for that person
@@ -21,9 +23,17 @@ module ConceptQL
 
       desc "For each person, passes along the record with the earliest start_date."
 
-      # With either option, Occurrence's timed query returns every upstream
-      # row instead of one row per person
-      unsupported_options :at_least, :within
+      returns "One record per person: the upstream record with the earliest start_date. " \
+              "When several records have that start_date, the one with the lowest criterion_id."
+
+      example "For each patient, select the Condition that represents the first occurrence of an MI",
+              [ "first", [ "icd9", "412" ] ]
+
+      # With at_least or within, Occurrence's timed query returns every
+      # upstream row instead of one row per person. group_by_date does not
+      # change the result, because first passes along one record of the
+      # earliest date either way (seed conceptql-ufn).
+      unsupported_options :at_least, :within, :group_by_date
 
       def occurrence
         1

data/lib/conceptql/operators/from.rb

@@ -7,6 +7,9 @@ module ConceptQL
       include ConceptQL::Behaviors::Timeless
 
       register __FILE__
+      # Reads a raw table. It is not a public operator.
+      hidden
+      category "Select by Property"
       basic_type :selection
       no_desc
       option :domains, type: Array

data/lib/conceptql/operators/gender.rb

@@ -10,8 +10,16 @@ module ConceptQL
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::Timeless
 
-      desc "Selects all person records that match the selected gender."
-      argument :gender, type: :string, options: %w[Male Female Unknown]
+      desc "Selects the patients with the given genders."
+      argument :gender, type: :string, options: %w[Male Female Unknown],
+                        meaning: "One or more genders. A value that starts with M selects the male patients, " \
+                                 "and a value that starts with F selects the female patients. " \
+                                 "Any other value, such as Unknown, selects the patients whose gender is " \
+                                 "neither male nor female, including the patients with no gender. Case does not matter."
+      returns "One person record for each patient whose gender is one of the given genders. " \
+              "The start_date and the end_date of each record are the patient's birth date."
+      example "All female patients", [ "gender", "Female" ]
+      example "All male patients", [ "gender", "Male" ]
       domains :person
       category "Select by Property"
       basic_type :selection

data/lib/conceptql/operators/hospice.rb

@@ -8,7 +8,13 @@ module ConceptQL
       register __FILE__
       include ConceptQL::Behaviors::Utilizable
 
-      desc "Selects hospice admission records."
+      desc "Selects hospice admissions: one record for each admission whose claim came from a hospice file."
+      returns "One record for each hospice admission. The type of the records is condition_occurrence, " \
+              "and their criterion_table is collections, the table of claims. Their start_date and end_date " \
+              "are the dates of the claim, and source_value holds the primary code of the admission when it has one. " \
+              "Each record also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
+      # The test data has no hospice claims
+      example "All hospice admissions", [ "hospice" ], help: false
 
       def collection_type
         "hospice"

data/lib/conceptql/operators/hospitalization.rb

@@ -8,7 +8,12 @@ module ConceptQL
       register __FILE__
       include ConceptQL::Behaviors::Utilizable
 
-      desc "Selects inpatient admission records."
+      desc "Selects inpatient hospital admissions: one record for each admission whose claim came from an inpatient file."
+      returns "One record for each inpatient admission. The type of the records is condition_occurrence, " \
+              "and their criterion_table is collections, the table of claims. Their start_date and end_date " \
+              "are the dates of the claim, and source_value holds the primary code of the admission when it has one. " \
+              "Each record also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
+      example "All inpatient hospital admissions", [ "hospitalization" ]
 
       def collection_type
         "inpatient"

data/lib/conceptql/operators/information_periods.rb

@@ -10,10 +10,18 @@ module ConceptQL
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::Timeless
 
-      desc "Selects all information period records, which have the observation_period domain. " \
-           "The operator takes no upstream stream. " \
-           "Each argument is an information type concept ID, and with arguments, " \
-           "the operator selects only the information periods of those types."
+      desc "Selects information periods: the spans of time in which the data has information about a patient, " \
+           "such as periods of insurance enrollment."
+      argument :information_types, label: "Information Types", type: :codelist,
+                                   meaning: "Zero or more information types, each as a concept ID (an integer) " \
+                                            "or a concept code of the GDM_INFORMATION_TYPE vocabulary, such as PARTD (Medicare Part D). " \
+                                            "A statement may mix both. " \
+                                            "With no information types, the operator selects every information period. " \
+                                            "With information types, it selects only the information periods whose type is one of them. " \
+                                            "An unknown code gets a warning and selects no period."
+      returns "One record for each selected information period, from the information_periods table. " \
+              "The type of the records is observation_period."
+      example "All information periods", [ "information_periods" ]
       domains :observation_period
       category "Get Related Data"
       basic_type :selection
@@ -21,7 +29,8 @@ module ConceptQL
 
       def query(db)
         ds = db[source_table]
-        ds = ds.where(where_clause) if where_clause
+        clause = dm.information_period_where_clause(db, arguments)
+        ds = ds.where(clause) if clause
         ds
       end
 
@@ -29,8 +38,18 @@ module ConceptQL
         dm.table_by_domain(domain)
       end
 
-      def where_clause
-        dm.information_period_where_clause(arguments)
+      private
+
+      # A code that names no concept selects no period. A code is known only
+      # in its own case, as the lookup finds it.
+      def additional_validation(db, opts = {})
+        return unless add_warnings?(db, opts)
+
+        codes = dm.information_type_codes(arguments)
+        return if codes.empty?
+
+        unknown = codes - dm.known_codes(db, dm.information_types_vocab, codes, check_case: false)
+        add_warning(UNKNOWN_CODE, *unknown) unless unknown.empty?
       end
     end
   end

data/lib/conceptql/operators/invalid.rb

@@ -5,6 +5,10 @@ module ConceptQL
     class Invalid < Operator
       register __FILE__
 
+      # Stands in for an operator that did not resolve, so no user picks it
+      hidden
+      category "Select by Clinical Codes"
+
       no_desc
       default_query_columns
 

data/lib/conceptql/operators/last.rb

@@ -6,13 +6,15 @@ module ConceptQL
   module Operators
     # Represents a operator that will grab the last occurrence of something
     #
-    # The operator treats all streams as a single, large stream.  It partitions
-    # that larget stream by person_id, then sorts within those groupings
-    # by start_date and then select at most one row per person, regardless
-    # of how many different types of streams enter the operator
+    # The operator takes exactly one upstream. It partitions the records of
+    # that upstream by person_id, sorts the records of each person by
+    # start_date, and selects at most one row per person, even when the
+    # upstream mixes records from several criterion tables
     #
-    # If two rows have the same start_date, the order of their ranking
-    # is arbitrary
+    # If two rows have the same start_date, the row with the highest
+    # criterion_id comes first. criterion_id is unique within one
+    # criterion_table, so only rows from two different tables with the same
+    # id and start_date still rank in arbitrary order
     #
     # If we ask for the last occurrence of something and a person has no
     # occurrences, this operator returns nothing for that person
@@ -21,9 +23,17 @@ module ConceptQL
 
       desc "For each person, passes along the record with the most recent start_date."
 
-      # With either option, Occurrence's timed query returns every upstream
-      # row instead of one row per person
-      unsupported_options :at_least, :within
+      returns "One record per person: the upstream record with the latest start_date. " \
+              "When several records have that start_date, the one with the highest criterion_id."
+
+      example "For each patient, select the Condition that represents the last occurrence of an MI",
+              [ "last", [ "icd9", "412" ] ]
+
+      # With at_least or within, Occurrence's timed query returns every
+      # upstream row instead of one row per person. group_by_date does not
+      # change the result, because last passes along one record of the
+      # latest date either way (seed conceptql-ufn).
+      unsupported_options :at_least, :within, :group_by_date
 
       def occurrence
         -1

data/lib/conceptql/operators/match.rb

@@ -9,7 +9,12 @@ module ConceptQL
     class Match < BinaryOperatorOperator
       register __FILE__
 
-      desc "Keeps left hand records that have the same values as a right hand side record. By default, every column is compared. only_columns or except_columns narrows that set, and join_columns compares only the person and the listed columns. Two NULL values count as the same value."
+      desc "Keeps each left-hand record that is equal to a right-hand record in every column, including label. Two empty (NULL) values count as equal."
+      returns "The left-hand records that have a right-hand record with the same value in every column. The right-hand records are not returned."
+      option_meaning :right, "The right-hand stream. The operator keeps each left-hand record that is equal to a record of this stream, and does not pass these records on."
+
+      example "MIs that are a patient's first MI",
+              [ "match", { left: [ "icd9", "412" ], right: [ "first", [ "icd9", "412" ] ] } ]
       default_query_columns
 
       # match reads only_columns, except_columns, join_columns and

data/lib/conceptql/operators/multiple_vocabularies.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "vocabulary"
+
 module ConceptQL
   module Operators
     class MultipleVocabularies < Operator
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::CodeLister
+      extend Vocabulary::SharedDocumentation
 
       class << self
         def multiple_vocabularies
@@ -26,12 +29,19 @@ module ConceptQL
           end
         end
 
+        def long_name_of(vocabulary_ids)
+          return vocabulary_ids.first if vocabulary_ids.one?
+
+          "#{vocabulary_ids[0...-1].join(', ')} and #{vocabulary_ids.last}"
+        end
+
         def operator_symbol(word)
           word.gsub(/\W+/, "_").downcase
         end
 
         # This will override the to_metadata method and return the preferred name
-        # based on the name listed in the file.
+        # based on the name listed in the file. The long_name names the
+        # operator's vocabularies, for example "CPT4, HCPCS and CPT4_HCPCS".
         #
         # This method will be called once for each vocabulary we register
         # for this operator
@@ -39,6 +49,7 @@ module ConceptQL
           h = super
           op_info = multiple_vocabularies[name].first
           h[:preferred_name] = op_info[:operator]
+          h[:long_name] = long_name_of(multiple_vocabularies[name].map { |mv| mv[:vocabulary_id] })
           h[:predominant_domains] = multiple_vocabularies[name].map { |mv| mv[:domain] }.uniq.compact
           h
         end
@@ -47,7 +58,10 @@ module ConceptQL
       register_many
 
       desc "Selects records based on the given vocabularies."
-      argument :codes, type: :codelist
+      argument :codes, type: :codelist,
+                       meaning: "One or more codes. The operator looks up each code in each of its vocabularies " \
+                                "(CPT-4 and HCPCS for cpt_or_hcpcs) and selects the matching records of all of them. " \
+                                "A code gets a warning only when every one of the vocabularies rejects it."
       basic_type :selection
       category "Select by Clinical Codes"
       validate_no_upstreams
@@ -111,7 +125,7 @@ module ConceptQL
       CODE_WARNINGS = [ *BAD_FORMATS, UNKNOWN_CODE ].freeze
 
       def additional_validation(db, opts = {})
-        vocab_ops.each { |vo| vo.valid?(db, opts) }
+        vocab_ops.each { |vo| vo.valid?(db, opts.merge(skip_merged_vocabulary_check: true)) }
 
         @errors += aggregate_messages(vocab_ops.map(&:errors))
         @warnings += aggregate_messages(vocab_ops.map { |vo| vo.warnings.reject { |w| CODE_WARNINGS.include?(w.first) } })

data/lib/conceptql/operators/numeric.rb

@@ -15,6 +15,10 @@ module ConceptQL
     # - An optional stream
     class Numeric < PassThru
       register __FILE__
+      # "We do not yet support numeric or sum in any meaningful way"
+      # (Ryan, 2026-11-03, seed conceptql-mdo.4)
+      hidden
+      category "Modify Data"
 
       desc "Sets the value_as_number of each record of its upstream stream. " \
            "The argument is a number, or the name of a column whose value is copied from the same record. " \

data/lib/conceptql/operators/numeric_filter.rb

@@ -12,10 +12,20 @@ module ConceptQL
     class NumericFilter < Operator
       register __FILE__
 
-      desc "Includes records with a value_as_number that match the given criteria."
+      desc "Passes along the records whose value_as_number is in the given range. " \
+           "Lab records, such as those of loinc, carry this value."
+
+      returns "The upstream records whose value_as_number is in the range. " \
+              "A record that has no value_as_number is not passed along."
+
+      option :greater_than_or_equal_to, type: :float,
+                                        meaning: "The lowest value_as_number that passes. Without this option, the range has no lower limit."
+      option :less_than_or_equal_to, type: :float,
+                                     meaning: "The highest value_as_number that passes. Without this option, the range has no upper limit."
+
+      example "Hemoglobin A1c results (LOINC 4548-4) with a value from 5 to 7",
+              [ "numeric_filter", [ "loinc", "4548-4" ], { "greater_than_or_equal_to" => 5, "less_than_or_equal_to" => 7 } ]
 
-      option :greater_than_or_equal_to, type: :float
-      option :less_than_or_equal_to, type: :float
       category "Filter Single Stream"
       basic_type :temporal
       allows_one_upstream

data/lib/conceptql/operators/occurrence.rb

@@ -14,10 +14,11 @@ module ConceptQL
     # -1 => last
     # -2 => second-to-last
     #
-    # The operator treats all streams as a single, large stream.  It partitions
-    # that larget stream by person_id, then sorts within those groupings
-    # by start_date and then select at most one row per person, regardless
-    # of how many different types of streams enter the operator
+    # The operator takes exactly one upstream. It partitions the records of
+    # that upstream by person_id, sorts the records of each person by
+    # start_date, and selects at most one row per person, even when the
+    # upstream mixes records from several criterion tables. With at_least or
+    # within, a person can have more than one row
     #
     # If two rows have the same start_date, criterion_id breaks the tie.
     # criterion_id is unique within one criterion_table, so only rows from
@@ -34,21 +35,41 @@ module ConceptQL
       preferred_name "Nth Occurrence"
 
       desc "For each person, orders the records by start_date and passes along the record at the given position. " \
-           "A positive number counts from the earliest record, so 2 means the second record. " \
-           "A negative number counts from the most recent record, so -3 means the third record from the last."
+           "A positive position counts from the earliest record and a negative one from the most recent record."
 
-      argument :occurrence, type: :integer
+      returns "One record per person: the record at the given position. " \
+              "A person who has fewer records than the position asks for is not passed along. " \
+              "With at_least or within, a person can have more than one record."
+
+      argument :occurrence, type: :integer,
+                            meaning: "The position of the record to pass along, as an integer. " \
+                                     "A positive number counts from the earliest record, so 1 is the first record and 2 is the second. " \
+                                     "A negative number counts from the most recent record, so -1 is the last record and -3 is the third from the last. " \
+                                     "0 selects nothing."
       category "Filter Single Stream"
       basic_type :temporal
-      allows_one_upstream
-      validate_at_least_one_upstream
+      validate_one_upstream
 
       option :at_least, type: :string,
-                        instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years". Negative numbers change dates prior to the existing date. Example: -30d = 30 days before the existing date.'
+                        instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
+                        meaning: "A date adjustment, such as 30d. For each record, the operator counts that record and the later records " \
+                                 "that start at least this long after it ends, and passes along the record at the given position. " \
+                                 "So a person can have more than one record in the result."
       option :within, type: :string,
-                      instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years". Negative numbers change dates prior to the existing date. Example: -30d = 30 days before the existing date.'
+                      instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
+                      meaning: "A date adjustment, such as 365d. For each record, the operator counts that record and the later records " \
+                               "that start at most this long after it ends, and passes along the record at the given position. " \
+                               "So a person can have more than one record in the result."
       option :group_by_date, type: :boolean,
-                             instructions: "Choose whether to group by date when determining the nth occurrence, treating occurrences on the same day as a single occurrence"
+                             instructions: "Choose whether to group by date when determining the nth occurrence, treating occurrences on the same day as a single occurrence",
+                             meaning: "Treats the records of a person on one start_date as one occurrence, so the position counts dates. " \
+                                      "From the date at that position, the operator passes along the record with the lowest criterion_id, " \
+                                      "or the highest criterion_id for a negative position."
+
+      example "For each patient, select the Condition that represents the second occurrence of an MI",
+              [ "occurrence", 2, [ "icd9", "412" ] ]
+      example "For each patient, the first record on the second day with any of these diagnoses",
+              [ "occurrence", 2, [ "icd9", "410.00", "410.01", "250.00", "250.01" ], { "group_by_date" => true } ]
 
       def query_cols
         dynamic_columns + [ :rn ]