conceptql 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +141 -0
  3. data/docs/spec/README.md +402 -337
  4. data/docs/spec/examples/date-range-operator.json +1 -1
  5. data/docs/spec/examples/death-operator.json +1 -1
  6. data/docs/spec/examples/nth-occurrence-operator.json +1 -1
  7. data/docs/spec/examples/one-in-two-out-operator.json +1 -1
  8. data/docs/spec/examples/person-filter-operator.json +2 -2
  9. data/docs/spec/examples/vocabulary-operator.json +3 -3
  10. data/lib/conceptql/behaviors/metadatable.rb +76 -62
  11. data/lib/conceptql/behaviors/utilizable.rb +1 -1
  12. data/lib/conceptql/database.rb +16 -2
  13. data/lib/conceptql/diagram.rb +2 -2
  14. data/lib/conceptql/lexicon/lexicon_no_db.rb +4 -4
  15. data/lib/conceptql/lexicon.rb +7 -4
  16. data/lib/conceptql/operators/after.rb +5 -4
  17. data/lib/conceptql/operators/any_overlap.rb +4 -3
  18. data/lib/conceptql/operators/before.rb +5 -4
  19. data/lib/conceptql/operators/binary_operator_operator.rb +11 -13
  20. data/lib/conceptql/operators/casting_operator.rb +1 -1
  21. data/lib/conceptql/operators/co_reported.rb +9 -7
  22. data/lib/conceptql/operators/contains.rb +4 -3
  23. data/lib/conceptql/operators/count.rb +3 -3
  24. data/lib/conceptql/operators/date_range.rb +9 -8
  25. data/lib/conceptql/operators/death.rb +4 -4
  26. data/lib/conceptql/operators/dedup.rb +2 -2
  27. data/lib/conceptql/operators/during.rb +4 -3
  28. data/lib/conceptql/operators/episode.rb +9 -9
  29. data/lib/conceptql/operators/equal.rb +3 -2
  30. data/lib/conceptql/operators/ethnicity.rb +7 -3
  31. data/lib/conceptql/operators/except.rb +4 -3
  32. data/lib/conceptql/operators/filter.rb +4 -3
  33. data/lib/conceptql/operators/first.rb +4 -3
  34. data/lib/conceptql/operators/from.rb +2 -1
  35. data/lib/conceptql/operators/gender.rb +4 -3
  36. data/lib/conceptql/operators/hospice.rb +4 -3
  37. data/lib/conceptql/operators/hospitalization.rb +4 -3
  38. data/lib/conceptql/operators/information_periods.rb +5 -4
  39. data/lib/conceptql/operators/last.rb +4 -3
  40. data/lib/conceptql/operators/match.rb +4 -3
  41. data/lib/conceptql/operators/multiple_vocabularies.rb +4 -3
  42. data/lib/conceptql/operators/numeric.rb +4 -4
  43. data/lib/conceptql/operators/numeric_filter.rb +6 -6
  44. data/lib/conceptql/operators/occurrence.rb +25 -18
  45. data/lib/conceptql/operators/one_in_two_out.rb +16 -16
  46. data/lib/conceptql/operators/operator.rb +16 -3
  47. data/lib/conceptql/operators/pass_thru.rb +1 -1
  48. data/lib/conceptql/operators/person.rb +3 -3
  49. data/lib/conceptql/operators/person_filter.rb +6 -5
  50. data/lib/conceptql/operators/place_of_service_filter.rb +7 -7
  51. data/lib/conceptql/operators/provenance.rb +9 -9
  52. data/lib/conceptql/operators/provider_filter.rb +6 -6
  53. data/lib/conceptql/operators/race.rb +4 -3
  54. data/lib/conceptql/operators/recall.rb +6 -5
  55. data/lib/conceptql/operators/snf.rb +4 -3
  56. data/lib/conceptql/operators/sum.rb +6 -5
  57. data/lib/conceptql/operators/time_window.rb +6 -6
  58. data/lib/conceptql/operators/trim_date_end.rb +6 -5
  59. data/lib/conceptql/operators/trim_date_start.rb +6 -5
  60. data/lib/conceptql/operators/union.rb +8 -6
  61. data/lib/conceptql/operators/vocabulary.rb +12 -8
  62. data/lib/conceptql/query.rb +41 -12
  63. data/lib/conceptql/scope.rb +10 -2
  64. data/lib/conceptql/version.rb +1 -1
  65. data/lib/conceptql/visitors/metadata_extractor.rb +3 -1
  66. data/lib/conceptql/vocabularies/drg_systems.rb +16 -14
  67. data/lib/conceptql/vocabularies/read_codes.rb +1 -1
  68. data/lib/conceptql/window.rb +23 -2
  69. data/schemas/gdm.yml +0 -66
  70. data/schemas/gdm_wide.yml +0 -66
  71. metadata +1 -1
@@ -137,7 +137,7 @@
137
137
  }
138
138
  },
139
139
  {
140
- "title": "Each patient, with the dates from the start to the end of the data",
140
+ "title": "Each patient, with the dates from the start to the end of the dataset",
141
141
  "statement": [
142
142
  "date_range",
143
143
  {
@@ -2,7 +2,7 @@
2
2
  "spec_id": "death-operator",
3
3
  "examples": [
4
4
  {
5
- "title": "All death records",
5
+ "title": "All deaths",
6
6
  "statement": ["death"],
7
7
  "help": true,
8
8
  "columns": [
@@ -145,7 +145,7 @@
145
145
  }
146
146
  },
147
147
  {
148
- "title": "For each patient, the first record on the second day with any of these diagnoses",
148
+ "title": "For each patient, the first result on the second day with any of these diagnoses",
149
149
  "statement": [
150
150
  "occurrence",
151
151
  2,
@@ -2,7 +2,7 @@
2
2
  "spec_id": "one-in-two-out-operator",
3
3
  "examples": [
4
4
  {
5
- "title": "First diabetes diagnosis, either found once in an inpatient record, or twice in outpatient records at least 30 days apart",
5
+ "title": "First diabetes diagnosis, either one inpatient result, or two outpatient results at least 30 days apart",
6
6
  "statement": [
7
7
  "one_in_two_out",
8
8
  ["icd9", "250.00"],
@@ -166,7 +166,7 @@
166
166
  }
167
167
  },
168
168
  {
169
- "title": "All MI Conditions for people who had an office visit at some point in the data",
169
+ "title": "All MI Conditions for people who had an office visit at some point in the dataset",
170
170
  "statement": [
171
171
  "person_filter",
172
172
  {
@@ -512,7 +512,7 @@
512
512
  }
513
513
  },
514
514
  {
515
- "title": "All MI Conditions for people who are Male OR had an office visit at some point in the data",
515
+ "title": "All MI Conditions for people who are Male OR had an office visit at some point in the dataset",
516
516
  "statement": [
517
517
  "person_filter",
518
518
  {
@@ -2,7 +2,7 @@
2
2
  "spec_id": "vocabulary-operator",
3
3
  "examples": [
4
4
  {
5
- "title": "All records with the ICD-9-CM diagnosis code 412 (old myocardial infarction)",
5
+ "title": "All results with the ICD-9-CM diagnosis code 412 (old myocardial infarction)",
6
6
  "statement": ["icd9cm", "412"],
7
7
  "help": true,
8
8
  "columns": [
@@ -129,7 +129,7 @@
129
129
  }
130
130
  },
131
131
  {
132
- "title": "All MS-DRG 205 records: other respiratory system diagnoses with a major complication or comorbidity",
132
+ "title": "All MS-DRG 205 results: other respiratory system diagnoses with a major complication or comorbidity",
133
133
  "statement": ["ms_drg", "205"],
134
134
  "help": true,
135
135
  "columns": [
@@ -193,7 +193,7 @@
193
193
  }
194
194
  },
195
195
  {
196
- "title": "All CMS-DRG 205 records (a liver disorder)",
196
+ "title": "All CMS-DRG 205 results (a liver disorder)",
197
197
  "statement": ["cms_drg", "205"],
198
198
  "help": false,
199
199
  "columns": [
@@ -2,6 +2,24 @@
2
2
 
3
3
  module ConceptQL
4
4
  module Metadatable
5
+ # The facets of an operator: top-level keys of its metadata. The values of
6
+ # the first seven come from the code (validations, behavior modules and
7
+ # superclasses). Each operator declares its effects. docs/metadata.md
8
+ # says what each one means. A reader that needs every facet iterates this
9
+ # list.
10
+ FACET_KEYS = %i[upstreams reads_data timeless takes_codes uses_provenance utilization temporal_comparison effects].freeze
11
+
12
+ # What an operator can do to rows. docs/metadata.md says what each one
13
+ # means.
14
+ EFFECTS = %i[select keep change combine aggregate cast refer].freeze
15
+
16
+ # Raised when an operator class declares an effect outside EFFECTS
17
+ class UnknownEffectError < ArgumentError
18
+ def initialize(klass, unknown)
19
+ super("#{klass} declares unknown effects #{unknown.inspect}. The known effects are #{EFFECTS.inspect}.")
20
+ end
21
+ end
22
+
5
23
  def preferred_name(value = nil)
6
24
  return @preferred_name unless value
7
25
 
@@ -136,23 +154,28 @@ module ConceptQL
136
154
  end
137
155
  end
138
156
 
139
- def basic_type(value = nil)
140
- return @basic_type unless value
157
+ # Declares what the operator does to results, for example effects :keep,
158
+ # :change. The metadata lists them in this order. Without values, gives
159
+ # the declared effects (an empty list when there are none). A subclass
160
+ # inherits them, so the vocabulary operators get the effects of
161
+ # Vocabulary.
162
+ def effects(*values)
163
+ return @effects || [] if values.empty?
141
164
 
142
- @basic_type = value
143
- end
165
+ unknown = values - EFFECTS
166
+ raise UnknownEffectError.new(self, unknown) unless unknown.empty?
144
167
 
145
- # min_upstreams and max_upstreams say how many positional upstreams pass
146
- # validation (99 means no limit). A validate_*_upstream check sets them
147
- # again when to_metadata runs (derive_metadata_from_validations).
148
- def allows_many_upstreams
149
- @min_upstreams = 0
150
- @max_upstreams = 99
168
+ @effects = values
151
169
  end
152
170
 
153
- def allows_one_upstream
154
- @min_upstreams = 0
155
- @max_upstreams = 1
171
+ # Declares the symbol that a diagram draws for the operator: :selection,
172
+ # :filter, :set, :temporal or :cast. Only the drawing reads it, because
173
+ # the facets cannot give it: count draws :set and episode draws
174
+ # :temporal, and both take one upstream. A subclass inherits it.
175
+ def diagram_base(value = nil)
176
+ return @diagram_base unless value
177
+
178
+ @diagram_base = value
156
179
  end
157
180
 
158
181
  def just_class_name
@@ -182,14 +205,8 @@ module ConceptQL
182
205
  upstream.category cat
183
206
  end
184
207
 
185
- upstream.basic_type @basic_type
186
-
187
- case @max_upstreams
188
- when 1
189
- upstream.allows_one_upstream
190
- when 99
191
- upstream.allows_many_upstreams
192
- end
208
+ upstream.diagram_base @diagram_base
209
+ upstream.effects(*@effects) if @effects
193
210
  end
194
211
 
195
212
  def pref_name
@@ -209,24 +226,56 @@ module ConceptQL
209
226
  short_name: short_name,
210
227
  long_name: long_name,
211
228
  operation: just_class_name.underscore,
212
- min_upstreams: @min_upstreams || 0,
213
- max_upstreams: @max_upstreams || 0,
214
229
  arguments: @arguments || [],
215
230
  options: process_options(@options),
216
231
  # Strings, as JSON gives them: domains (for example death) are symbols
217
232
  predominant_domains: (@domains || @predominant_domains || []).map(&:to_s),
218
233
  desc: get_desc,
219
234
  categories: @categories || [],
220
- basic_type: @basic_type,
235
+ diagram_base: @diagram_base,
221
236
  deprecated: (true if deprecated), # nil for an operator that is not deprecated
222
- arity: arity,
223
237
  aliases: @aliases,
224
238
  spec_id: spec_id,
225
239
  returns: get_returns,
226
240
  examples: examples_for(name)
241
+ }.merge(facets)
242
+ end
243
+
244
+ # The value of each key in FACET_KEYS
245
+ def facets
246
+ {
247
+ upstreams: upstreams_facet,
248
+ reads_data: include?(ConceptQL::Behaviors::Windowable),
249
+ timeless: include?(ConceptQL::Behaviors::Timeless),
250
+ takes_codes: include?(ConceptQL::Behaviors::CodeLister),
251
+ uses_provenance: include?(ConceptQL::Provenanceable),
252
+ utilization: include?(ConceptQL::Behaviors::Utilizable),
253
+ temporal_comparison: ancestors.include?(ConceptQL::Operators::TemporalOperator),
254
+ effects: effects.map(&:to_s)
227
255
  }
228
256
  end
229
257
 
258
+ # The upstreams that the validations accept, as one word. The first
259
+ # check that matches wins: union and co_reported also validate at least
260
+ # one upstream, but they are "two_or_more". nil when no validation says.
261
+ def upstreams_facet
262
+ meths = @validations.map(&:first)
263
+ required = @validations.select { |meth, *| meth == :validate_required_options }.flat_map { |_meth, *names| names }
264
+ if (%i[left right] - required).empty?
265
+ "left_right"
266
+ elsif meths.include?(:validate_at_least_two_upstreams)
267
+ "two_or_more"
268
+ elsif meths.include?(:validate_at_least_one_upstream)
269
+ "one_or_more"
270
+ elsif meths.include?(:validate_at_most_one_upstream)
271
+ "none_or_one"
272
+ elsif meths.include?(:validate_one_upstream)
273
+ "one"
274
+ elsif meths.include?(:validate_no_upstreams)
275
+ "none"
276
+ end
277
+ end
278
+
230
279
  # The returns text that the metadata serves
231
280
  def get_returns
232
281
  returns
@@ -237,21 +286,6 @@ module ConceptQL
237
286
  examples
238
287
  end
239
288
 
240
- def arity
241
- case basic_type
242
- when :set
243
- -1
244
- when :temporal, :cast
245
- 1
246
- when :selection, nil
247
- 0
248
- when :filter
249
- 2
250
- else
251
- raise "#{name} has unknown basic_type: #{basic_type.pretty_inspect}"
252
- end
253
- end
254
-
255
289
  # The desc that the operator set (no_desc sets ""), else the standard
256
290
  # vocabulary text. A subclass does not inherit its parent's desc.
257
291
  def get_desc
@@ -271,7 +305,7 @@ module ConceptQL
271
305
  missing = []
272
306
  missing << :categories if (@categories || []).empty?
273
307
  missing << :desc if get_desc.empty?
274
- missing << :basic_type unless @basic_type
308
+ missing << :diagram_base unless @diagram_base
275
309
  puts "#{just_class_name} is missing #{missing.join(', ')}" unless missing.empty?
276
310
  end
277
311
 
@@ -284,26 +318,6 @@ module ConceptQL
284
318
  end
285
319
  end
286
320
 
287
- def validate_no_upstreams_to_metadata(*_args)
288
- @min_upstreams = 0
289
- @max_upstreams = 0
290
- end
291
-
292
- def validate_one_upstream_to_metadata(*_args)
293
- @min_upstreams = 1
294
- @max_upstreams = 1
295
- end
296
-
297
- def validate_at_least_one_upstream_to_metadata(*_args)
298
- @min_upstreams = 1
299
- @max_upstreams = 99
300
- end
301
-
302
- def validate_at_most_one_upstream_to_metadata(*_args)
303
- @min_upstreams = 0
304
- @max_upstreams = 1
305
- end
306
-
307
321
  def validate_no_arguments_to_metadata(*_args)
308
322
  @arguments = []
309
323
  end
@@ -318,7 +332,7 @@ module ConceptQL
318
332
  end
319
333
 
320
334
  def standard_description
321
- "Selects records based on the #{pref_name} vocabulary."
335
+ "Selects results based on the #{pref_name} vocabulary."
322
336
  end
323
337
 
324
338
  def no_desc
@@ -11,7 +11,7 @@ module ConceptQL
11
11
  included do
12
12
  domains :condition_occurrence
13
13
  category "Select by Property"
14
- basic_type :selection
14
+ diagram_base :selection
15
15
  validate_no_upstreams
16
16
  validate_no_arguments
17
17
 
@@ -45,7 +45,7 @@ module ConceptQL
45
45
  @opts[:scope_opts] = {
46
46
  force_temp_tables: opts.fetch(:force_temp_tables, ENV["CONCEPTQL_FORCE_TEMP_TABLES"] == "true"),
47
47
  scratch_database: opts.fetch(:scratch_database, ENV["DOCKER_SCRATCH_DATABASE"])
48
- }.merge(opts[:scope_opts] || {})
48
+ }.merge(rekey_scope_opts(opts[:scope_opts]))
49
49
  @opts[:scope_opts][:lexicon] = lexicon
50
50
 
51
51
  @shared_utilization_tables = {}
@@ -54,7 +54,7 @@ module ConceptQL
54
54
  end
55
55
 
56
56
  def query(statement, opts = {})
57
- opts[:scope_opts] = (@opts[:scope_opts] || {}).merge(opts.delete(:scope_opts) || {})
57
+ opts[:scope_opts] = (@opts[:scope_opts] || {}).merge(rekey_scope_opts(opts.delete(:scope_opts)))
58
58
  if @opts[:share_utilization] && opts[:scope_opts][:table_prefix].to_s.empty?
59
59
  raise ArgumentError, "share_utilization needs a table_prefix in scope_opts, to name its tables"
60
60
  end
@@ -204,6 +204,20 @@ module ConceptQL
204
204
  end
205
205
  private :lexicon_url_lexicon
206
206
 
207
+ # The scope options of a calling program with Symbol keys, as every
208
+ # reader of the scope expects them. A program that builds its options
209
+ # from JSON has String keys, and a String key had no effect. The keys of
210
+ # the window_opts hash are rekeyed too. The values do not change: a
211
+ # window table statement is rekeyed where it is queried, as the window
212
+ # options of a window statement are (Utils.rekey of the statement).
213
+ def rekey_scope_opts(scope_opts)
214
+ symbolize = ->(hash) { hash.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key } }
215
+ symbolize.call(scope_opts || {}).tap do |opts|
216
+ opts[:window_opts] = symbolize.call(opts[:window_opts]) if opts[:window_opts].is_a?(Hash)
217
+ end
218
+ end
219
+ private :rekey_scope_opts
220
+
207
221
  # This Database's operators for a data model, as a frozen name => class
208
222
  # Hash: a vocabulary operator for every vocabulary in config/vocabularies.csv
209
223
  # (plus the custom file), in this Database's lexicon and in its reference
@@ -82,7 +82,7 @@ module ConceptQL
82
82
  children = upstreams + opts.values_at(:left, :right).compact
83
83
  node = {
84
84
  name: name.to_s,
85
- base: metadata_for(name)[:basic_type]&.to_s,
85
+ base: metadata_for(name)[:diagram_base]&.to_s,
86
86
  humanName: opts[:name] || metadata_for(name)[:preferred_name] || name.to_s
87
87
  }
88
88
  node[:vocabularyId] = metadata_for(name)[:preferred_name] if vocabulary?(name)
@@ -211,7 +211,7 @@ module ConceptQL
211
211
  attr_reader :statements, :cdb
212
212
 
213
213
  def binary
214
- @binary ||= ConceptQL.metadata(cdb)[:operators].select { |_k, v| v[:basic_type] == :filter }.keys
214
+ @binary ||= ConceptQL.metadata(cdb)[:operators].select { |_k, v| v[:upstreams] == "left_right" }.keys
215
215
  end
216
216
 
217
217
  def build_node(operator)
@@ -11,10 +11,10 @@ module ConceptQL
11
11
  #
12
12
  # It must answer the same table methods as the other strategies, because
13
13
  # LexiconStrategy's lookups (concepts, descendants_of,
14
- # related_concept_ids, ...) are written against them. The tables are named
15
- # in the GDM layout (concepts / ancestors / mappings), matching
16
- # #vocabularies_query, which already reads GDM's `vocabularies` table, and
17
- # the columns that LexiconStrategy's queries use (id, concept_code,
14
+ # related_concept_ids, ...) are written against them. The table names
15
+ # (concepts, ancestors, mappings, vocabularies) are placeholders: the mock
16
+ # runs no query, so no database needs these tables. The columns are the
17
+ # ones that LexiconStrategy's queries use (id, concept_code,
18
18
  # vocabulary_id, concept_text; ancestor_id / descendant_id;
19
19
  # concept_1_id / concept_2_id).
20
20
  class LexiconNoDB < LexiconStrategy
@@ -217,10 +217,13 @@ module ConceptQL
217
217
  # It asks through the block, so that question also reaches the cache.
218
218
  #
219
219
  # An empty vocabulary knows every code, unless empty_means_known is
220
- # false. Then it knows none. The code checks of the operators pass false
221
- # and apply the 2020 rule (refs #185) through Database#check_codes,
222
- # because the rule needs both lexicons: it applies only when the
223
- # reference lexicon lacks the vocabulary too (bead conceptql-dufi).
220
+ # false. Then it knows none. The default is the 2020 rule (refs #185)
221
+ # for a caller with one lexicon: a lexicon that lacks a vocabulary cannot
222
+ # tell a real code from a typo, so it accepts every code. The code checks
223
+ # of the operators pass false and apply the rule through
224
+ # Database#check_codes, because there the rule needs both lexicons: it
225
+ # applies only when the reference lexicon lacks the vocabulary too (bead
226
+ # conceptql-dufi).
224
227
  def known_codes(data_db, vocabulary_id, codes, check_case: true, empty_means_known: true)
225
228
  known = lookup(:known_codes, [ data_db, vocabulary_id, codes, empty_means_known ]) do
226
229
  @strategy.known_codes(data_db, vocabulary_id, codes) do
@@ -6,13 +6,14 @@ module ConceptQL
6
6
  module Operators
7
7
  class After < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
11
+ desc "For each patient, keeps the left-hand results whose start_date is after the earliest end_date of the patient's right-hand results. With the within option, each left-hand result is compared with every right-hand result of the patient instead."
12
+ returns "The left-hand results that start after a right-hand result of the same patient ends, each result once. The right-hand results are not returned."
12
13
 
13
14
  allows_at_least_option
14
- 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."
15
- 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."
15
+ option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. The left-hand result must also start no more than this amount after the end_date of the right-hand result. With this option, each left-hand result is compared with every right-hand result of the patient, not only with the one that ends first. Use a positive amount."
16
+ option_meaning :at_least, "A date adjustment, such as 7d or 1w. The left-hand result must start more than this amount after the end_date of the right-hand result. Use a positive amount."
16
17
 
17
18
  example "All MIs that occurred after a patient's first case of diabetes (250.01)",
18
19
  [ "after", { left: [ "icd9", "412" ], right: [ "icd9", "250.01" ] } ]
@@ -6,10 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class AnyOverlap < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
12
- 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."
11
+ desc "For each patient, keeps the left-hand results whose date range shares at least one day with the date range of a right-hand result."
12
+ returns "The left-hand results that overlap the date range of at least one right-hand result of the same patient, each result once. The right-hand results are not returned."
13
+ option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. Before the comparison, the date range of each right-hand result is widened by this amount in each direction: its start_date moves back and its end_date moves forward. Use a positive amount."
13
14
 
14
15
  example "All MIs that overlap with the month of 2010-06",
15
16
  [ "any_overlap", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-06-01", end: "2010-06-30" } ] } ]
@@ -6,13 +6,14 @@ module ConceptQL
6
6
  module Operators
7
7
  class Before < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
11
+ desc "For each patient, keeps the left-hand results whose end_date is before the latest start_date of the patient's right-hand results. With the within option, each left-hand result is compared with every right-hand result of the patient instead."
12
+ returns "The left-hand results that end before a right-hand result of the same patient starts, each result once. The right-hand results are not returned."
12
13
 
13
14
  allows_at_least_option
14
- 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."
15
- 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."
15
+ option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. The left-hand result must also end no more than this amount before the start_date of the right-hand result. With this option, each left-hand result is compared with every right-hand result of the patient, not only with the one that starts last. Use a positive amount."
16
+ option_meaning :at_least, "A date adjustment, such as 7d or 1w. The left-hand result must end more than this amount before the start_date of the right-hand result. Use a positive amount."
16
17
 
17
18
  example "All MIs that occurred before a patient's last case of diabetes (250.01)",
18
19
  [ "before", { left: [ "icd9", "412" ], right: [ "icd9", "250.01" ] } ]
@@ -7,9 +7,9 @@ module ConceptQL
7
7
  # Base class for all operators that take two streams, a left-hand and a right-hand
8
8
  class BinaryOperatorOperator < Operator
9
9
  option :left, type: :upstream,
10
- meaning: "The left-hand stream. The operator compares these records with the right-hand stream and passes on the ones that meet its condition."
10
+ meaning: "The left-hand stream. The operator compares these results with the right-hand stream and passes on the ones that meet its condition."
11
11
  option :right, type: :upstream,
12
- meaning: "The right-hand stream. The operator compares the left-hand records with these records and does not pass them on."
12
+ meaning: "The right-hand stream. The operator compares the left-hand results with these results and does not pass them on."
13
13
  # The operands are the left and right options. A positional upstream
14
14
  # would be ignored, so it is an error (Ryan ruled 2026-11-03).
15
15
  validate_no_upstreams
@@ -17,7 +17,7 @@ module ConceptQL
17
17
  validate_option Array, :left, :right
18
18
  validate_required_options :left, :right
19
19
  category "Filter by Comparing"
20
- basic_type :filter
20
+ diagram_base :filter
21
21
 
22
22
  def upstreams
23
23
  [ left ]
@@ -29,22 +29,20 @@ module ConceptQL
29
29
 
30
30
  attr_reader :left, :right
31
31
 
32
- def events_per_patient
33
- left.events_per_patient
34
- end
35
-
36
- def multiple_vocabularies
37
- left.multiple_vocabularies
38
- end
32
+ # events_per_patient and multiple_vocabularies come from Operator, which
33
+ # reads upstreams.first, the left. A missing left gives :multiple and
34
+ # false, the values of an operator with no upstream.
39
35
 
36
+ # A missing operand, or one that is not an array, is nil. The
37
+ # validations report it, and the walk skips it.
40
38
  def accept(visitor, opts = {})
41
39
  visitor.visit(self)
42
- left.accept(visitor, opts)
43
- right.accept(visitor, opts) unless opts[:avoid_rhs]
40
+ left&.accept(visitor, opts)
41
+ right&.accept(visitor, opts) unless opts[:avoid_rhs]
44
42
  end
45
43
 
46
44
  def all_upstreams
47
- [ left, right ]
45
+ [ left, right ].compact
48
46
  end
49
47
 
50
48
  private
@@ -26,7 +26,7 @@ module ConceptQL
26
26
  # rows in its table as records.
27
27
  class CastingOperator < Operator
28
28
  category "Get Related Data"
29
- basic_type :cast
29
+ diagram_base :cast
30
30
  validate_at_most_one_upstream
31
31
  validate_no_arguments
32
32
 
@@ -6,9 +6,12 @@ module ConceptQL
6
6
  module Operators
7
7
  class CoReported < PassThru
8
8
  register __FILE__
9
+ effects :combine, :keep
9
10
 
11
+ # Each upstream passes along its own records, so with two or more
12
+ # upstreams one person can get one row from each (bead conceptql-8q8h).
10
13
  def events_per_patient
11
- upstreams.all? { |u| u.events_per_patient == :single } ? :single : :multiple
14
+ upstreams.length > 1 ? :multiple : super
12
15
  end
13
16
 
14
17
  def multiple_vocabularies
@@ -17,17 +20,16 @@ module ConceptQL
17
20
  vocabularies.length > 1
18
21
  end
19
22
 
20
- desc "Passes along the records of its upstreams that were reported in the same context as a record of every other upstream. " \
21
- "In the GDM, a context is the claim or other source record that reported the record."
23
+ desc "Passes along the results of its upstreams that were reported in the same context as a result of every other upstream. " \
24
+ "In the GDM, a context is the claim or other source row of the dataset that reported the row behind a result."
22
25
 
23
- returns "The records of each upstream whose context also has a record of every other upstream. " \
24
- "The operator does not compare dates. If one upstream has no record in a context, the records of all upstreams " \
25
- "in that context are not passed along. Person and death records have no context, so they never pass."
26
+ returns "The results of each upstream whose context also has a result of every other upstream. " \
27
+ "The operator does not compare dates. If one upstream has no result in a context, the results of all upstreams " \
28
+ "in that context are not passed along. Person and death results have no context, so they never pass."
26
29
 
27
30
  example "Diabetes diagnoses reported as a reason for an office visit, and those office visits",
28
31
  [ "co_reported", [ "icd9", "250.00" ], [ "cpt", "99214" ] ]
29
32
 
30
- allows_many_upstreams
31
33
  category "Combine Streams"
32
34
  default_query_columns
33
35
  validate_at_least_one_upstream
@@ -6,10 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class Contains < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
12
- 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."
11
+ desc "For each patient, keeps the left-hand results whose date range encloses the date range of a right-hand result. The left-hand result starts on or before the start_date of the right-hand result and ends on or after its end_date."
12
+ returns "The left-hand results that enclose the date range of at least one right-hand result of the same patient, each result once. The right-hand results are not returned."
13
+ option_meaning :within, "A date adjustment, such as 30d, 2m or 1y-3d. Before the comparison, the date range of each left-hand result is widened by this amount in each direction: its start_date moves back and its end_date moves forward. The returned results keep their own dates. Use a positive amount."
13
14
 
14
15
  example "All MIs occurring on 2010-06-22",
15
16
  [ "contains", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-06-22", end: "2010-06-22" } ] } ]
@@ -6,15 +6,15 @@ module ConceptQL
6
6
  module Operators
7
7
  class Count < PassThru
8
8
  register __FILE__
9
+ effects :aggregate
9
10
  hidden
10
11
  category "Modify Data"
11
12
 
12
- desc "Counts the number of records that exactly match across all columns."
13
+ desc "Counts the number of results that exactly match across all columns."
13
14
  # Every stream is a set, so count returns 1 for nearly every row
14
15
  # (seed conceptql-e8n, ruled 2026-10-30).
15
- deprecated "count will become an error in a later release. To count the events of each person, " \
16
+ deprecated "count will become an error in a later release. To count the results of each person, " \
16
17
  'use ["sum", ["numeric", 1, <stream>], {"group_by_person": true}].'
17
- allows_one_upstream
18
18
  validate_one_upstream
19
19
  validate_no_arguments
20
20
  require_column :value_as_number
@@ -12,29 +12,30 @@ module ConceptQL
12
12
  # 'END' represents the last date of data in the data source,
13
13
  class DateRange < Operator
14
14
  register __FILE__
15
+ effects :select
15
16
 
16
17
  include ConceptQL::Behaviors::Windowable
17
18
  include ConceptQL::Behaviors::Timeless
18
19
 
19
20
  DATE_FORMAT = /\A#{Regexp.union([ /START/i, /END/i, /\d{4}-\d{2}-\d{2}/ ])}\z/.freeze
20
21
 
21
- desc "Makes one person record for each patient, with the given start_date and end_date. " \
22
- "Use it to compare other records with a fixed range of dates."
22
+ desc "Makes one person result for each patient, with the given start_date and end_date. " \
23
+ "Use it to compare other results with a fixed range of dates."
23
24
  option :start, type: :string,
24
- meaning: "The start_date of each record. It is a date in YYYY-MM-DD format, START or END. " \
25
+ meaning: "The start_date of each result. It is a date in YYYY-MM-DD format, START or END. " \
25
26
  "START is the earliest start date of any information period in the database, " \
26
27
  "and END is the latest end date. START and END are not case-sensitive."
27
28
  option :end, type: :string,
28
- meaning: "The end_date of each record. It is a date in YYYY-MM-DD format, START or END. " \
29
+ meaning: "The end_date of each result. It is a date in YYYY-MM-DD format, START or END. " \
29
30
  "START is the earliest start date of any information period in the database, " \
30
31
  "and END is the latest end date. START and END are not case-sensitive. " \
31
32
  "For a single day, give the same date as the start option."
32
- returns "One record for each patient. The type of the records is person, " \
33
- "and each record has the start_date and the end_date that the options give."
33
+ returns "One result for each patient. The type of the results is person, " \
34
+ "and each result has the start_date and the end_date that the options give."
34
35
  example "Each patient, with the dates of the year 2010", [ "date_range", { "start" => "2010-01-01", "end" => "2010-12-31" } ]
35
- example "Each patient, with the dates from the start to the end of the data", [ "date_range", { "start" => "START", "end" => "END" } ]
36
+ example "Each patient, with the dates from the start to the end of the dataset", [ "date_range", { "start" => "START", "end" => "END" } ]
36
37
  category "Select by Property"
37
- basic_type :selection
38
+ diagram_base :selection
38
39
  validate_no_upstreams
39
40
  validate_no_arguments
40
41
  validate_option DATE_FORMAT, :start, :end