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
@@ -10,24 +10,25 @@ module ConceptQL
10
10
  # CMS replaced the CMS-DRG system with MS-DRG on 2007-10-01 and reused
11
11
  # most DRG codes for new meanings: DRG 010 meant "Nervous System
12
12
  # Neoplasms" before that day and "Pancreas transplant" after it. One
13
- # vocabulary, DRG, holds both systems, and an event row does not record
14
- # which meaning applied: the ETL stores one concept ID for each source code
15
- # whatever the event date. So a statement names the system, and the system
16
- # decides by the event date. ["ms_drg", "010"] selects the DRG 010 events
17
- # from 2007-10-01, and ["cms_drg", "010"] selects the DRG 010 events before
13
+ # vocabulary, DRG, holds both systems, and a row of a dataset table does
14
+ # not record which meaning applied: the ETL stores one concept ID for each
15
+ # source code whatever the start date of the row. So a statement names the
16
+ # system, and the system decides by that start date. ["ms_drg", "010"]
17
+ # selects the DRG 010 results
18
+ # from 2007-10-01, and ["cms_drg", "010"] selects the DRG 010 results before
18
19
  # that day. The concept-ID lookup is the one that drg uses. The
19
20
  # operators use no OHDSI validity date and no concept class to select
20
- # events.
21
+ # results.
21
22
  #
22
23
  # Each operator is a vocabulary operator of vocabulary DRG. So its code
23
24
  # format is the DRG row of vocabulary_formats (a vocabulary operator uses
24
25
  # the row of the vocabulary it selects), and its unknown-code warning
25
26
  # checks the DRG vocabulary.
26
27
  #
27
- # The deprecated drg operator selects the events of both systems.
28
+ # The deprecated drg operator selects the results of both systems.
28
29
  module DrgSystems
29
- # The first day of MS-DRG. ms_drg selects the events on or after this
30
- # day, and cms_drg the events before it.
30
+ # The first day of MS-DRG. ms_drg selects the results on or after this
31
+ # day, and cms_drg the results before it.
31
32
  MS_DRG_START_DATE = Date.new(2007, 10, 1)
32
33
 
33
34
  # The vocabulary and the operator that hold both systems.
@@ -35,15 +36,16 @@ module ConceptQL
35
36
  DRG_OPERATOR = "drg"
36
37
 
37
38
  DRG_DEPRECATION = "drg will become an error in a later release. A DRG code can have two meanings, " \
38
- "and drg selects the events of both. Use ms_drg for the MS-DRG meaning (events from " \
39
- "#{MS_DRG_START_DATE.iso8601}) or cms_drg for the CMS-DRG meaning (events before " \
39
+ "and drg selects the results of both. Use ms_drg for the MS-DRG meaning " \
40
+ "(discharges from #{MS_DRG_START_DATE.iso8601}) or cms_drg for the CMS-DRG " \
41
+ "meaning (discharges before " \
40
42
  "#{MS_DRG_START_DATE.iso8601}).".freeze
41
43
 
42
44
  # operator: the operator name. concept_class_id: the OHDSI concept class
43
45
  # of the system's meanings. from_cutover: true when the system starts on
44
46
  # MS_DRG_START_DATE, false when it ends the day before.
45
47
  System = Data.define(:operator, :name, :long_name, :concept_class_id, :from_cutover) do
46
- # The condition on the event's start date.
48
+ # The condition on the start date of a row.
47
49
  def date_condition(start_date_column)
48
50
  column = Sequel.identifier(start_date_column)
49
51
  from_cutover ? column >= MS_DRG_START_DATE : column < MS_DRG_START_DATE
@@ -52,11 +54,11 @@ module ConceptQL
52
54
 
53
55
  SYSTEMS = [
54
56
  System.new(operator: "ms_drg", name: "MS-DRG",
55
- long_name: "Medicare Severity Diagnosis-Related Group (CMS), events from " \
57
+ long_name: "Medicare Severity Diagnosis-Related Group (CMS), discharges from " \
56
58
  "#{MS_DRG_START_DATE.iso8601}",
57
59
  concept_class_id: "MS-DRG", from_cutover: true),
58
60
  System.new(operator: "cms_drg", name: "CMS-DRG",
59
- long_name: "CMS Diagnosis-Related Group, events before #{MS_DRG_START_DATE.iso8601}",
61
+ long_name: "CMS Diagnosis-Related Group, discharges before #{MS_DRG_START_DATE.iso8601}",
60
62
  concept_class_id: "DRG", from_cutover: false)
61
63
  ].to_h { |system| [ system.operator, system ] }.freeze
62
64
 
@@ -20,7 +20,7 @@ module ConceptQL
20
20
  module ReadCodes
21
21
  OPERATOR = "read"
22
22
  PREFERRED_NAME = "READ"
23
- DESC = "Selects records based on the Read vocabulary."
23
+ DESC = "Selects results based on the Read vocabulary."
24
24
 
25
25
  # The entry of read: the entry of the Read vocabulary with the preferred
26
26
  # name READ, as id => Entry. Without a Read entry there is none.
@@ -7,6 +7,11 @@ module ConceptQL
7
7
  # Provides a singleton method which will return a series of scope windows
8
8
  # that should be applied to each selection operator in a ConceptQL statement
9
9
  module Window
10
+ # The errors of the window options, as Query reports them on the window
11
+ # operator: [message, *details]
12
+ MISSING_DATE_ERROR = "date range needs start_date and end_date"
13
+ SCOPE_BY_ERROR = "scope_by must be start_date, end_date or date_range"
14
+
10
15
  class << self
11
16
  EVENT_DATE_COLUMNS = {
12
17
  nil => %i[start_date start_date],
@@ -19,6 +24,20 @@ module ConceptQL
19
24
  fetch_windows(prep_options(opts))
20
25
  end
21
26
 
27
+ # The errors of the window options: one of start_date and end_date
28
+ # without the other (the detail names the missing option), and a
29
+ # scope_by that is not a known value (the detail is the value). A
30
+ # scope_by of nil is the default, start_date.
31
+ def option_errors(opts)
32
+ dates = %i[start_date end_date]
33
+ given = dates.select { |date| opts[date] }
34
+ errors = []
35
+ errors << [ MISSING_DATE_ERROR, (dates - given).first.to_s ] if given.one?
36
+ scope_by = opts[:scope_by]
37
+ errors << [ SCOPE_BY_ERROR, scope_by.to_s ] unless EVENT_DATE_COLUMNS.key?(scope_by&.to_s&.to_sym)
38
+ errors
39
+ end
40
+
22
41
  def fetch_windows(opts)
23
42
  windows = []
24
43
 
@@ -58,8 +77,10 @@ module ConceptQL
58
77
  end
59
78
 
60
79
  def prep_options(opts)
61
- scope_by = opts.fetch(:scope_by, :start_date).to_sym
62
- raise "Unknown scope_by value #{scope_by.inspect}" unless EVENT_DATE_COLUMNS.key?(scope_by)
80
+ # Query refuses a statement with an unknown scope_by (option_errors),
81
+ # so this raise is an assertion.
82
+ scope_by = (opts[:scope_by] || :start_date).to_sym
83
+ raise "#{SCOPE_BY_ERROR}: #{scope_by.inspect}" unless EVENT_DATE_COLUMNS.key?(scope_by)
63
84
 
64
85
  start_col, end_col = *(EVENT_DATE_COLUMNS[scope_by])
65
86
  opts.merge(
data/schemas/gdm.yml CHANGED
@@ -814,69 +814,3 @@
814
814
  FK reference to [concepts](#concepts) table representing the type
815
815
  of admission the record is (Emergency, Elective, etc.)
816
816
  :foreign_key: concepts
817
- :concepts:
818
- :columns:
819
- :id:
820
- :type: :Bigint
821
- :primary_key: true
822
- :comment: Surrogate key for record (this is the concept_id)
823
- :null: false
824
- :vocabulary_id:
825
- :type: String
826
- :comment:
827
- FK reference to the vocabularies table for the vocabulary associated
828
- with the concept (see OMOP or UMLS)
829
- :foreign_key: vocabularies
830
- :null: false
831
- :concept_code:
832
- :type: String
833
- :comment:
834
- Actual code as text string from the source vocabulary (e.g., "410.00"
835
- for ICD-9)
836
- :null: false
837
- :concept_text:
838
- :type: String
839
- :comment: Text descriptor associated with the concept_code
840
- :null: false
841
- :vocabularies:
842
- :columns:
843
- :id:
844
- :type: String
845
- :primary_key: true
846
- :comment: Short name of the vocabulary which acts as a natural key for record
847
- :null: false
848
- :omopv4_vocabulary_id:
849
- :type: Integer
850
- :comment: Old ID used in OMOPv4
851
- :null: false
852
- :vocabulary_name:
853
- :type: String
854
- :comment: Full name of the vocabulary
855
- :null: false
856
- :domain:
857
- :type: String
858
- :comment: Domain to which the majority of the vocabulary is assigned
859
- :concepts_count:
860
- :type: Integer
861
- :comment:
862
- Number of row in the [concepts](#concepts) table assigned to this
863
- vocabulary
864
- :is_clinical_vocabulary:
865
- :type: TrueClass
866
- :comment: Are concepts from this vocabulary stored in [clinical_codes](#clinical_codes)?
867
- :mappings:
868
- :columns:
869
- :concept_1_id:
870
- :type: :Bigint
871
- :comment: FK reference to [concepts](#concepts) table for the source concept
872
- :foreign_key: concepts
873
- :null: false
874
- :relationship_id:
875
- :type: String
876
- :comment: The type or nature of the relationship (e.g., "is_a")
877
- :null: false
878
- :concept_2_id:
879
- :type: :Bigint
880
- :comment: FK reference to [concepts](#concepts) table for the destination concept
881
- :foreign_key: concepts
882
- :null: false
data/schemas/gdm_wide.yml CHANGED
@@ -689,69 +689,3 @@
689
689
  type (e.g., insurance coverage, hospital data, up-to-standard date)
690
690
  :foreign_key: concepts
691
691
  :null: false
692
- :concepts:
693
- :columns:
694
- :id:
695
- :type: :Bigint
696
- :primary_key: true
697
- :comment: Surrogate key for record (this is the concept_id)
698
- :null: false
699
- :vocabulary_id:
700
- :type: String
701
- :comment:
702
- FK reference to the vocabularies table for the vocabulary associated
703
- with the concept (see OMOP or UMLS)
704
- :foreign_key: vocabularies
705
- :null: false
706
- :concept_code:
707
- :type: String
708
- :comment:
709
- Actual code as text string from the source vocabulary (e.g., "410.00"
710
- for ICD-9)
711
- :null: false
712
- :concept_text:
713
- :type: String
714
- :comment: Text descriptor associated with the concept_code
715
- :null: false
716
- :vocabularies:
717
- :columns:
718
- :id:
719
- :type: String
720
- :primary_key: true
721
- :comment: Short name of the vocabulary which acts as a natural key for record
722
- :null: false
723
- :omopv4_vocabulary_id:
724
- :type: Integer
725
- :comment: Old ID used in OMOPv4
726
- :null: false
727
- :vocabulary_name:
728
- :type: String
729
- :comment: Full name of the vocabulary
730
- :null: false
731
- :domain:
732
- :type: String
733
- :comment: Domain to which the majority of the vocabulary is assigned
734
- :concepts_count:
735
- :type: Integer
736
- :comment:
737
- Number of row in the [concepts](#concepts) table assigned to this
738
- vocabulary
739
- :is_clinical_vocabulary:
740
- :type: TrueClass
741
- :comment: Are concepts from this vocabulary stored in [clinical_codes](#clinical_codes)?
742
- :mappings:
743
- :columns:
744
- :concept_1_id:
745
- :type: :Bigint
746
- :comment: FK reference to [concepts](#concepts) table for the source concept
747
- :foreign_key: concepts
748
- :null: false
749
- :relationship_id:
750
- :type: String
751
- :comment: The type or nature of the relationship (e.g., "is_a")
752
- :null: false
753
- :concept_2_id:
754
- :type: :Bigint
755
- :comment: FK reference to [concepts](#concepts) table for the destination concept
756
- :foreign_key: concepts
757
- :null: false
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: conceptql
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.0
4
+ version: 0.9.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ryan Duryea