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
@@ -8,14 +8,14 @@ module ConceptQL
8
8
  include ConceptQL::Behaviors::Windowable
9
9
 
10
10
  register __FILE__
11
+ effects :select, :cast
11
12
 
12
- desc "Selects every death record. With one upstream operator, it selects the deaths of the patients who have a record in the upstream stream."
13
- returns "One record for each selected death, from the deaths table. The type of the records is death, " \
13
+ desc "Selects every death. With one upstream operator, it selects the deaths of the patients who have a result in the upstream stream."
14
+ returns "One result for each selected death, from the deaths table. The type of the results is death, " \
14
15
  "and their start_date and end_date are both the date of death."
15
- example "All death records", [ "death" ]
16
+ example "All deaths", [ "death" ]
16
17
  example "The deaths of the patients with an old myocardial infarction (ICD-9-CM 412)", [ "death", [ "icd9cm", "412" ] ]
17
18
  domains :death
18
- allows_one_upstream
19
19
 
20
20
  def my_domain
21
21
  :death
@@ -6,11 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class Dedup < PassThru
8
8
  register __FILE__
9
+ effects :keep
9
10
  hidden
10
11
  category "Filter Single Stream"
11
12
 
12
- desc "Passes along each distinct record once. Records that have the same value in every column become one record."
13
- allows_one_upstream
13
+ desc "Passes along each distinct result once. Results that have the same value in every column become one result."
14
14
  validate_one_upstream
15
15
 
16
16
  def query(db)
@@ -6,10 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class During < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
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 is inside the date range of a right-hand result. The left-hand result starts on or after the start_date of the right-hand result and ends on or before its end_date."
12
+ returns "The left-hand results that are inside 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 for the year 2010",
15
16
  [ "during", { left: [ "icd9", "412" ], right: [ "date_range", { start: "2010-01-01", end: "2010-12-31" } ] } ]
@@ -6,26 +6,26 @@ module ConceptQL
6
6
  module Operators
7
7
  class Episode < PassThru
8
8
  register __FILE__
9
+ effects :aggregate
9
10
 
10
- desc "Merges each patient's records into episodes: spans of time in which the records are close together. " \
11
+ desc "Merges each patient's results into episodes: spans of time in which the results are close together. " \
11
12
  "For example, it can turn a set of prescriptions into the spans of time in which a patient takes a drug."
12
- returns "One record for each episode. Its start_date is the earliest start_date in the episode, " \
13
+ returns "One result for each episode. Its start_date is the earliest start_date in the episode, " \
13
14
  "and its end_date is the latest end_date. Its criterion_table and criterion_domain are episode, " \
14
- "and its criterion_id is 0, because an episode merges several records."
15
+ "and its criterion_id is 0, because an episode merges several results."
15
16
  example "Episodes of diabetes diagnoses", [ "episode", [ "icd9", "250.00" ], { "gap_of" => "90" } ]
16
17
 
17
- allows_one_upstream
18
18
  validate_one_upstream
19
19
  option :gap_of, type: :integer,
20
- 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.",
20
+ instructions: "Enter a number of days. A result stays in the current episode when it starts no more than this many days after the latest end date of the earlier results. The default is 0.",
21
21
  meaning: "The largest gap in days that stays in the same episode. The operator orders each " \
22
- "patient's records by start_date and then by end_date. A record stays in the current " \
22
+ "patient's results by start_date and then by end_date. A result stays in the current " \
23
23
  "episode when its start_date is no more than this many days after the latest end_date " \
24
- "of the earlier records, not only of the record just before. Otherwise it starts a " \
25
- "new episode. A record without an end_date counts as ending on its start_date. " \
24
+ "of the earlier results, not only of the result just before. Otherwise it starts a " \
25
+ "new episode. A result without an end_date counts as ending on its start_date. " \
26
26
  "The default is 0."
27
27
  category "Modify Data"
28
- basic_type :temporal
28
+ diagram_base :temporal
29
29
 
30
30
  def table
31
31
  nil
@@ -6,9 +6,10 @@ module ConceptQL
6
6
  module Operators
7
7
  class Equal < TemporalOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
11
+ desc "For each patient, keeps the left-hand results whose value_as_number equals the value_as_number of a right-hand result. It does not compare dates."
12
+ returns "The left-hand results that have a right-hand result of the same patient with the same value_as_number, each result once. Left-hand results without a value_as_number (NULL) are not returned. The right-hand results are not returned."
12
13
 
13
14
  # The test data has only one record with a value_as_number, so this
14
15
  # example returns no rows there and stays out of the help.
@@ -6,19 +6,23 @@ module ConceptQL
6
6
  module Operators
7
7
  class Ethnicity < Operator
8
8
  register __FILE__
9
+ effects :select
10
+
11
+ include ConceptQL::Behaviors::Windowable
12
+ include ConceptQL::Behaviors::Timeless
9
13
 
10
14
  desc "Selects the patients with the given ethnicities."
11
15
  domains :person
12
16
  category "Select by Property"
13
- basic_type :selection
17
+ diagram_base :selection
14
18
  argument :ethnicity, type: :string, options: [ "Hispanic or Latino", "Not Hispanic or Latino" ],
15
19
  meaning: "One or more ethnicities. A value that starts with Hispanic selects the " \
16
20
  "Hispanic or Latino patients, and a value that starts with Not Hispanic selects " \
17
21
  "the patients who are not Hispanic or Latino. A value that contains Unknown " \
18
22
  "selects the patients who have no ethnicity or ethnicity concept ID 0. Case does not matter, " \
19
23
  "and any other value selects no patients."
20
- returns "One person record for each patient whose ethnicity is one of the given ethnicities. " \
21
- "The start_date and the end_date of each record are the patient's birth date."
24
+ returns "One person result for each patient whose ethnicity is one of the given ethnicities. " \
25
+ "The start_date and the end_date of each result are the patient's birth date."
22
26
  example "All patients recorded as Hispanic", [ "ethnicity", "Hispanic" ]
23
27
  validate_no_upstreams
24
28
  validate_at_least_one_argument
@@ -6,10 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class Except < BinaryOperatorOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
12
- 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."
11
+ desc "Removes each left-hand result that also appears in the right-hand stream. Two results are the same when they have the same criterion_table, criterion_id, start_date and end_date."
12
+ returns "The left-hand results that have no right-hand result with the same criterion_table, criterion_id, start_date and end_date. A left-hand result whose table has no right-hand result passes through unchanged. The right-hand results are not returned."
13
+ option_meaning :right, "The right-hand stream. The operator removes each left-hand result that is also in this stream, and does not pass these results on."
13
14
 
14
15
  example "All males who are not white",
15
16
  [ "except", { left: [ "gender", "male" ], right: [ "race", "white" ] } ]
@@ -6,10 +6,11 @@ module ConceptQL
6
6
  module Operators
7
7
  class Filter < BinaryOperatorOperator
8
8
  register __FILE__
9
+ effects :keep
9
10
 
10
- 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."
11
- 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."
12
- 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."
11
+ desc "Keeps each left-hand result that also appears in the right-hand stream. Two results are the same when they have the same person_id, criterion_id, criterion_table, criterion_domain, start_date and end_date."
12
+ returns "The left-hand results that have a right-hand result with the same person_id, criterion_id, criterion_table, criterion_domain, start_date and end_date. The right-hand results are not returned."
13
+ option_meaning :right, "The right-hand stream. The operator keeps each left-hand result that is also in this stream, and does not pass these results on."
13
14
 
14
15
  example "MIs that are a patient's first diagnosis of MI or diabetes",
15
16
  [ "filter", { left: [ "icd9", "412" ], right: [ "first", [ "union", [ "icd9", "412" ], [ "icd9", "250.01" ] ] ] } ]
@@ -20,11 +20,12 @@ module ConceptQL
20
20
  # occurrences, this operator returns nothing for that person
21
21
  class First < Occurrence
22
22
  register __FILE__
23
+ effects :keep
23
24
 
24
- desc "For each person, passes along the record with the earliest start_date."
25
+ desc "For each person, passes along the result with the earliest start_date."
25
26
 
26
- returns "One record per person: the upstream record with the earliest start_date. " \
27
- "When several records have that start_date, the one with the lowest criterion_id."
27
+ returns "One result per person: the upstream result with the earliest start_date. " \
28
+ "When several results have that start_date, the one with the lowest criterion_id."
28
29
 
29
30
  example "For each patient, select the Condition that represents the first occurrence of an MI",
30
31
  [ "first", [ "icd9", "412" ] ]
@@ -7,10 +7,11 @@ module ConceptQL
7
7
  include ConceptQL::Behaviors::Timeless
8
8
 
9
9
  register __FILE__
10
+ effects :select
10
11
  # Reads a raw table. It is not a public operator.
11
12
  hidden
12
13
  category "Select by Property"
13
- basic_type :selection
14
+ diagram_base :selection
14
15
  no_desc
15
16
  option :domains, type: Array
16
17
  option :query_cols, type: Array
@@ -6,6 +6,7 @@ module ConceptQL
6
6
  module Operators
7
7
  class Gender < Operator
8
8
  register __FILE__
9
+ effects :select
9
10
 
10
11
  include ConceptQL::Behaviors::Windowable
11
12
  include ConceptQL::Behaviors::Timeless
@@ -16,13 +17,13 @@ module ConceptQL
16
17
  "and a value that starts with F selects the female patients. " \
17
18
  "Any other value, such as Unknown, selects the patients whose gender is " \
18
19
  "neither male nor female, including the patients with no gender. Case does not matter."
19
- returns "One person record for each patient whose gender is one of the given genders. " \
20
- "The start_date and the end_date of each record are the patient's birth date."
20
+ returns "One person result for each patient whose gender is one of the given genders. " \
21
+ "The start_date and the end_date of each result are the patient's birth date."
21
22
  example "All female patients", [ "gender", "Female" ]
22
23
  example "All male patients", [ "gender", "Male" ]
23
24
  domains :person
24
25
  category "Select by Property"
25
- basic_type :selection
26
+ diagram_base :selection
26
27
  validate_no_upstreams
27
28
  validate_at_least_one_argument
28
29
 
@@ -6,13 +6,14 @@ module ConceptQL
6
6
  module Operators
7
7
  class Hospice < Operator
8
8
  register __FILE__
9
+ effects :select
9
10
  include ConceptQL::Behaviors::Utilizable
10
11
 
11
- desc "Selects hospice admissions: one record for each admission whose claim came from a hospice file."
12
- returns "One record for each hospice admission. The type of the records is condition_occurrence, " \
12
+ desc "Selects hospice admissions: one result for each admission whose claim came from a hospice file."
13
+ returns "One result for each hospice admission. The type of the results is condition_occurrence, " \
13
14
  "and their criterion_table is collections, the table of claims. Their start_date and end_date " \
14
15
  "are the dates of the claim, and source_value holds the primary code of the admission when it has one. " \
15
- "Each record also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
16
+ "Each result also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
16
17
  # The test data has no hospice claims
17
18
  example "All hospice admissions", [ "hospice" ], help: false
18
19
 
@@ -6,13 +6,14 @@ module ConceptQL
6
6
  module Operators
7
7
  class Hospitalization < Operator
8
8
  register __FILE__
9
+ effects :select
9
10
  include ConceptQL::Behaviors::Utilizable
10
11
 
11
- desc "Selects inpatient hospital admissions: one record for each admission whose claim came from an inpatient file."
12
- returns "One record for each inpatient admission. The type of the records is condition_occurrence, " \
12
+ desc "Selects inpatient hospital admissions: one result for each admission whose claim came from an inpatient file."
13
+ returns "One result for each inpatient admission. The type of the results is condition_occurrence, " \
13
14
  "and their criterion_table is collections, the table of claims. Their start_date and end_date " \
14
15
  "are the dates of the claim, and source_value holds the primary code of the admission when it has one. " \
15
- "Each record also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
16
+ "Each result also has admission and discharge columns, such as admission_date, discharge_date and length_of_stay."
16
17
  example "All inpatient hospital admissions", [ "hospitalization" ]
17
18
 
18
19
  def collection_type
@@ -6,11 +6,12 @@ module ConceptQL
6
6
  module Operators
7
7
  class InformationPeriods < Operator
8
8
  register __FILE__
9
+ effects :select
9
10
 
10
11
  include ConceptQL::Behaviors::Windowable
11
12
  include ConceptQL::Behaviors::Timeless
12
13
 
13
- desc "Selects information periods: the spans of time in which the data has information about a patient, " \
14
+ desc "Selects information periods: the spans of time in which the dataset has information about a patient, " \
14
15
  "such as periods of insurance enrollment."
15
16
  argument :information_types, label: "Information Types", type: :codelist,
16
17
  meaning: "Zero or more information types, each as a concept ID (an integer) " \
@@ -19,12 +20,12 @@ module ConceptQL
19
20
  "With no information types, the operator selects every information period. " \
20
21
  "With information types, it selects only the information periods whose type is one of them. " \
21
22
  "An unknown code gets a warning and selects no period."
22
- returns "One record for each selected information period, from the information_periods table. " \
23
- "The type of the records is observation_period."
23
+ returns "One result for each selected information period, from the information_periods table. " \
24
+ "The type of the results is observation_period."
24
25
  example "All information periods", [ "information_periods" ]
25
26
  domains :observation_period
26
27
  category "Get Related Data"
27
- basic_type :selection
28
+ diagram_base :selection
28
29
  validate_no_upstreams
29
30
 
30
31
  def query(db)
@@ -20,11 +20,12 @@ module ConceptQL
20
20
  # occurrences, this operator returns nothing for that person
21
21
  class Last < Occurrence
22
22
  register __FILE__
23
+ effects :keep
23
24
 
24
- desc "For each person, passes along the record with the most recent start_date."
25
+ desc "For each person, passes along the result with the most recent start_date."
25
26
 
26
- returns "One record per person: the upstream record with the latest start_date. " \
27
- "When several records have that start_date, the one with the highest criterion_id."
27
+ returns "One result per person: the upstream result with the latest start_date. " \
28
+ "When several results have that start_date, the one with the highest criterion_id."
28
29
 
29
30
  example "For each patient, select the Condition that represents the last occurrence of an MI",
30
31
  [ "last", [ "icd9", "412" ] ]
@@ -8,10 +8,11 @@ module ConceptQL
8
8
  # column, so a stream matched with itself keeps every record.
9
9
  class Match < BinaryOperatorOperator
10
10
  register __FILE__
11
+ effects :keep
11
12
 
12
- 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."
13
- 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."
14
- 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."
13
+ desc "Keeps each left-hand result that is equal to a right-hand result in every column, including label. Two empty (NULL) values count as equal."
14
+ returns "The left-hand results that have a right-hand result with the same value in every column. The right-hand results are not returned."
15
+ option_meaning :right, "The right-hand stream. The operator keeps each left-hand result that is equal to a result of this stream, and does not pass these results on."
15
16
 
16
17
  example "MIs that are a patient's first MI",
17
18
  [ "match", { left: [ "icd9", "412" ], right: [ "first", [ "icd9", "412" ] ] } ]
@@ -57,12 +57,13 @@ module ConceptQL
57
57
 
58
58
  register_many
59
59
 
60
- desc "Selects records based on the given vocabularies."
60
+ desc "Selects results based on the given vocabularies."
61
61
  argument :codes, type: :codelist,
62
62
  meaning: "One or more codes. The operator looks up each code in each of its vocabularies " \
63
- "(CPT-4 and HCPCS for cpt_or_hcpcs) and selects the matching records of all of them. " \
63
+ "(CPT-4 and HCPCS for cpt_or_hcpcs) and selects the matching results of all of them. " \
64
64
  "A code gets a warning only when every one of the vocabularies rejects it."
65
- basic_type :selection
65
+ diagram_base :selection
66
+ effects :select
66
67
  category "Select by Clinical Codes"
67
68
  validate_no_upstreams
68
69
  validate_at_least_one_argument
@@ -15,18 +15,18 @@ module ConceptQL
15
15
  # - An optional stream
16
16
  class Numeric < PassThru
17
17
  register __FILE__
18
+ effects :select, :change
18
19
  # "We do not yet support numeric or sum in any meaningful way"
19
20
  # (Ryan, 2026-11-03, seed conceptql-mdo.4)
20
21
  hidden
21
22
  category "Modify Data"
22
23
 
23
- desc "Sets the value_as_number of each record of its upstream stream. " \
24
- "The argument is a number, or the name of a column whose value is copied from the same record. " \
25
- "Without an upstream stream, the operator selects one person record for each person, " \
24
+ desc "Sets the value_as_number of each result of its upstream stream. " \
25
+ "The argument is a number, or the name of a column whose value is copied from the same result. " \
26
+ "Without an upstream stream, the operator selects one person result for each person, " \
26
27
  "with value_as_number set to the argument. " \
27
28
  "A column name must then name a column of the person table."
28
29
  argument :value, type: :float
29
- allows_one_upstream
30
30
  validate_at_most_one_upstream
31
31
  validate_one_argument
32
32
  default_query_columns
@@ -11,12 +11,13 @@ module ConceptQL
11
11
  # If an record has NULL for value_as_number, it is filtered out.
12
12
  class NumericFilter < Operator
13
13
  register __FILE__
14
+ effects :keep
14
15
 
15
- desc "Passes along the records whose value_as_number is in the given range. " \
16
- "Lab records, such as those of loinc, carry this value."
16
+ desc "Passes along the results whose value_as_number is in the given range. " \
17
+ "The results of lab tests, such as those of loinc, carry this value."
17
18
 
18
- returns "The upstream records whose value_as_number is in the range. " \
19
- "A record that has no value_as_number is not passed along."
19
+ returns "The upstream results whose value_as_number is in the range. " \
20
+ "A result that has no value_as_number is not passed along."
20
21
 
21
22
  option :greater_than_or_equal_to, type: :float,
22
23
  meaning: "The lowest value_as_number that passes. Without this option, the range has no lower limit."
@@ -27,8 +28,7 @@ module ConceptQL
27
28
  [ "numeric_filter", [ "loinc", "4548-4" ], { "greater_than_or_equal_to" => 5, "less_than_or_equal_to" => 7 } ]
28
29
 
29
30
  category "Filter Single Stream"
30
- basic_type :temporal
31
- allows_one_upstream
31
+ diagram_base :temporal
32
32
  validate_one_upstream
33
33
  require_column :value_as_number
34
34
  default_query_columns
@@ -31,44 +31,45 @@ module ConceptQL
31
31
  include ConceptQL::Behaviors::SingleEvent
32
32
 
33
33
  register __FILE__
34
+ effects :keep
34
35
 
35
36
  preferred_name "Nth Occurrence"
36
37
 
37
- desc "For each person, orders the records by start_date and passes along the record at the given position. " \
38
- "A positive position counts from the earliest record and a negative one from the most recent record."
38
+ desc "For each person, orders the results by start_date and passes along the result at the given position. " \
39
+ "A positive position counts from the earliest result and a negative one from the most recent result."
39
40
 
40
- returns "One record per person: the record at the given position. " \
41
- "A person who has fewer records than the position asks for is not passed along. " \
42
- "With at_least or within, a person can have more than one record."
41
+ returns "One result per person: the result at the given position. " \
42
+ "A person who has fewer results than the position asks for is not passed along. " \
43
+ "With at_least or within, a person can have more than one result."
43
44
 
44
45
  argument :occurrence, type: :integer,
45
- meaning: "The position of the record to pass along, as an integer. " \
46
- "A positive number counts from the earliest record, so 1 is the first record and 2 is the second. " \
47
- "A negative number counts from the most recent record, so -1 is the last record and -3 is the third from the last. " \
46
+ meaning: "The position of the result to pass along, as an integer. " \
47
+ "A positive number counts from the earliest result, so 1 is the first result and 2 is the second. " \
48
+ "A negative number counts from the most recent result, so -1 is the last result and -3 is the third from the last. " \
48
49
  "0 selects nothing."
49
50
  category "Filter Single Stream"
50
- basic_type :temporal
51
+ diagram_base :temporal
51
52
  validate_one_upstream
52
53
 
53
54
  option :at_least, type: :string,
54
55
  instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
55
- meaning: "A date adjustment, such as 30d. For each record, the operator counts that record and the later records " \
56
- "that start at least this long after it ends, and passes along the record at the given position. " \
57
- "So a person can have more than one record in the result."
56
+ meaning: "A date adjustment, such as 30d. For each result, the operator counts that result and the later results " \
57
+ "that start at least this long after it ends, and passes along the result at the given position. " \
58
+ "So a person can have more than one result."
58
59
  option :within, type: :string,
59
60
  instructions: 'Enter a number followed by "d", "w", "m" or "y" for days, weeks, months or years. Example: 30d.',
60
- meaning: "A date adjustment, such as 365d. For each record, the operator counts that record and the later records " \
61
- "that start at most this long after it ends, and passes along the record at the given position. " \
62
- "So a person can have more than one record in the result."
61
+ meaning: "A date adjustment, such as 365d. For each result, the operator counts that result and the later results " \
62
+ "that start at most this long after it ends, and passes along the result at the given position. " \
63
+ "So a person can have more than one result."
63
64
  option :group_by_date, type: :boolean,
64
65
  instructions: "Choose whether to group by date when determining the nth occurrence, treating occurrences on the same day as a single occurrence",
65
- meaning: "Treats the records of a person on one start_date as one occurrence, so the position counts dates. " \
66
- "From the date at that position, the operator passes along the record with the lowest criterion_id, " \
66
+ meaning: "Treats the results of a person on one start_date as one occurrence, so the position counts dates. " \
67
+ "From the date at that position, the operator passes along the result with the lowest criterion_id, " \
67
68
  "or the highest criterion_id for a negative position."
68
69
 
69
70
  example "For each patient, select the Condition that represents the second occurrence of an MI",
70
71
  [ "occurrence", 2, [ "icd9", "412" ] ]
71
- example "For each patient, the first record on the second day with any of these diagnoses",
72
+ example "For each patient, the first result on the second day with any of these diagnoses",
72
73
  [ "occurrence", 2, [ "icd9", "410.00", "410.01", "250.00", "250.01" ], { "group_by_date" => true } ]
73
74
 
74
75
  def query_cols
@@ -153,6 +154,12 @@ module ConceptQL
153
154
  .with(joined_name, joined_ds)
154
155
  end
155
156
 
157
+ # The timed query can pass along several records of one person
158
+ # (bead conceptql-vsqm). First and Last are never timed.
159
+ def events_per_patient
160
+ timed? ? :multiple : super
161
+ end
162
+
156
163
  def grouped?
157
164
  options[:group_by_date]
158
165
  end
@@ -11,40 +11,40 @@ module ConceptQL
11
11
  include ConceptQL::Behaviors::SingleEvent
12
12
 
13
13
  register __FILE__
14
+ effects :keep, :change
14
15
 
15
- desc "For each person, passes along the earliest confirmed condition record. " \
16
- "One inpatient record confirms a condition, and so do two outpatient records whose start dates are a given gap apart."
16
+ desc "For each person, passes along the earliest confirmed condition result. " \
17
+ "One inpatient result confirms a condition, and so do two outpatient results whose start dates are a given gap apart."
17
18
 
18
- returns "One record per person: the earliest confirmed condition record. " \
19
- "A returned inpatient record has the admission date as its start_date and the discharge date as its end_date, " \
20
- "when the claim has them. Only condition records with inpatient, outpatient or carrier_claim provenance can be confirmed."
19
+ returns "One result per person: the earliest confirmed condition result. " \
20
+ "A returned inpatient result has the admission date as its start_date and the discharge date as its end_date, " \
21
+ "when the claim has them. Only condition results with inpatient, outpatient or carrier_claim provenance can be confirmed."
21
22
 
22
- example "First diabetes diagnosis, either found once in an inpatient record, or twice in outpatient records at least 30 days apart",
23
+ example "First diabetes diagnosis, either one inpatient result, or two outpatient results at least 30 days apart",
23
24
  [ "one_in_two_out", [ "icd9", "250.00" ], { "outpatient_minimum_gap" => "30d", "outpatient_event_to_return" => "Initial Event" } ]
24
25
 
25
- allows_one_upstream
26
26
  validate_one_upstream
27
27
  validate_no_arguments
28
28
  category "Filter Single Stream"
29
- basic_type :temporal
29
+ diagram_base :temporal
30
30
 
31
31
  option :inpatient_length_of_stay, type: :integer, min: 0, default: 0,
32
- meaning: "An inpatient stay must be longer than this many days: an inpatient record counts only when its discharge date " \
32
+ meaning: "An inpatient stay must be longer than this many days: an inpatient result counts only when its discharge date " \
33
33
  "is more than this many days after its admission date. 0 or no value means no length-of-stay check.",
34
34
  label: "Inpatient Length of Stay (Days)"
35
35
  option :outpatient_minimum_gap, type: :string, default: "30d",
36
36
  instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".',
37
- meaning: "A date adjustment, such as 30d. The confirming outpatient record must start at least this long " \
38
- "after the initial outpatient record. Without this option, the gap is 30 days."
37
+ meaning: "A date adjustment, such as 30d. The confirming outpatient result must start at least this long " \
38
+ "after the initial outpatient result. Without this option, the gap is 30 days."
39
39
  option :outpatient_maximum_gap, type: :string, default: "365d",
40
40
  instructions: 'Enter a numeric value and specify "d", "m", or "y" for "days", "months", or "years".',
41
- meaning: "A date adjustment, such as 365d. The confirming outpatient record must start no more than this long " \
42
- "after the initial outpatient record. Without this option, there is no maximum gap."
41
+ meaning: "A date adjustment, such as 365d. The confirming outpatient result must start no more than this long " \
42
+ "after the initial outpatient result. Without this option, there is no maximum gap."
43
43
  option :outpatient_event_to_return, type: :string, options: [ "Initial Event", "Confirming Event" ],
44
44
  default: "Initial Event",
45
- meaning: "Which outpatient record the operator passes on when two outpatient records confirm the condition: " \
46
- "the initial record or the confirming record. " \
47
- "Without this option, or with any value other than Initial Event, it passes on the confirming record."
45
+ meaning: "Which outpatient result the operator passes on when two outpatient results confirm the condition: " \
46
+ "the initial result or the confirming result. " \
47
+ "Without this option, or with any value other than Initial Event, it passes on the confirming result."
48
48
 
49
49
  validate_option DateAdjuster::VALID_INPUT, :outpatient_minimum_gap, :outpatient_maximum_gap
50
50
 
@@ -48,10 +48,15 @@ module ConceptQL
48
48
  NDC_BAD_FORMAT = "#{BAD_FORMAT} (claims use 11-digit package NDCs, so it matches no rows)"
49
49
  BAD_FORMATS = [ BAD_FORMAT, NDC_BAD_FORMAT ].freeze
50
50
  UNKNOWN_CODE = "unknown code(s)"
51
+ # A code given as a JSON number (412, not "412") is an error of the
52
+ # statement, not a warning (Ryan ruled 2026-11-13, bead conceptql-uob6).
53
+ # The lookups would send the number to SQL, and Postgres cannot compare
54
+ # a text column with an integer. The error names each such code.
55
+ NON_STRING_CODE = "codes must be strings"
51
56
  ONE_UPSTREAM = "has only one upstream"
52
57
 
53
58
  option :label, type: :string,
54
- 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."
59
+ meaning: "A short description of the operator's results. The operator writes it into the label column of each of its results, and a recall operator selects those results by it. Each label in a statement must be different."
55
60
 
56
61
  @validations = []
57
62
 
@@ -90,6 +95,7 @@ module ConceptQL
90
95
  option
91
96
  required_options
92
97
  codes_match
98
+ string_codes
93
99
  END
94
100
 
95
101
  validation_meths.each do |type|
@@ -624,12 +630,14 @@ module ConceptQL
624
630
  end
625
631
  end
626
632
 
633
+ # A code that is not a string is the error of validate_string_codes,
634
+ # so it gets no format warning too.
627
635
  def bad_arguments
628
636
  return [] unless code_regexp
629
637
  # Vocabulary#select_all? is private, so include private methods.
630
638
  return [] if respond_to?(:select_all?, true) && select_all?
631
639
 
632
- @bad_arguments ||= arguments.reject do |arg|
640
+ @bad_arguments ||= arguments.grep(String).reject do |arg|
633
641
  code_regexp === arg
634
642
  end
635
643
  end
@@ -643,6 +651,11 @@ module ConceptQL
643
651
  nil
644
652
  end
645
653
 
654
+ def validate_string_codes
655
+ non_strings = arguments.grep_v(String)
656
+ add_error(NON_STRING_CODE, *non_strings) unless non_strings.empty?
657
+ end
658
+
646
659
  def validate_codes_match
647
660
  return if bad_arguments.empty?
648
661
 
@@ -720,7 +733,7 @@ module ConceptQL
720
733
  end
721
734
 
722
735
  def matching_columns
723
- if scope.opts.dig(:window_opts, :window_table)
736
+ if scope.window_opts[:window_table]
724
737
  %i[person_id window_id]
725
738
  else
726
739
  [ :person_id ]
@@ -9,7 +9,7 @@ module ConceptQL
9
9
  # co_reported). It has no query method, so it does not register: pass_thru
10
10
  # is not an operator name.
11
11
  class PassThru < Operator
12
- basic_type :set
12
+ diagram_base :set
13
13
  no_desc
14
14
 
15
15
  def domains(db)