conceptql 0.6.0 → 0.7.0

data/lib/conceptql/operators/one_in_two_out.rb

@@ -12,7 +12,15 @@ module ConceptQL
 
       register __FILE__
 
-      desc "Identifies an event that appears either once in an inpatient setting or twice within a specified interval in an outpatient setting."
+      desc "For each person, passes along the earliest confirmed condition record. " \
+           "One inpatient record confirms a condition, and so do two outpatient records whose start dates are a given gap apart."
+
+      returns "One record per person: the earliest confirmed condition record. " \
+              "A returned inpatient record has the admission date as its start_date and the discharge date as its end_date, " \
+              "when the claim has them. Only condition records with inpatient, outpatient or carrier_claim provenance can be confirmed."
+
+      example "First diabetes diagnosis, either found once in an inpatient record, or twice in outpatient records at least 30 days apart",
+              [ "one_in_two_out", [ "icd9", "250.00" ], { "outpatient_minimum_gap" => "30d", "outpatient_event_to_return" => "Initial Event" } ]
 
       allows_one_upstream
       validate_one_upstream
@@ -21,13 +29,22 @@ module ConceptQL
       basic_type :temporal
 
       option :inpatient_length_of_stay, type: :integer, min: 0, default: 0,
-                                        desc: "Minimum length of inpatient stay (in days) required for inpatient event to be valid", label: "Inpatient Length of Stay (Days)"
+                                        meaning: "An inpatient stay must be longer than this many days: an inpatient record counts only when its discharge date " \
+                                                 "is more than this many days after its admission date. 0 or no value means no length-of-stay check.",
+                                        label: "Inpatient Length of Stay (Days)"
       option :outpatient_minimum_gap, type: :string, default: "30d",
-                                      instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".'
+                                      instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".',
+                                      meaning: "A date adjustment, such as 30d. The confirming outpatient record must start at least this long " \
+                                               "after the initial outpatient record. Without this option, the gap is 30 days."
       option :outpatient_maximum_gap, type: :string, default: "365d",
-                                      instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".'
+                                      instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".',
+                                      meaning: "A date adjustment, such as 365d. The confirming outpatient record must start no more than this long " \
+                                               "after the initial outpatient record. Without this option, there is no maximum gap."
       option :outpatient_event_to_return, type: :string, options: [ "Initial Event", "Confirming Event" ],
-                                          default: "Initial Event", desc: "Which event to pass downstream"
+                                          default: "Initial Event",
+                                          meaning: "Which outpatient record the operator passes on when two outpatient records confirm the condition: " \
+                                                   "the initial record or the confirming record. " \
+                                                   "Without this option, or with any value other than Initial Event, it passes on the confirming record."
 
       validate_option DateAdjuster::VALID_INPUT, :outpatient_minimum_gap, :outpatient_maximum_gap
 

data/lib/conceptql/operators/operator.rb

@@ -49,7 +49,8 @@ module ConceptQL
       BAD_FORMATS = [ BAD_FORMAT, NDC_BAD_FORMAT ].freeze
       UNKNOWN_CODE = "unknown code(s)"
 
-      option :label, type: :string
+      option :label, type: :string,
+                     meaning: "A short description of the operator's records. The operator writes it into the label column of each of its records, and a recall operator selects those records by it. Each label in a statement must be different."
 
       @validations = []
 
@@ -594,12 +595,15 @@ module ConceptQL
         end
       end
 
-      # A blank value counts as not set, as in Occurrence#at_least_option
+      # A blank value counts as not set, as in Occurrence#at_least_option.
+      # So does false: the Jigsaw diagram editor writes false when a user
+      # clears a checkbox (seed conceptql-ufn).
       def validate_unsupported_options(*opts)
         opts.each do |opt|
-          next if options[opt].to_s.strip.empty?
+          value = options[opt]
+          next if value == false || value.to_s.strip.empty?
 
-          add_error("unsupported option", opt.to_s, options[opt])
+          add_error("unsupported option", opt.to_s, value)
         end
       end
 

data/lib/conceptql/operators/person.rb

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

data/lib/conceptql/operators/person_filter.rb

@@ -7,7 +7,20 @@ module ConceptQL
     class PersonFilter < BinaryOperatorOperator
       register __FILE__
 
-      desc "Passes along left hand records with a corresponding person_id in the right hand records."
+      desc "Keeps each left-hand record whose patient has at least one record in the right-hand stream. The type and the dates of the right-hand records do not matter."
+      returns "The left-hand records of every type whose patient has at least one right-hand record. The right-hand records are not returned."
+      option_meaning :right, "The right-hand stream. The operator keeps the left-hand records of each patient who has a record in this stream, and does not pass these records on."
+
+      example "All MI Conditions for people who are male",
+              [ "person_filter", { left: [ "icd9", "412" ], right: [ "gender", "Male" ] } ]
+      example "All MI Conditions for people who had an office visit at some point in the data",
+              [ "person_filter", { left: [ "icd9", "412" ], right: [ "cpt", "99214" ] } ]
+      example "The same result as the example above, with the office visits converted to patients first",
+              [ "person_filter", { left: [ "icd9", "412" ], right: [ "person", [ "cpt", "99214" ] ] } ]
+      example "All MI Conditions for people who are Male OR had an office visit at some point in the data",
+              [ "person_filter", { left: [ "icd9", "412" ], right: [ "union", [ "cpt", "99214" ], [ "gender", "Male" ] ] } ]
+      example "Yields two types: all MI Conditions for people who are Male, and all office visit Procedures for people who are Male",
+              [ "person_filter", { left: [ "union", [ "icd9", "412" ], [ "cpt", "99214" ] ], right: [ "gender", "Male" ] } ]
       default_query_columns
 
       # PersonFilter has no `as` option, and a statement that sets one fails

data/lib/conceptql/operators/place_of_service_filter.rb

@@ -31,10 +31,19 @@ module ConceptQL
       ANY = "*"
 
       desc "Passes along the records whose place of service is one of the given CMS Place of Service codes. " \
-           "The code * matches a record that has any place of service. " \
            "A record that has no place of service is not passed along."
 
-      argument :places_of_service, type: :codelist, vocab: VOCABULARY_ID
+      returns "The upstream records whose place of service is one of the given codes."
+
+      argument :places_of_service, type: :codelist, vocab: VOCABULARY_ID,
+                                   meaning: "One or more CMS Place of Service codes, such as 21 (inpatient hospital) or 22 (outpatient hospital). " \
+                                            "The code * matches a record whose place of service is any code of that vocabulary. " \
+                                            "An unknown code makes the statement invalid."
+
+      # The test data has no place of service, so the example returns no rows
+      example "Diabetes diagnoses (ICD-9 250.00) with the place of service outpatient hospital (22)",
+              [ "place_of_service_filter", 22, [ "icd9", "250.00" ] ], help: false
+
       category "Filter Single Stream"
       basic_type :temporal
       allows_one_upstream
@@ -51,9 +60,11 @@ module ConceptQL
       private
 
       # With no codes, the lookup returns every concept of the vocabulary.
+      # The codes come from the statement, whose validation reports an
+      # unknown code, so the lookup does not raise CodeCaseMismatchError.
       def place_of_service_concept_ids(db)
         codes = arguments.map(&:to_s)
-        dm.concept_ids(db, VOCABULARY_ID, codes.include?(ANY) ? [] : codes)
+        dm.concept_ids(db, VOCABULARY_ID, codes.include?(ANY) ? [] : codes, check_case: false)
       end
 
       # With no lexicon there are no codes to check against, and every code

data/lib/conceptql/operators/provenance.rb

@@ -20,15 +20,24 @@ module ConceptQL
       register __FILE__
 
       desc "Passes along the records whose provenance matches at least one of the given keywords. " \
-           "Each record has a file provenance, such as inpatient or outpatient, " \
-           "and a code provenance, such as primary or first. " \
-           "A plain keyword matches a record when either provenance matches it. " \
-           "A keyword of the form <file keyword>:<code keyword> matches a record when its file provenance " \
-           "matches the file keyword and its code provenance matches the code keyword. " \
-           "The keyword * matches a record that has any file or code provenance. " \
-           "At least one keyword is required."
+           "The provenance of a record says which kind of file it came from, such as inpatient, " \
+           "and where its code was on the claim, such as primary."
+
+      returns "The upstream records whose provenance matches at least one of the keywords."
+
+      argument :provenance_types, label: "Provenance Types", type: :codelist,
+                                  meaning: "One or more provenance keywords, in lower case. " \
+                                           "A file keyword, such as inpatient, outpatient or carrier_claim, says which kind of file a record came from. " \
+                                           "A code keyword, such as primary or first, says where the code was on the claim. " \
+                                           "A plain keyword matches a record when its file provenance or its code provenance matches it. " \
+                                           "A keyword also matches the provenances under it, so inpatient includes snf. " \
+                                           "A keyword of the form file:code, such as inpatient:primary, needs both the file and the code provenance to match. " \
+                                           "The keyword * matches a record that has any provenance. " \
+                                           "A statement with no keyword, or with an unknown keyword, is invalid."
+
+      example "Diabetes diagnoses (ICD-9 250.00) from inpatient files",
+              [ "provenance", "inpatient", [ "icd9", "250.00" ] ]
 
-      argument :provenance_types, label: "Provenance Types", type: :codelist
       category "Filter Single Stream"
       basic_type :temporal
       allows_one_upstream

data/lib/conceptql/operators/provider_filter.rb

@@ -10,12 +10,24 @@ module ConceptQL
       register __FILE__
 
       desc "Passes along the records whose provider matches the given specialties and roles. " \
-           "Each option is a comma-separated list of concept IDs, and * matches any value. " \
-           "A record matches the specialties when its context specialty or its practitioner specialty " \
-           "is in the list. " \
-           "A record can have more than one specialty, so the operator can pass along the same record more than once."
-      option :specialties, type: :string
-      option :roles, type: :string
+           "Each option is a comma-separated list of concept IDs, and * matches any value."
+
+      returns "The upstream records that have a provider who matches both the specialties and the roles. " \
+              "A record can have more than one provider, so a record comes out once for each provider who matches. " \
+              "Each record gets the columns provider_id, context_specialty_concept_id, practitioner_specialty_concept_id " \
+              "and role_type_concept_id."
+
+      option :specialties, type: :string,
+                           meaning: "A comma-separated list of specialty concept IDs, such as 38003868 (Endocrinology, Diabetes & Metabolism Physician), " \
+                                    "or * for any specialty. A provider matches when the specialty recorded for the provider on the claim, " \
+                                    "or the provider's own specialty, is in the list."
+      option :roles, type: :string,
+                     meaning: "A comma-separated list of role concept IDs of the GDM_ROLE vocabulary, " \
+                              "such as 100000067 (Attending physician) or 100176860 (Billing provider), or * for any role."
+
+      example "Diabetes diagnoses with an endocrinologist as the attending physician",
+              [ "provider_filter", [ "icd9", "250.00" ], { "specialties" => "38003868", "roles" => "100000067" } ]
+
       category "Filter Single Stream"
       basic_type :temporal
       allows_one_upstream

data/lib/conceptql/operators/race.rb

@@ -17,8 +17,16 @@ module ConceptQL
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::Timeless
 
-      desc "Selects person records that match the given set of Race codes."
-      argument :races, type: :codelist, vocab: "Race"
+      desc "Selects the patients with the given races."
+      argument :races, type: :codelist, vocab: "Race",
+                       meaning: "One or more race names, such as White, or race concept IDs. " \
+                                "A name matches the concepts with that name in any vocabulary, and case does not matter. " \
+                                "The operator also selects the more detailed races under each given race, " \
+                                "and each concept that is a kind of one of the race concepts through an is-a relationship. " \
+                                "A value that contains Unknown also selects the patients who have no race or race concept ID 0."
+      returns "One person record for each patient whose race is one of the given races. " \
+              "The start_date and the end_date of each record are the patient's birth date."
+      example "All patients recorded as white", [ "race", "White" ]
       domains :person
       category "Select by Property"
       basic_type :selection
@@ -42,17 +50,14 @@ module ConceptQL
 
         concept_ids = dm.concept_ids_by_name(db, words)
 
-        c_ids = (concept_ids + actual_ids).map { |i| [ i, race_descendents[i] ] }.flatten.compact.uniq.sort
+        c_ids = (concept_ids + actual_ids.map(&:to_i)).map { |i| [ i, race_descendents[i] ] }.flatten.compact.uniq.sort
 
         c_ids = dm.related_concept_ids(db, c_ids)
 
-        q = db.from(source_table)
-        if words.any? { |w| w.match(/unknown/i) }
-          c_ids += [ 0 ]
-          q = q.where(race_concept_id: nil)
-        end
+        condition = Sequel.expr(race_concept_id: c_ids)
+        condition = Sequel.|(condition, { race_concept_id: 0 }, { race_concept_id: nil }) if words.any? { |w| w.match(/unknown/i) }
 
-        q.where(race_concept_id: c_ids)
+        db.from(source_table).where(condition)
       end
 
       def actual_ids

data/lib/conceptql/operators/read.rb

@@ -3,17 +3,27 @@
 require "sequel"
 require "sequel/adapters/mock"
 require_relative "../behaviors/labish"
+require_relative "vocabulary"
 
 module ConceptQL
   module Operators
     class Read < Operator
       include ConceptQL::Behaviors::CodeLister
+      extend Vocabulary::SharedDocumentation
       register __FILE__
 
       preferred_name "READ"
+      # The vocabulary_name of Read in the OHDSI vocabulary table
+      long_name "NHS UK Read Codes Version 2 (HSCIC)"
+      # Metadata only: the records come from ReadGDM, which selects condition_occurrence
+      predominant_domains :condition_occurrence
       desc "Selects records based on the Read vocabulary."
-      argument :read_codes, type: :codelist, vocab: "Read"
+      argument :read_codes, type: :codelist, vocab: "Read",
+                            meaning: "One or more Read codes. Write each code as the Read vocabulary writes it. " \
+                                     "A code matches exactly, including case, and it does not select its child codes. " \
+                                     "A code alone of * selects every Read record."
       basic_type :selection
+      validate_no_upstreams
       category "Select by Clinical Codes"
       conceptql_spec_id "vocabulary"
 

data/lib/conceptql/operators/recall.rb

@@ -14,9 +14,41 @@ module ConceptQL
     class Recall < Operator
       register __FILE__
 
-      desc "Passes along the records of the operator in the statement that has the given label."
+      desc "Passes on the records of the operator in the statement that has the given label. " \
+           "Use it to break a complex statement into parts, or to use a stream of records more than once."
+      returns "The records of the operator that has the given label."
+      example 'Label neurological diagnoses as "neuro dxs". Recall them to remove those that were co-reported ' \
+              "with a nervous-system MS-DRG. Then apply the one inpatient, two outpatient rule. " \
+              "(The code lists are shortened.)",
+              [
+                "one_in_two_out",
+                [
+                  "except",
+                  {
+                    "left" => [
+                      "union",
+                      [ "icd9", "331.0", "332.0", "340", "345.90" ],
+                      [ "icd10cm", "G20", "G30.9", "G35", "G40.909" ],
+                      { "label" => "neuro dxs" }
+                    ],
+                    "right" => [
+                      "co_reported",
+                      [ "recall", "neuro dxs" ],
+                      [ "ms_drg", "056", "057", "058", "059", "060", "100", "101" ]
+                    ]
+                  }
+                ],
+                {
+                  "outpatient_minimum_gap" => "30d",
+                  "outpatient_maximum_gap" => "365d",
+                  "outpatient_event_to_return" => "Confirming Event"
+                }
+              ]
 
-      argument :name, type: :string
+      argument :name, type: :string,
+                      meaning: "The label of the operator whose records to pass on. It must match the label exactly, " \
+                               "including case. The labeled operator can come before or after the recall in the " \
+                               "statement, but labeled streams that recall each other in a loop are invalid."
       category "Get Related Data"
       basic_type :selection
       validate_no_upstreams

data/lib/conceptql/operators/snf.rb

@@ -8,7 +8,13 @@ module ConceptQL
       register __FILE__
       include ConceptQL::Behaviors::Utilizable
 
-      desc "Selects skilled nursing facility (SNF) admission records."
+      desc "Selects admissions to skilled nursing facilities (SNF): one record for each admission whose claim came from an SNF file."
+      returns "One record for each SNF 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 SNF claims
+      example "All SNF admissions", [ "snf" ], help: false
 
       def collection_type
         "snf"

data/lib/conceptql/operators/sum.rb

@@ -6,6 +6,10 @@ module ConceptQL
   module Operators
     class Sum < 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"
 
       def events_per_patient
         group_by_person? ? :single : :multiple

data/lib/conceptql/operators/temporal_operator.rb

@@ -15,7 +15,8 @@ module ConceptQL
       default_query_columns
 
       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 positive number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
+                      meaning: "A date adjustment, such as 30d, 2m or 1y-3d, that lets the compared dates be up to this amount apart. Each temporal operator applies it to its own comparison. Use a positive amount."
 
       # The temporal operators read join_columns through
       # BinaryOperatorOperator#join_columns_option, but do not declare it with
@@ -28,7 +29,8 @@ module ConceptQL
       class << self
         def allows_at_least_option
           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 positive number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
+                            meaning: "A date adjustment, such as 7d or 1w, that sets the smallest gap between the compared dates. The gap must be larger than this amount. Use a positive amount."
         end
       end
 

data/lib/conceptql/operators/time_window.rb

@@ -8,8 +8,9 @@ module ConceptQL
     # A TimeWindow adjusts the start_date and end_date the incoming stream by the values specified in
     # the start and end arguments.
     #
-    # Start and end take the format of ([+-]\d*[mdy])+.  For example:
+    # Start and end take the format of ([+-]\d*[dwmy])+.  For example:
     # 'd' => adjust date by one day.  2012-10-07 => 2012-10-08
+    # 'w' => adjust date by one week. 2012-10-07 => 2012-10-14
     # 'm' => adjust date by one month. 2012-10-07 => 2012-11-07
     # 'y' => adjust date by one year. 2012-10-07 => 2013-10-07
     # '1y' => adjust date by one year. 2012-10-07 => 2013-10-07
@@ -24,11 +25,33 @@ module ConceptQL
     class TimeWindow < PassThru
       register __FILE__
 
-      desc "Adjusts start_date and end_date to create a new window of time for each record."
+      # The values that the start and end options take (DateAdjuster)
+      DATE_ADJUSTMENT_TEXT = "The value is an amount of time, made of one or more numbers, each with a unit: " \
+                             "d (days), w (weeks), m (months) or y (years). Each part can have a - or + sign, " \
+                             "a bare number means days, and a unit without a number means 1 of it. " \
+                             "For example, -1m is 1 month back, and 10d3m is 3 months and 10 days. " \
+                             "An empty value or 0 leaves the date unchanged. The value start or end uses the " \
+                             "record's start_date or end_date, and a date in YYYY-MM-DD format sets the date to that date."
+
+      desc "Moves the start_date and the end_date of each record. " \
+           "Use it to shift or widen a record's dates before you compare them with other records."
       option :start, 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.'
+                     instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years, such as 30d. A negative number moves the date earlier. You can also enter start, end or a date in YYYY-MM-DD format.',
+                     meaning: "How to change the start_date. If you omit it, the start_date does not change. #{DATE_ADJUSTMENT_TEXT}"
       option :end, 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.'
+                   instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years, such as 30d. A negative number moves the date earlier. You can also enter start, end or a date in YYYY-MM-DD format.',
+                   meaning: "How to change the end_date. If you omit it, the end_date does not change. #{DATE_ADJUSTMENT_TEXT}"
+      returns "One record for each upstream record, with the start_date and the end_date that the options give. " \
+              "The other columns do not change."
+      example "All Diagnoses of Diabetes (ICD-9 250.01) within 30 days of an MI",
+              [ "during", { "left" => [ "icd9", "250.01" ], "right" => [ "time_window", [ "icd9", "412" ], { "start" => "-30d", "end" => "30d" } ] } ]
+      example "Shift the dates of all MIs back by 200 years", [ "time_window", [ "icd9", "412" ], { "start" => "-200y", "end" => "-200y" } ]
+      example "Widen the dates of all MIs to run from 2 months and 2 days before the MI to 1 year and 3 days after it",
+              [ "time_window", [ "icd9", "412" ], { "start" => "-2m-2d", "end" => "3d1y" } ]
+      example "Collapse the date range of all MIs to the start date: leave start_date unchanged and set end_date to start_date",
+              [ "time_window", [ "icd9", "412" ], { "start" => "", "end" => "start" } ]
+      example "Nonsensical, but allowed: swap the start_date and end_date",
+              [ "time_window", [ "icd9", "412" ], { "start" => "end", "end" => "start" } ]
       allows_one_upstream
       validate_one_upstream
       validate_no_arguments

data/lib/conceptql/operators/trim_date.rb

@@ -4,6 +4,11 @@ require_relative "temporal_operator"
 
 module ConceptQL
   module Operators
+    # The base class of trim_date_end and trim_date_start. It does not
+    # register, so trim_date is not an operator name, and its subclasses set
+    # their own desc. The rest of this comment describes trim_date_end.
+    # trim_date_start does the same with the dates reversed.
+    #
     # Trims the end_date of the LHS set of records by the RHS's earliest
     # start_date (per person)
     # If a the RHS contains a start_date that comes before the LHS's start_date
@@ -27,20 +32,7 @@ module ConceptQL
     # (trim_date_start). An LHS record is discarded only when it has RHS
     # records and none of them passes.
     class TrimDate < TemporalOperator
-      desc <<~EOF
-        Trims the end_date of the left hand records (LHR) by the earliest
-        start_date (per person) in the right hand records (RHR)
-        If the RHR contains a start_date that comes before the start_date in the LHR
-        that record in the LHR is completely discarded.
-
-        If there is no record in the RHR for a record in the LHR, the record in the LHR is passed
-        through unaffected.
-
-        If the start_date of the record in the RHR is later than the end_date of the record in the LHR, the record in the LHR
-        is passed through unaffected.
-      EOF
-
-      allows_one_upstream
+      no_desc
 
       def query(db)
         # If the RHS's min start date is less than the LHS start date,

data/lib/conceptql/operators/trim_date_end.rb

@@ -17,9 +17,15 @@ module ConceptQL
     class TrimDateEnd < TrimDate
       register __FILE__
 
-      desc "For each person, trims the end_date of all left hand records by the earliest start_date in the right hand records."
-
-      allows_one_upstream
+      desc "For each patient, moves the end_date of each left-hand record back to the start_date of the right-hand record with the earliest start_date. A left-hand record that starts after that start_date is removed, and the left-hand records of a patient without right-hand records pass through unchanged."
+      returns "The left-hand records, each with its end_date set to the earlier of its own end_date and the start_date of the patient's right-hand record. Left-hand records that start after that start_date are not returned. The right-hand records are not returned."
+      option_meaning :left, "The left-hand stream. The operator moves the end_date of these records and passes them on."
+      option_meaning :right, "The right-hand stream. For each patient, the earliest start_date of these records sets the latest end_date of the left-hand records. These records are not passed on."
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d, that is subtracted from the start_date of the right-hand record before the comparison. The adjusted date is the one that moves the end_date of the left-hand record."
+
+      example "Each patient's span from birth to age 50 or to 1970-01-01, whichever is earlier (patients born after 1970 are dropped)",
+              [ "trim_date_end", { left: [ "time_window", [ "person" ], { end: "+50y" } ],
+                                   right: [ "date_range", { start: "1970-01-01", end: "1970-01-01" } ] } ]
 
       private
 

data/lib/conceptql/operators/trim_date_start.rb

@@ -17,9 +17,15 @@ module ConceptQL
     class TrimDateStart < TrimDate
       register __FILE__
 
-      desc "For each person, trims the start_date of all left hand records by the most recent end_date in the right hand records."
-
-      allows_one_upstream
+      desc "For each patient, moves the start_date of each left-hand record forward to the end_date of the right-hand record with the latest start_date. A left-hand record that ends before that end_date is removed, and the left-hand records of a patient without right-hand records pass through unchanged."
+      returns "The left-hand records, each with its start_date set to the later of its own start_date and the end_date of the patient's right-hand record. Left-hand records that end before that end_date are not returned. The right-hand records are not returned."
+      option_meaning :left, "The left-hand stream. The operator moves the start_date of these records and passes them on."
+      option_meaning :right, "The right-hand stream. For each patient, the end_date of the record with the latest start_date sets the earliest start_date of the left-hand records. These records are not passed on."
+      option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d, that is added to the end_date of the right-hand record before the comparison. The adjusted date is the one that moves the start_date of the left-hand record."
+
+      example "Each patient's span from birth to age 50, trimmed to start no earlier than 1980-01-01 (patients who were 50 before 1980 are dropped)",
+              [ "trim_date_start", { left: [ "time_window", [ "person" ], { end: "+50y" } ],
+                                     right: [ "date_range", { start: "1980-01-01", end: "1980-01-01" } ] } ]
 
       private
 

data/lib/conceptql/operators/union.rb

@@ -54,7 +54,19 @@ module ConceptQL
         vocabularies.length > 1
       end
 
-      desc "Combines sets of incoming records into a single large set of records."
+      desc "Combines the records of all its upstream operators into one stream. " \
+           "Each record keeps its own type, so one stream can hold several types."
+
+      returns "Each record of each upstream. A record that comes from more than one upstream comes out once. " \
+              "Two records are the same only when every column is equal, including label."
+
+      example "Two streams of the same type (condition_occurrence) combined into one stream",
+              [ "union", [ "icd9", "412" ], [ "icd9", "250.01" ] ]
+      example "Two condition_occurrence streams combined, then combined with a procedure_occurrence stream",
+              [ "union", [ "union", [ "icd9", "412" ], [ "icd9", "250.01" ] ], [ "cpt", "99214" ] ]
+      example "Two condition_occurrence streams and a procedure_occurrence stream combined by a single union",
+              [ "union", [ "icd9", "412" ], [ "icd9", "250.01" ], [ "cpt", "99214" ] ]
+
       allows_many_upstreams
       category "Combine Streams"
       default_query_columns