Reword most operator descriptions, refs #237

outcomesinsights · Apr 27, 2023 · b4a9ddc · b4a9ddc
1 parent b099581
commit b4a9ddc
Show file tree

Hide file tree

Showing 30 changed files with 35 additions and 108 deletions.
diff --git a/lib/conceptql/operators/after.rb b/lib/conceptql/operators/after.rb
@@ -5,15 +5,7 @@ module Operators
     class After < TemporalOperator
       register __FILE__
 
-      desc <<-EOF
-Compares all records on a person-by-person basis between the left hand records (LHR) and the right hand records (RHR).
-Any record in the LHR with a start_date that occurs after the earliest end_date in the RHR is passed through.
-All other records are discarded, including all records in the RHR.
-L-------N-------L
-R-----R
-   R-----R
-        L-----Y----L
-      EOF
+      desc "Compares records on a person-by-person basis, passes along left hand records with a start_date that occurs after the earliest end_date of a right hand record."
 
       allows_at_least_option
       within_skip :after

diff --git a/lib/conceptql/operators/any_overlap.rb b/lib/conceptql/operators/any_overlap.rb
@@ -5,7 +5,7 @@ module Operators
     class AnyOverlap < TemporalOperator
       register __FILE__
 
-      desc 'If a record in the LHR overlaps in any way a record in the RHR, it is passed through.'
+      desc "Compares records on a person-by-person basis and passes along left hand records with a date range that overlaps in any way with a right hand record's date_range."
 
       def where_clause
         ((within_start <= l_start_date) & (l_start_date <= within_end)) | ((l_start_date <= within_start) & (within_start <= l_end_date))

diff --git a/lib/conceptql/operators/before.rb b/lib/conceptql/operators/before.rb
@@ -5,11 +5,7 @@ module Operators
     class Before < TemporalOperator
       register __FILE__
 
-      desc <<-EOF
-Compares all records on a person-by-person basis between the left hand records (LHR) and the right hand records (RHR).
-Any record in the LHR with an end_date that occurs before the most recent start_date of the RHR is passed through.
-All other records are discarded, including all records in the RHR.
-      EOF
+      desc "Compares records on a person-by-person basis, passes along left hand records with an end_date that occurs before the most recent start_date of a right hand record."
 
       allows_at_least_option
       within_skip :before

diff --git a/lib/conceptql/operators/co_reported.rb b/lib/conceptql/operators/co_reported.rb
@@ -6,7 +6,7 @@ module Operators
     class CoReported < PassThru
       register __FILE__
 
-      desc 'Passes through all events that were co-reported in a database. For GDM, an event is considered to be "co-reported" if it shares the same context_id as another event.'
+      desc 'Passes along all events that were co-reported in a database. For GDM, an event is considered to be "co-reported" if it shares the same context_id as another event.'
       allows_many_upstreams
       category "Combine Streams"
       default_query_columns

diff --git a/lib/conceptql/operators/concurrent_within.rb b/lib/conceptql/operators/concurrent_within.rb
@@ -6,7 +6,7 @@ module Operators
     class ConcurrentWithin < Operator
       register __FILE__
 
-      desc 'Filters each upstream to only include rows where there are matching entries in each of the other upstreams.'
+      desc "Filters each upstream to only include records where other upstreams' date ranges overlap"
       option :start, type: :string
       option :end, type: :string
       allows_many_upstreams

diff --git a/lib/conceptql/operators/contains.rb b/lib/conceptql/operators/contains.rb
@@ -5,12 +5,7 @@ module Operators
     class Contains < TemporalOperator
       register __FILE__
 
-      desc <<-EOF
-If a record in the left hand records (LHR) has a start_date on or before and an end_date on or after a record in the right hand records (RHR), it is passed through.
-L--X-L
-R-----R
-L------Y--------L
-      EOF
+      desc "Compares records on a person-by-person basis and passes along left hand records with a start_date and end_date contained within a right hand record's start_date and end_date."
 
       def where_clause
         (within_start <= r_start_date) & (r_end_date <= within_end)

diff --git a/lib/conceptql/operators/date_range.rb b/lib/conceptql/operators/date_range.rb
@@ -16,7 +16,7 @@ class DateRange < Operator
 
       DATE_FORMAT = /\A#{Regexp.union([/START/i, /END/i, /\d{4}-\d{2}-\d{2}/])}\z/
 
-      desc "Used to represent a date literal.  Dates must be in the format YYYY-MM-DD"
+      desc "Creates a set of all person records with the given start_date and end_date."
       option :start, type: :string
       option :end, type: :string
       category "Select by Property"

diff --git a/lib/conceptql/operators/death.rb b/lib/conceptql/operators/death.rb
@@ -7,7 +7,7 @@ class Death < CastingOperator
 
       register __FILE__
 
-      desc 'Generates all death records, or, if fed a stream, fetches all death records for the people represented in the incoming record set.'
+      desc 'Selects all death records'
       domains :death
       allows_one_upstream
 

diff --git a/lib/conceptql/operators/during.rb b/lib/conceptql/operators/during.rb
@@ -5,11 +5,7 @@ module Operators
     class During < TemporalOperator
       register __FILE__
 
-      desc <<-EOF
-Compares all records on a person-by-person basis between the left hand records (LHR) and the right hand records (RHR).
-Any record in the LHR with a start_date and end_date that occur within the start_date and end_date of a record in the RHR is passed through.
-All other records are discarded, including all records in the RHR.
-      EOF
+      desc "Compares records on a person-by-person basis and passes along left hand records with a start_date within a right hand record's start_date and end_date."
 
       def where_clause
         (within_start <= l_start_date) & (l_end_date <= within_end)

diff --git a/lib/conceptql/operators/episode.rb b/lib/conceptql/operators/episode.rb
@@ -5,9 +5,8 @@ module Operators
     class Episode < PassThru
       register __FILE__
 
-      desc <<-EOF
-Groups all incoming results into episodes by person allowing for there to be a gap, defined by "Gap Of", between the end date of an event and the start date of the next one to be considered the same episode.
-      EOF
+      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."
+
       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'

diff --git a/lib/conceptql/operators/equal.rb b/lib/conceptql/operators/equal.rb
@@ -5,7 +5,7 @@ module Operators
     class Equal < TemporalOperator
       register __FILE__
 
-      desc 'If a record in the left hand records (LHR) has the same value_as_number as a record in the right hand records (RHR), it is passed through.'
+      desc 'Compares records on a person-by-person basis and passes along left hand records that have the same value_as_number as a right hand record.'
       require_column :value_as_number
 
       def where_clause

diff --git a/lib/conceptql/operators/ethnicity.rb b/lib/conceptql/operators/ethnicity.rb
@@ -5,7 +5,7 @@ module Operators
     class Ethnicity < Operator
       register __FILE__
 
-      desc "Generates all person records that match the given set of Race codes."
+      desc "Selects person records that match the given set of Ethnicity codes."
       domains :person
       category "Select by Property"
       basic_type :selection

diff --git a/lib/conceptql/operators/except.rb b/lib/conceptql/operators/except.rb
@@ -5,7 +5,7 @@ module Operators
     class Except < BinaryOperatorOperator
       register __FILE__
 
-      desc 'If a record in the left hand records (LHR) appears in the right hand records (RHR), it is removed from the output record set.'
+      desc "Removes all incoming records that appear in the right hand set of records."
       default_query_columns
 
       def query(db)

diff --git a/lib/conceptql/operators/filter.rb b/lib/conceptql/operators/filter.rb
@@ -5,7 +5,7 @@ module Operators
     class Filter < BinaryOperatorOperator
       register __FILE__
 
-      desc 'If a record in the left hand records (LHR) has a corresponding record in the right hand records (RHR) with the same person, criterion_id, and criterion_domain, it is passed through.'
+      desc "Keeps left hand records that share the same person, criterion_id, and criterion_domain with a right hand side record."
       default_query_columns
 
       def query(db)

diff --git a/lib/conceptql/operators/first.rb b/lib/conceptql/operators/first.rb
@@ -17,7 +17,7 @@ module Operators
     class First < Occurrence
       register __FILE__
 
-      desc 'Only passes through the record with the earliest start_date per person.  If more than one record qualifies, the record is arbitrarily chosen.'
+      desc "Passes along, per person, the record with the earliest start_date."
 
       def occurrence
         1

diff --git a/lib/conceptql/operators/last.rb b/lib/conceptql/operators/last.rb
@@ -17,7 +17,7 @@ module Operators
     class Last < Occurrence
       register __FILE__
 
-      desc 'Only passes through the record with the most recent start_date per person.  If more than one record qualifies, the record is arbitrarily chosen.'
+      desc "Passes along, per person, the record with the most recent start_date."
 
       def occurrence
         -1

diff --git a/lib/conceptql/operators/match.rb b/lib/conceptql/operators/match.rb
@@ -5,7 +5,7 @@ module Operators
     class Match < BinaryOperatorOperator
       register __FILE__
 
-      desc 'If a record in the left hand records (LHR) has a corresponding record in the right hand records (RHR) with the same person, criterion_id, and criterion_domain, it is passed through.'
+      desc "Keeps left hand records that share the same person, criterion_id, and criterion_domain with a right hand side record."
       default_query_columns
 
       def query(db)

diff --git a/lib/conceptql/operators/numeric_filter.rb b/lib/conceptql/operators/numeric_filter.rb
@@ -11,11 +11,8 @@ module Operators
     class NumericFilter < Operator
       register __FILE__
 
-      desc <<-DESC
-        Filters records to include those with a value_as_number that matches the given criteria.
+      desc 'Includes records with a value_as_number that matches the given criteria.  Excludes records where value_as_number is NULL.'
 
-        If value_as_number is NULL, the record is excluded.
-      DESC
       option :greater_than_or_equal_to, type: :float
       option :less_than_or_equal_to, type: :float
       category "Filter Single Stream"

diff --git a/lib/conceptql/operators/occurrence.rb b/lib/conceptql/operators/occurrence.rb
@@ -26,20 +26,7 @@ class Occurrence < Operator
 
       preferred_name 'Nth Occurrence'
 
-      desc <<-EOF
-Groups all records by person, then orders by start_date and finds the nth occurrence (can be positive or negative).
-1 => first
-2 => second
-...
--1 => last
--2 => second-to-last
-
-If two records have the same start_date, their relative order
-is arbitrary.
-
-If we ask for the second occurrence of something and a person has only one
-occurrence, this operator returns nothing for that person.
-      EOF
+      desc "Groups all records by person, then orders by start_date and finds the nth occurrence. Can be positive or negative, e.g 2 means 'second' and -3 means 'third from last'."
 
       argument :occurrence, type: :integer
       category "Filter Single Stream"

diff --git a/lib/conceptql/operators/one_in_two_out.rb b/lib/conceptql/operators/one_in_two_out.rb
@@ -1,5 +1,4 @@
 require_relative 'operator'
-require_relative 'visit_occurrence'
 require_relative '../date_adjuster'
 require_relative '../behaviors/provenanceable'
 
@@ -9,9 +8,9 @@ class OneInTwoOut < Operator
       register __FILE__
 
       desc <<-EOF
-Represents a common pattern in research algorithms: searching for an event
+Applies a common pattern in research algorithms by searching for an event
 that appears either once in an inpatient setting or
-twice in an outpatient setting with a 30-day gap.
+twice in an outpatient setting with a specified gap.
       EOF
       allows_one_upstream
       validate_one_upstream

diff --git a/lib/conceptql/operators/person.rb b/lib/conceptql/operators/person.rb
@@ -8,7 +8,7 @@ class Person < CastingOperator
 
       register __FILE__
 
-      desc 'Generates all person records, or, if fed a stream, fetches all person records for the people represented in the incoming record set.'
+      desc "Selects all person records."
       allows_one_upstream
       domains :person
 

diff --git a/lib/conceptql/operators/person_filter.rb b/lib/conceptql/operators/person_filter.rb
@@ -5,7 +5,7 @@ module Operators
     class PersonFilter < BinaryOperatorOperator
       register __FILE__
 
-      desc 'If a record in the left hand records (LHR) matches a person in the right hand records (RHR), it is passed through.'
+      desc "Passes along left hand records with a corresponding person_id in the right hand records."
       default_query_columns
 
       def query(db)

diff --git a/lib/conceptql/operators/place_of_service_filter.rb b/lib/conceptql/operators/place_of_service_filter.rb
@@ -15,11 +15,8 @@ module Operators
     class PlaceOfServiceFilter < Operator
       register __FILE__
 
-      desc <<-EOF
-Filters records to include only those that match one or more of the Medicare Place Of Service values.
+      desc "Passes along records that match one or more of the Medicare Place Of Service values."
 
-Common values include 21 (inpatient hospital), 23 (emergency room), and 11 (office).
-      EOF
       argument :places_of_service, type: :codelist, vocab: 'Place of Service'
       category "Filter Single Stream"
       basic_type :temporal

diff --git a/lib/conceptql/operators/provenance.rb b/lib/conceptql/operators/provenance.rb
@@ -16,15 +16,8 @@ module Operators
     class Provenance < Operator
       register __FILE__
 
-      desc <<-EOF
-Filters incoming records to those with the indicated provenance.
-
-Enter numeric concept id(s), or the corresponding text label(s):
-- Inpatient: inpatient, inpatient_detail, inpatient_header, inpatient_primary, inpatient_primary_or_first
-- Outpatient: outpatient, outpatient_detail, outpatient_header, outpatient_primary, outpatient_primary_or_first
-- Carrier: carrier_claim, carrier_claim_detail, carrier_claim_header, carrier_claim_primary_or_first
-- Other: primary, primary_or_first, claim
-      EOF
+      desc "Passes along records with the indicated provenance."
+
       argument :provenance_types, label: 'Provenance Types', type: :codelist
       category "Filter Single Stream"
       basic_type :temporal

diff --git a/lib/conceptql/operators/provider_filter.rb b/lib/conceptql/operators/provider_filter.rb
@@ -7,7 +7,7 @@ module Operators
     class ProviderFilter < Operator
       register __FILE__
 
-      desc "Filters incoming records to only those that match the associated providers based on provider specialty concept_ids."
+      desc "Passes along records where the provider's specialty matches a given set of specialty_concept_ids."
       option :specialties, type: :string
       category "Filter Single Stream"
       basic_type :temporal
@@ -21,7 +21,7 @@ def query(db)
         ds = stream.evaluate(db).from_self(alias: :upstream)
 
         specialty_concept_ids = options[:specialties].split(/\s*,\s*/)
-            
+
         unless specialty_concept_ids.include?('*')
           ds = ds.where(specialty_concept_id: specialty_concept_ids.map(&:to_i))
         end

diff --git a/lib/conceptql/operators/race.rb b/lib/conceptql/operators/race.rb
@@ -15,7 +15,7 @@ class Race < Operator
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::Timeless
 
-      desc 'Generates all person records that match the given set of Race codes.'
+      desc "Selects person records that match the given set of Race codes."
       argument :races, type: :codelist, vocab: 'Race'
       domains :person
       category "Select by Property"

diff --git a/lib/conceptql/operators/recall.rb b/lib/conceptql/operators/recall.rb
@@ -12,10 +12,8 @@ module Operators
     class Recall < Operator
       register __FILE__
 
-      desc <<-EOF
-Recalls a set of named records that were previously stored using the Define operator.
-Must be surrounded by the same Let operator as surrounds the corresponding Define operator.
-      EOF
+      desc "Recalls a set of records from a labeled operator in the statement"
+
       argument :name, type: :string
       category "Get Related Data"
       basic_type :selection

diff --git a/lib/conceptql/operators/time_window.rb b/lib/conceptql/operators/time_window.rb
@@ -22,7 +22,7 @@ module Operators
     class TimeWindow < PassThru
       register __FILE__
 
-      desc 'Adjusts the start_date and end_date to create a new window of time for each record.'
+      desc 'Adjusts start_date and end_date to create a new window of time for each record.'
       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.'
       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.'
       allows_one_upstream

diff --git a/lib/conceptql/operators/trim_date_end.rb b/lib/conceptql/operators/trim_date_end.rb
@@ -15,18 +15,7 @@ module Operators
     class TrimDateEnd < TrimDate
       register __FILE__
 
-      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
+      desc "Trims, on a person-by-person basis, the end_date of all left hand records by the earliest start_date in the right hand records."
 
       allows_one_upstream
 

diff --git a/lib/conceptql/operators/trim_date_start.rb b/lib/conceptql/operators/trim_date_start.rb
@@ -15,18 +15,7 @@ module Operators
     class TrimDateStart < TrimDate
       register __FILE__
 
-      desc <<-EOF
-Trims the start_date of the left hand records (LHR) by the final
-end_date (per person) in the right hand records (RHR)
-If the RHR contains an end_date that comes after the end_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 end_date of the record in the RHR is earlier than the start_date of the record in the LHR, the record in the LHR
-is passed through unaffected.
-      EOF
+      desc "Trims, on a person-by-person basis, the start_date of all left hand records by the most recent end_date in the right hand records."
 
       allows_one_upstream